Console Automation MCP Server

Production-Ready Model Context Protocol (MCP) server that enables AI assistants to fully interact with console applications, monitor output, detect errors, and automate terminal workflows - similar to how Playwright works for web browsers.

Production Status ✅

This server is fully production-ready with:

✅ No native compilation required (removed node-pty dependency)
✅ Full cross-platform support (Windows, macOS, Linux)
✅ Streaming support for long-running processes
✅ Multiple console type support (cmd, PowerShell, bash, zsh, sh)
✅ Resource management and automatic cleanup
✅ Comprehensive error handling and recovery
✅ Easy installation scripts for all major MCP clients
✅ All tests passing (see test-functionality.js)

Features

🚀 Core Capabilities

Full Terminal Control: Create and manage up to 50 concurrent console sessions
Multi-Protocol Support: Local shells (cmd, PowerShell, pwsh, bash, zsh, sh) and remote SSH connections
Interactive Input: Send text input and special key sequences (Enter, Tab, Ctrl+C, etc.)
Real-time Output Monitoring: Capture, filter, and analyze console output with advanced search
Streaming Support: Efficient streaming for long-running processes with pattern matching
Automatic Error Detection: Built-in patterns to detect errors, exceptions, and stack traces across languages
Cross-platform: Works on Windows, macOS, and Linux without native dependencies

🔐 SSH & Remote Connections

Full SSH Support: Password and key-based authentication with passphrase support
SSH Options: Custom ports, connection timeouts, keep-alive settings
Connection Profiles: Save and reuse SSH configurations for quick access
Cloud Platform Support: Azure, AWS, GCP, Kubernetes connections via saved profiles
Container Support: Docker and WSL integration for containerized workflows

✅ Test Automation Framework

Automated Test Cases: Built-in assertion tools for console output validation
Output Assertions: Verify output contains, matches regex, or equals expected values
Exit Code Validation: Assert command exit codes for success/failure detection
Error-Free Validation: Automatically check for errors in command output
State Snapshots: Save and compare session states before/after operations
Test Workflows: Chain assertions for comprehensive testing scenarios

🔄 Background Job Execution

Async Command Execution: Run long-running commands in background with full output capture
Priority Queue System: Prioritize jobs (1-10 scale) for optimal resource utilization
Job Monitoring: Track status, progress, and completion of background jobs
Job Control: Cancel, pause, or resume background operations
Result Retrieval: Get complete output and exit codes from completed jobs
Resource Management: Automatic cleanup of completed jobs with configurable retention

📊 Enterprise Monitoring & Alerts

System-Wide Metrics: CPU, memory, disk, and network usage tracking
Session Metrics: Per-session performance monitoring and resource consumption
Real-time Dashboards: Live monitoring data with customizable views
Alert System: Performance, error, security, and anomaly alerts with severity levels
Custom Monitoring: Configure monitoring intervals, metrics, and thresholds per session
Diagnostics: Built-in error analysis and session health validation

📁 Profile Management

Connection Profiles: Save SSH, Docker, WSL, and cloud platform connections
Application Profiles: Store common command configurations (Node.js, Python, .NET, Java, Go, Rust)
Quick Connect: Instantly connect using saved profiles with override support
Environment Variables: Store environment configurations per profile
Working Directory Management: Set default directories for each profile

🔍 Advanced Output Processing

Regex Filtering: Search output with regular expressions (case-sensitive/insensitive)
Multi-Pattern Search: Combine multiple patterns with AND/OR logic
Pagination: Get specific line ranges, head, or tail of output
Time-based Filtering: Filter output by timestamp (absolute or relative: '5m', '1h', '2d')
Output Streaming: Real-time output capture for long-running processes
Buffer Management: Clear output buffers to reduce memory usage

Quick Installation

Windows (PowerShell as Administrator)

git clone https://github.com/ooples/console-automation-mcp.git
cd console-automation-mcp
.\install.ps1 -Target claude  # or google, openai, custom, all

macOS/Linux

git clone https://github.com/ooples/console-automation-mcp.git
cd console-automation-mcp
chmod +x install.sh
./install.sh --target claude  # or google, openai, custom, all

Manual Installation

