Console Automation

Model Context Protocol (MCP) server for controlled interaction with local console applications and remote SSH sessions, including output monitoring, error detection, and long-running workflows.

This server can execute arbitrary commands and open remote SSH sessions. Treat it like a privileged terminal, not a low-risk documentation connector:

- keep MCP tool approvals enabled for command/session mutations;
- prefer SSH keys or environment-variable credential references over inline secrets;
- use a restricted deployment account and a separate production approval step;
- leaveMCP_DEBUG_LOGandMCP_LOG_DIRunset unless diagnostics are explicitly required;
- leave session persistence disabled unless recovery metadata is explicitly required;
- install cloud, container, and serial integrations only when needed.

- 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

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

- 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

- 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

- 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

- 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

- 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

git clone https://github.com/ooples/mcp-console-automation.git cd mcp-console-automation .\install.ps1 -Target codex

git clone https://github.com/ooples/mcp-console-automation.git cd mcp-console-automation chmod +x install.sh ./install.sh --target codex

git clone https://github.com/ooples/mcp-console-automation.git cd mcp-console-automation npm ci npm run build codex mcp add console-automation --env LOG_LEVEL=warn -- node "$PWD/dist/mcp/server.js"

Codex stores MCP configuration in~/.codex/config.toml. The installers usecodex mcp addand safely replace an existingconsole-automationregistration. Restart Codex after installation and use/mcpto verify the connection.

For another MCP client, generate a new JSON configuration without overwriting an existing file:

.\install.ps1 -Target custom -CustomPath C:\path\to\new-mcp-config.json

The npm package has not been published, sonpx console-automation-mcpand@mcp/console-automationare not valid installation paths.

console_save_profilerejects inline passwords, private-key material, and passphrases. UsepasswordEnvVar,privateKeyEnvVarorprivateKeyPath, andpassphraseEnvVar. Profile-list responses never return credential values, and configuration files are created with owner-only permissions where the operating system supports POSIX modes.

Session persistence is disabled by default because session recovery data can include commands, paths, and environment values. To opt in, setMCP_SESSION_PERSISTENCE=true. The default file is~/.console-automation-mcp/sessions.json; override it withMCP_SESSION_PERSISTENCE_PATH. Persisted command/environment recovery data remains disabled unless enabled through the programmaticSessionManagerconfiguration.

The production installers remove development and optional protocol packages. Local consoles and SSH remain available. Install only the peer packages required for Docker, cloud, Kubernetes, serial, or other optional adapters.

This MCP server provides40 comprehensive toolsorganized into 6 categories:

- 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

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

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

const session = await console_create_session({ command: "npm", args: ["test"] }); await console_assert_output({ sessionId: session.sessionId, assertionType: "contains", expected: "All tests passed" });

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 });

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 });

// 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); }

// 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" });

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

- Generic errors (error:, ERROR:, Error:)
- Exceptions (Exception:, exception)
- Warnings (Warning:, WARNING:)
- Fatal errors
- Failed operations
- Permission/access denied
- Timeouts
- Stack traces (Python, Java, Node.js)
- Compilation errors
- Syntax errors
- Memory errors
- Connection errors

- Node child processes and ssh2: For local command execution and SSH sessions
- @modelcontextprotocol/sdk: MCP protocol implementation
- TypeScript: For type safety and better developer experience
- Winston: For structured logging
- ConsoleManager: Manages terminal sessions, input/output, and lifecycle
- ErrorDetector: Analyzes output for errors and exceptions
- MCP Server: Exposes console functionality through MCP tools
- Session Management: Handles multiple concurrent console sessions

- Node.js >= 18.0.0
- Windows, macOS, or Linux operating system
- Optional serial-port integrations can require platform build tools.

Run static validation, the build, MCP smoke tests, and the test suite:

npm run lint npm run typecheck npm run build npm run test:mcp npm run test:logger npm run test:installer npm run test:package npm test

- Permission denied errors: Ensure the server has permission to spawn processes
- Optional native dependency errors: Install platform build tools only when enabling serial-port integrations
- Session not responding: Check if the command requires TTY interaction
- Output not captured: Some applications may write directly to terminal, bypassing stdout

Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (git checkout -b feature/AmazingFeature)
- Commit your changes (git commit -m 'Add some AmazingFeature')
- Push to the branch (git push origin feature/AmazingFeature)
- Open a Pull Request

MIT License - see LICENSE file for details

For issues, questions, or suggestions, please open an issue on GitHub:https://github.com/ooples/mcp-console-automation/issues

-

A comprehensive MCP server for configuring and managing Cisco ACI (Application Centric Infrastructure) fabrics through the APIC REST API.