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. This server is fully production-ready with: - ✅ No native compilation required (removed node-pty dependency) - ✅ Full cross-platform support (Windows, macOS, Li
Add this skill
npx mdskills install ooples/mcp-console-automationComprehensive terminal automation with 40 tools, SSH support, and monitoring capabilities
1# Console Automation MCP Server23**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.45[](https://github.com/ooples/console-automation-mcp)6[](LICENSE)7[](https://nodejs.org)89## Production Status ✅1011This server is **fully production-ready** with:12- ✅ No native compilation required (removed node-pty dependency)13- ✅ Full cross-platform support (Windows, macOS, Linux)14- ✅ Streaming support for long-running processes15- ✅ Multiple console type support (cmd, PowerShell, bash, zsh, sh)16- ✅ Resource management and automatic cleanup17- ✅ Comprehensive error handling and recovery18- ✅ Easy installation scripts for all major MCP clients19- ✅ All tests passing (see test-functionality.js)2021## Features2223### 🚀 Core Capabilities2425- **Full Terminal Control**: Create and manage up to 50 concurrent console sessions26- **Multi-Protocol Support**: Local shells (cmd, PowerShell, pwsh, bash, zsh, sh) and remote SSH connections27- **Interactive Input**: Send text input and special key sequences (Enter, Tab, Ctrl+C, etc.)28- **Real-time Output Monitoring**: Capture, filter, and analyze console output with advanced search29- **Streaming Support**: Efficient streaming for long-running processes with pattern matching30- **Automatic Error Detection**: Built-in patterns to detect errors, exceptions, and stack traces across languages31- **Cross-platform**: Works on Windows, macOS, and Linux without native dependencies3233### 🔐 SSH & Remote Connections3435- **Full SSH Support**: Password and key-based authentication with passphrase support36- **SSH Options**: Custom ports, connection timeouts, keep-alive settings37- **Connection Profiles**: Save and reuse SSH configurations for quick access38- **Cloud Platform Support**: Azure, AWS, GCP, Kubernetes connections via saved profiles39- **Container Support**: Docker and WSL integration for containerized workflows4041### ✅ Test Automation Framework4243- **Automated Test Cases**: Built-in assertion tools for console output validation44- **Output Assertions**: Verify output contains, matches regex, or equals expected values45- **Exit Code Validation**: Assert command exit codes for success/failure detection46- **Error-Free Validation**: Automatically check for errors in command output47- **State Snapshots**: Save and compare session states before/after operations48- **Test Workflows**: Chain assertions for comprehensive testing scenarios4950### 🔄 Background Job Execution5152- **Async Command Execution**: Run long-running commands in background with full output capture53- **Priority Queue System**: Prioritize jobs (1-10 scale) for optimal resource utilization54- **Job Monitoring**: Track status, progress, and completion of background jobs55- **Job Control**: Cancel, pause, or resume background operations56- **Result Retrieval**: Get complete output and exit codes from completed jobs57- **Resource Management**: Automatic cleanup of completed jobs with configurable retention5859### 📊 Enterprise Monitoring & Alerts6061- **System-Wide Metrics**: CPU, memory, disk, and network usage tracking62- **Session Metrics**: Per-session performance monitoring and resource consumption63- **Real-time Dashboards**: Live monitoring data with customizable views64- **Alert System**: Performance, error, security, and anomaly alerts with severity levels65- **Custom Monitoring**: Configure monitoring intervals, metrics, and thresholds per session66- **Diagnostics**: Built-in error analysis and session health validation6768### 📁 Profile Management6970- **Connection Profiles**: Save SSH, Docker, WSL, and cloud platform connections71- **Application Profiles**: Store common command configurations (Node.js, Python, .NET, Java, Go, Rust)72- **Quick Connect**: Instantly connect using saved profiles with override support73- **Environment Variables**: Store environment configurations per profile74- **Working Directory Management**: Set default directories for each profile7576### 🔍 Advanced Output Processing7778- **Regex Filtering**: Search output with regular expressions (case-sensitive/insensitive)79- **Multi-Pattern Search**: Combine multiple patterns with AND/OR logic80- **Pagination**: Get specific line ranges, head, or tail of output81- **Time-based Filtering**: Filter output by timestamp (absolute or relative: '5m', '1h', '2d')82- **Output Streaming**: Real-time output capture for long-running processes83- **Buffer Management**: Clear output buffers to reduce memory usage8485## Quick Installation8687### Windows (PowerShell as Administrator)88```powershell89git clone https://github.com/ooples/console-automation-mcp.git90cd console-automation-mcp91.\install.ps1 -Target claude # or google, openai, custom, all92```9394### macOS/Linux95```bash96git clone https://github.com/ooples/console-automation-mcp.git97cd console-automation-mcp98chmod +x install.sh99./install.sh --target claude # or google, openai, custom, all100```101102### Manual Installation103```bash104git clone https://github.com/ooples/console-automation-mcp.git105cd console-automation-mcp106npm install --production107npm run build108```109110## Configuration111112### For Claude Desktop113114Add to your Claude Desktop configuration file:115116**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`117**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`118**Linux**: `~/.config/Claude/claude_desktop_config.json`119120```json121{122 "mcpServers": {123 "console-automation": {124 "command": "npx",125 "args": ["@mcp/console-automation"],126 "env": {127 "LOG_LEVEL": "info"128 }129 }130 }131}132```133134### For other MCP clients135136```bash137# Start the server with new name138console-automation-mcp --log-level info139140# Or with backward compatible name141mcp-console --log-level info142143# Or with npx144npx console-automation-mcp --log-level info145```146147## Available Tools (40 Total)148149This MCP server provides **40 comprehensive tools** organized into 6 categories:150151### 📚 Complete Documentation152153- **[Complete Tools Reference](docs/TOOLS.md)** - Detailed documentation for all 40 tools154- **[Practical Examples](docs/EXAMPLES.md)** - Real-world usage examples and patterns155- **[Publishing Guide](PUBLISHING.md)** - How to list this server in registries156157### Tool Categories158159#### 🖥️ Session Management (9 tools)160- `console_create_session` - Create local or SSH console sessions161- `console_send_input` - Send text input to sessions162- `console_send_key` - Send special keys (Enter, Ctrl+C, etc.)163- `console_get_output` - Get filtered/paginated output with advanced search164- `console_get_stream` - Stream output from long-running processes165- `console_wait_for_output` - Wait for specific patterns166- `console_stop_session` - Stop sessions167- `console_list_sessions` - List all active sessions168- `console_cleanup_sessions` - Clean up inactive sessions169170#### ⚡ Command Execution (6 tools)171- `console_execute_command` - Execute commands with output capture172- `console_detect_errors` - Analyze output for errors173- `console_get_resource_usage` - Get system resource stats174- `console_clear_output` - Clear output buffers175- `console_get_session_state` - Get session execution state176- `console_get_command_history` - View command history177178#### 📊 Monitoring & Alerts (6 tools)179- `console_get_system_metrics` - Comprehensive system metrics180- `console_get_session_metrics` - Session-specific metrics181- `console_get_alerts` - Active monitoring alerts182- `console_get_monitoring_dashboard` - Real-time dashboard data183- `console_start_monitoring` - Start custom monitoring184- `console_stop_monitoring` - Stop monitoring185186#### 📁 Profile Management (4 tools)187- `console_save_profile` - Save SSH/app connection profiles188- `console_list_profiles` - List saved profiles189- `console_remove_profile` - Remove profiles190- `console_use_profile` - Quick connect with saved profiles191192#### 🔄 Background Jobs (9 tools)193- `console_execute_async` - Execute commands asynchronously194- `console_get_job_status` - Check job status195- `console_get_job_output` - Get job output196- `console_cancel_job` - Cancel running jobs197- `console_list_jobs` - List all background jobs198- `console_get_job_progress` - Monitor job progress199- `console_get_job_result` - Get complete job results200- `console_get_job_metrics` - Job execution statistics201- `console_cleanup_jobs` - Clean up completed jobs202203#### ✅ Test Automation (6 tools)204- `console_assert_output` - Assert output matches criteria205- `console_assert_exit_code` - Assert exit codes206- `console_assert_no_errors` - Verify no errors occurred207- `console_save_snapshot` - Save session state snapshots208- `console_compare_snapshots` - Compare state differences209- `console_assert_state` - Assert session state210211### Quick Start Examples212213#### Create a Local Session214```javascript215const session = await console_create_session({216 command: "npm",217 args: ["run", "dev"],218 detectErrors: true219});220```221222#### Connect via SSH223```javascript224const session = await console_create_session({225 command: "bash",226 consoleType: "ssh",227 sshOptions: {228 host: "example.com",229 username: "user",230 privateKeyPath: "~/.ssh/id_rsa"231 }232});233```234235#### Run Tests with Assertions236```javascript237const session = await console_create_session({238 command: "npm",239 args: ["test"]240});241242await console_assert_output({243 sessionId: session.sessionId,244 assertionType: "contains",245 expected: "All tests passed"246});247```248249#### Background Job Execution250```javascript251const job = await console_execute_async({252 sessionId: session.sessionId,253 command: "npm run build",254 priority: 8255});256257const status = await console_get_job_status({258 jobId: job.jobId259});260```261262For more examples, see [docs/EXAMPLES.md](docs/EXAMPLES.md)263264## Use Cases265266### 1. Running and monitoring a development server267```javascript268// Create a session for the dev server269const session = await console_create_session({270 command: "npm",271 args: ["run", "dev"],272 detectErrors: true273});274275// Wait for server to start276await console_wait_for_output({277 sessionId: session.sessionId,278 pattern: "Server running on",279 timeout: 10000280});281282// Monitor for errors283const errors = await console_detect_errors({284 sessionId: session.sessionId285});286```287288### 2. Interactive debugging session289```javascript290// Start a Python debugging session291const session = await console_create_session({292 command: "python",293 args: ["-m", "pdb", "script.py"]294});295296// Set a breakpoint297await console_send_input({298 sessionId: session.sessionId,299 input: "b main\n"300});301302// Continue execution303await console_send_input({304 sessionId: session.sessionId,305 input: "c\n"306});307308// Step through code309await console_send_key({310 sessionId: session.sessionId,311 key: "n"312});313```314315### 3. Automated testing with error detection316```javascript317// Run tests318const result = await console_execute_command({319 command: "pytest",320 args: ["tests/"],321 timeout: 30000322});323324// Check for test failures325const errors = await console_detect_errors({326 text: result.output327});328329if (errors.hasErrors) {330 console.log("Test failures detected:", errors);331}332```333334### 4. Interactive CLI tool automation335```javascript336// Start an interactive CLI tool337const session = await console_create_session({338 command: "mysql",339 args: ["-u", "root", "-p"]340});341342// Enter password343await console_wait_for_output({344 sessionId: session.sessionId,345 pattern: "Enter password:"346});347348await console_send_input({349 sessionId: session.sessionId,350 input: "mypassword\n"351});352353// Run SQL commands354await console_send_input({355 sessionId: session.sessionId,356 input: "SHOW DATABASES;\n"357});358```359360## Error Detection Patterns361362The server includes built-in patterns for detecting common error types:363364- Generic errors (error:, ERROR:, Error:)365- Exceptions (Exception:, exception)366- Warnings (Warning:, WARNING:)367- Fatal errors368- Failed operations369- Permission/access denied370- Timeouts371- Stack traces (Python, Java, Node.js)372- Compilation errors373- Syntax errors374- Memory errors375- Connection errors376377## Development378379### Building from source380```bash381npm install382npm run build383```384385### Running in development mode386```bash387npm run dev388```389390### Running tests391```bash392npm test393```394395### Type checking396```bash397npm run typecheck398```399400### Linting401```bash402npm run lint403```404405## Architecture406407The server is built with:408- **node-pty**: For creating and managing pseudo-terminals409- **@modelcontextprotocol/sdk**: MCP protocol implementation410- **TypeScript**: For type safety and better developer experience411- **Winston**: For structured logging412413### Core Components4144151. **ConsoleManager**: Manages terminal sessions, input/output, and lifecycle4162. **ErrorDetector**: Analyzes output for errors and exceptions4173. **MCP Server**: Exposes console functionality through MCP tools4184. **Session Management**: Handles multiple concurrent console sessions419420## Requirements421422- Node.js >= 18.0.0423- Windows, macOS, or Linux operating system424- No additional build tools required!425426## Testing427428Run the included test suite to verify functionality:429```bash430node test-functionality.js431```432433## Troubleshooting434435### Common Issues4364371. **Permission denied errors**: Ensure the server has permission to spawn processes4382. **node-pty compilation errors**: Install build tools for your platform4393. **Session not responding**: Check if the command requires TTY interaction4404. **Output not captured**: Some applications may write directly to terminal, bypassing stdout441442## Contributing443444Contributions are welcome! Please feel free to submit a Pull Request.4454461. Fork the repository4472. Create your feature branch (`git checkout -b feature/AmazingFeature`)4483. Commit your changes (`git commit -m 'Add some AmazingFeature'`)4494. Push to the branch (`git push origin feature/AmazingFeature`)4505. Open a Pull Request451452## License453454MIT License - see LICENSE file for details455456## Support457458For issues, questions, or suggestions, please open an issue on GitHub:459https://github.com/ooples/console-automation-mcp/issues460461## Roadmap462463- [ ] Add support for terminal recording and playback464- [ ] Implement session persistence and recovery465- [ ] Add more error detection patterns for specific languages466- [ ] Support for terminal multiplexing (tmux/screen integration)467- [ ] Web-based terminal viewer468- [ ] Session sharing and collaboration features469- [ ] Performance profiling tools470- [ ] Integration with popular CI/CD systems471
Full transparency — inspect the skill content before installing.