git clone https://github.com/ooples/console-automation-mcp.git
cd console-automation-mcp
npm install --production
npm run build

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "console-automation": {
      "command": "npx",
      "args": ["@mcp/console-automation"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

For other MCP clients

# Start the server with new name
console-automation-mcp --log-level info

# Or with backward compatible name
mcp-console --log-level info

# Or with npx
npx console-automation-mcp --log-level info

Available Tools (40 Total)

This MCP server provides 40 comprehensive tools organized into 6 categories:

📚 Complete Documentation

Complete Tools Reference - Detailed documentation for all 40 tools
Practical Examples - Real-world usage examples and patterns
Publishing Guide - How to list this server in registries

Tool Categories

🖥️ Session Management (9 tools)

console_create_session - Create local or SSH console sessions
console_send_input - Send text input to sessions
console_send_key - Send special keys (Enter, Ctrl+C, etc.)
console_get_output - Get filtered/paginated output with advanced search
console_get_stream - Stream output from long-running processes
console_wait_for_output - Wait for specific patterns
console_stop_session - Stop sessions
console_list_sessions - List all active sessions
console_cleanup_sessions - Clean up inactive sessions

⚡ Command Execution (6 tools)

console_execute_command - Execute commands with output capture
console_detect_errors - Analyze output for errors
console_get_resource_usage - Get system resource stats
console_clear_output - Clear output buffers
console_get_session_state - Get session execution state
console_get_command_history - View command history

📊 Monitoring & Alerts (6 tools)

console_get_system_metrics - Comprehensive system metrics
console_get_session_metrics - Session-specific metrics
console_get_alerts - Active monitoring alerts
console_get_monitoring_dashboard - Real-time dashboard data
console_start_monitoring - Start custom monitoring
console_stop_monitoring - Stop monitoring

📁 Profile Management (4 tools)

console_save_profile - Save SSH/app connection profiles
console_list_profiles - List saved profiles
console_remove_profile - Remove profiles
console_use_profile - Quick connect with saved profiles

🔄 Background Jobs (9 tools)

console_execute_async - Execute commands asynchronously
console_get_job_status - Check job status
console_get_job_output - Get job output
console_cancel_job - Cancel running jobs
console_list_jobs - List all background jobs
console_get_job_progress - Monitor job progress
console_get_job_result - Get complete job results
console_get_job_metrics - Job execution statistics
console_cleanup_jobs - Clean up completed jobs

✅ Test Automation (6 tools)

console_assert_output - Assert output matches criteria
console_assert_exit_code - Assert exit codes
console_assert_no_errors - Verify no errors occurred
console_save_snapshot - Save session state snapshots
console_compare_snapshots - Compare state differences
console_assert_state - Assert session state

Quick Start Examples

Create a Local Session

const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

Connect via SSH

const session = await console_create_session({
  command: "bash",
  consoleType: "ssh",
  sshOptions: {
    host: "example.com",
    username: "user",
    privateKeyPath: "~/.ssh/id_rsa"
  }
});

Run Tests with Assertions

const session = await console_create_session({
  command: "npm",
  args: ["test"]
});

await console_assert_output({
  sessionId: session.sessionId,
  assertionType: "contains",
  expected: "All tests passed"
});

Background Job Execution

const job = await console_execute_async({
  sessionId: session.sessionId,
  command: "npm run build",
  priority: 8
});

const status = await console_get_job_status({
  jobId: job.jobId
});

For more examples, see docs/EXAMPLES.md

Use Cases

1. Running and monitoring a development server

// Create a session for the dev server
const session = await console_create_session({
  command: "npm",
  args: ["run", "dev"],
  detectErrors: true
});

// Wait for server to start
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Server running on",
  timeout: 10000
});

// Monitor for errors
const errors = await console_detect_errors({
  sessionId: session.sessionId
});

2. Interactive debugging session

// Start a Python debugging session
const session = await console_create_session({
  command: "python",
  args: ["-m", "pdb", "script.py"]
});

// Set a breakpoint
await console_send_input({
  sessionId: session.sessionId,
  input: "b main\n"
});

// Continue execution
await console_send_input({
  sessionId: session.sessionId,
  input: "c\n"
});

// Step through code
await console_send_key({
  sessionId: session.sessionId,
  key: "n"
});

3. Automated testing with error detection

// Run tests
const result = await console_execute_command({
  command: "pytest",
  args: ["tests/"],
  timeout: 30000
});

// Check for test failures
const errors = await console_detect_errors({
  text: result.output
});

if (errors.hasErrors) {
  console.log("Test failures detected:", errors);
}

4. Interactive CLI tool automation

// Start an interactive CLI tool
const session = await console_create_session({
  command: "mysql",
  args: ["-u", "root", "-p"]
});

// Enter password
await console_wait_for_output({
  sessionId: session.sessionId,
  pattern: "Enter password:"
});

await console_send_input({
  sessionId: session.sessionId,
  input: "mypassword\n"
});

// Run SQL commands
await console_send_input({
  sessionId: session.sessionId,
  input: "SHOW DATABASES;\n"
});

Error Detection Patterns

The server includes built-in patterns for detecting common error types:

Generic errors (error:, ERROR:, Error:)
Exceptions (Exception:, exception)
Warnings (Warning:, WARNING:)
Fatal

…

Console Automation

Installation

Configuration

How to use

README