{ "markdown": "\n\n

\n \"terminal-mcp\n

\n\n

Give your AI a real terminal. Persistent sessions. Interactive programs. Zero limitations.

\n\n

\n \"PyPI\"/\n \"Python\n \"License:\n \"CI\"/\n \"CodeQL\"/\n

\n\n

\n \"Install\n \"Install\n \"Install\n \"Install\n

\n\n

\n \"terminal-mcp\n

\n\n---\n\n## The Problem\n\nEvery AI coding tool hits the same wall: **no real terminal access**.\n\nClaude Code's Bash tool, GitHub Copilot, and Codex all run commands in isolated subprocesses. Each command starts fresh. No state carries over. That means:\n\n- **No SSH sessions** - Can't connect to a remote server and run multiple commands\n- **No REPLs** - Can't use Python, Node, or Ruby interpreters interactively\n- **No database CLIs** - Can't maintain a psql, mysql, or redis-cli connection\n- **No TUI apps** - Can't navigate htop, vim, or fzf with arrow keys\n- **No long-running processes** - Can't monitor builds, watch logs, or run dev servers\n\n## The Solution\n\n**terminal-mcp** gives AI agents a real terminal. Persistent PTY sessions that survive across tool calls. Send commands, read output, press keys, navigate TUIs - exactly like a human at a terminal.\n\n```\nuvx terminal-mcp\n```\n\nOne command. Works with Claude Code, Claude Desktop, VS Code, Cursor, and Windsurf.\n\n---\n\n## Quick Start\n\n### 1. Install (30 seconds)\n\n```bash\n# No install needed - run directly\nuvx terminal-mcp\n\n# Or install globally\npip install terminal-mcp\n```\n\n### 2. Connect to Your AI Client\n\n
\nClaude Code\n\nAdd to `~/.claude.json` or project `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"uvx\",\n \"args\": [\"terminal-mcp\"]\n }\n }\n}\n```\n\n
\n\n
\nClaude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"uvx\",\n \"args\": [\"terminal-mcp\"]\n }\n }\n}\n```\n\n
\n\n
\nVS Code / Cursor\n\nClick the one-click install badge above, or add to `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"terminal-mcp\": {\n \"command\": \"uvx\",\n \"args\": [\"terminal-mcp\"]\n }\n }\n}\n```\n\n
\n\n
\nWindsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"uvx\",\n \"args\": [\"terminal-mcp\"]\n }\n }\n}\n```\n\n
\n\n### 3. Verify\n\n```\nsession_exec exec=\"echo hello from terminal-mcp\"\n```\n\n---\n\n## What Can You Do With It?\n\n### SSH Into Remote Servers\n\n```\nsession_create command=\"ssh user@prod-server.com\" label=\"prod\"\nsession_interact session_id=\"a1b2c3d4\" input=\"df -h\" wait_for=\"\\$\"\nsession_interact session_id=\"a1b2c3d4\" input=\"docker ps\" wait_for=\"\\$\"\nsession_close session_id=\"a1b2c3d4\"\n```\n\n### Run Interactive REPLs\n\n```\nsession_create command=\"python3\" label=\"python\"\nsession_interact session_id=\"e5f6g7h8\" input=\"import pandas as pd\" wait_for=\">>>\"\nsession_interact session_id=\"e5f6g7h8\" input=\"df = pd.read_csv('data.csv')\" wait_for=\">>>\"\nsession_interact session_id=\"e5f6g7h8\" input=\"df.describe()\" wait_for=\">>>\"\nsession_close session_id=\"e5f6g7h8\"\n```\n\n### Query Databases\n\n```\nsession_create command=\"psql -U admin mydb\" label=\"db\"\nsession_interact session_id=\"x1y2z3w4\" input=\"SELECT count(*) FROM users;\" wait_for=\"row\"\nsession_interact session_id=\"x1y2z3w4\" input=\"\\dt\" wait_for=\"#\"\nsession_close session_id=\"x1y2z3w4\"\n```\n\n### Navigate TUI Apps\n\n```\nsession_create command=\"htop\" label=\"monitor\"\nsession_read session_id=\"a1b2c3d4\"\n# Auto-detects TUI, returns screen snapshot\n\nsession_send session_id=\"a1b2c3d4\" key=\"F6\"\nsession_read session_id=\"a1b2c3d4\" mode=\"diff\"\n# Returns only changed lines - saves tokens\n\nsession_send session_id=\"a1b2c3d4\" key=\"F10\"\nsession_close session_id=\"a1b2c3d4\"\n```\n\n### Monitor Long-Running Builds\n\n```\nsession_create command=\"bash\" label=\"build\"\nsession_send session_id=\"a1b2c3d4\" input=\"npm run build\"\nsession_wait_for session_id=\"a1b2c3d4\" pattern=\"Build complete|ERROR\" timeout=120\n```\n\n### Run One-Off Commands\n\n```\nsession_exec exec=\"git log --oneline -10\"\nsession_exec exec=\"docker compose ps\" timeout=10\n```\n\n---\n\n## Features at a Glance\n\n| Feature | What It Does |\n|---------|-------------|\n| **Persistent Sessions** | Real PTY sessions that survive across tool calls |\n| **Send + Read in One Call** | `session_interact` halves LLM round trips |\n| **Pattern-Based Reads** | `wait_for` blocks until regex matches - no guessing timeouts |\n| **Auto TUI Detection** | Detects htop, vim, etc. and auto-switches to screen snapshot mode |\n| **Output Diff Mode** | Returns only changed screen lines - minimizes tokens |\n| **Special Keys** | Arrow keys, Tab, F1-F12, Home/End, Page Up/Down |\n| **Control Characters** | Ctrl-C, Ctrl-D, Ctrl-Z, Ctrl-L, telnet escape |\n| **Dangerous Command Gate** | Blocks `rm -rf`, `DROP TABLE`, `curl\\|sh` - requires confirmation |\n| **OSC 133 Shell Integration** | Auto-detects command boundaries and exit codes |\n| **Smart Truncation** | Four strategies to prevent context overflow |\n| **Secret Input** | Send passwords without logging |\n| **Dynamic Resize** | Resize terminal on the fly with SIGWINCH |\n| **Idle Cleanup** | Auto-closes idle sessions |\n| **Cross-Platform** | Linux, macOS, and Windows support |\n\n---\n\n## Tools Reference\n\nterminal-mcp exposes **9 MCP tools**. Full details in [docs/tools.md](docs/tools.md).\n\n| Tool | Purpose |\n|------|---------|\n| [`session_create`](docs/tools.md#session_create) | Spawn a persistent terminal session |\n| [`session_send`](docs/tools.md#session_send) | Send text, keys, or control characters |\n| [`session_read`](docs/tools.md#session_read) | Read output (stream, snapshot, auto, diff modes) |\n| [`session_interact`](docs/tools.md#session_interact) | Send + read in one call |\n| [`session_wait_for`](docs/tools.md#session_wait_for) | Wait for regex pattern in output |\n| [`session_exec`](docs/tools.md#session_exec) | One-shot command execution |\n| [`session_close`](docs/tools.md#session_close) | Close a session gracefully |\n| [`session_resize`](docs/tools.md#session_resize) | Resize terminal dimensions |\n| [`session_list`](docs/tools.md#session_list) | List active sessions |\n\n---\n\n## Architecture\n\n```mermaid\nflowchart LR\n Client[AI Client] -->|MCP JSON-RPC| Server[terminal-mcp]\n Server --> SM[Session Manager]\n SM --> S1[PTY 1: bash]\n SM --> S2[PTY 2: python3]\n SM --> S3[PTY 3: ssh user@host]\n S1 & S2 & S3 -.->|PTY output| Reader[Reader Thread]\n Reader -.->|buffer| Server\n```\n\nEach session is backed by a real PTY via `pexpect.spawn` (or `PopenSpawn` on Windows). For full architecture details, see [docs/architecture.md](docs/architecture.md).\n\n---\n\n## Configuration\n\nAll settings configurable via `TERMINAL_MCP_*` environment variables. Full reference in [docs/configuration.md](docs/configuration.md).\n\n| Setting | Env Var | Default |\n|---------|---------|---------|\n| Max sessions | `TERMINAL_MCP_MAX_SESSIONS` | `10` |\n| Idle timeout | `TERMINAL_MCP_IDLE_TIMEOUT` | `1800` (30 min) |\n| Safety gate | `TERMINAL_MCP_SAFETY_GATE` | `on` |\n| Buffer cap | `TERMINAL_MCP_MAX_BUFFER_BYTES` | `1000000` (1MB) |\n| Truncation | `TERMINAL_MCP_TRUNCATION_MODE` | `tail` |\n\nExample with custom settings:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"uvx\",\n \"args\": [\"terminal-mcp\"],\n \"env\": {\n \"TERMINAL_MCP_MAX_SESSIONS\": \"20\",\n \"TERMINAL_MCP_IDLE_TIMEOUT\": \"3600\",\n \"TERMINAL_MCP_TRUNCATION_MODE\": \"head_tail\"\n }\n }\n }\n}\n```\n\n---\n\n## Documentation\n\n| Document | Description |\n|----------|-------------|\n| [Tools Reference](docs/tools.md) | Complete API for all 9 MCP tools |\n| [Architecture](docs/architecture.md) | How terminal-mcp works under the hood |\n| [Configuration](docs/configuration.md) | All settings and environment variables |\n| [Safety & Security](docs/safety.md) | Dangerous command detection and safety gate |\n| [Use Cases & Examples](docs/examples.md) | Real-world recipes and patterns |\n| [Changelog](docs/changelog.md) | Version history and release notes |\n| [Contributing](docs/contributing.md) | How to contribute |\n\n---\n\n## Supported Clients\n\n| Client | Status | Install |\n|--------|--------|---------|\n| **Claude Code** (CLI) | Supported | `~/.claude.json` or `.mcp.json` |\n| **Claude Desktop** | Supported | [One-click install](#install-in-claude-desktop) |\n| **VS Code** (Copilot Chat) | Supported | [One-click install](https://insiders.vscode.dev/redirect/mcp/install?name=terminal-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22terminal-mcp%22%5D%7D) or `.vscode/mcp.json` |\n| **Cursor** | Supported | [One-click install](cursor://anysphere.cursor-mcp/install?name=terminal-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ0ZXJtaW5hbC1tY3AiXX0=) or Settings |\n| **Windsurf** | Supported | `~/.codeium/windsurf/mcp_config.json` |\n\n---\n\n## Running Tests\n\n```bash\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n## Contributing\n\nContributions welcome! See [docs/contributing.md](docs/contributing.md) for guidelines.\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 11077, "sha": "c6df1589eecbbc347447a2566dda6066df955e86738816c8b36a845c81b2d0e7", "repo_slug": "mkpvishnu/terminal-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_mkpvishnu_terminal_mcp_2101d5b3/readme" }