![\"Terminal](\"logo.png\")
\n\n \n
\n Let AI see and interact with your terminal.\n
\n\n\n Terminal MCP gives LLMs a shared view of your terminal session. Perfect for debugging CLIs and TUI applications in real-time, or letting AI drive terminal-based tools autonomously.\n
\n\n## Install\n\n```bash\nnpm install -g @ellery/terminal-mcp\n```\n\nOr via install script:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash\n```\n\n### Configure your AI tools\n\nWire `terminal-mcp` into the MCP config of every AI tool installed on your machine in one shot:\n\n```bash\nterminal-mcp setup # detect & install for all detected tools\nterminal-mcp setup --dry-run # preview without writing\nterminal-mcp setup --client claude-code,gemini # specific tools only\nterminal-mcp setup --uninstall # remove the entry from each tool\n```\n\nSupported clients (each gets the right schema for its config format):\n\n| Client | Config file | Format |\n|---|---|---|\n| OpenAI Codex CLI | `~/.codex/config.toml` | TOML |\n| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | JSON |\n| Gemini CLI | `~/.gemini/settings.json` | JSON |\n| OpenCode | `~/.config/opencode/opencode.json` | JSON |\n| Claude Code | `~/.claude.json` | JSON |\n| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) | JSON |\n\nA `.bak` of any pre-existing config is written next to the original on first install. The `terminal-mcp` entry is added without disturbing other servers or unrelated keys; running `setup` again is a no-op.\n\n### Upgrading\n\n```bash\nnpm install -g @ellery/terminal-mcp@latest\n```\n\nInteractive mode will print a banner on next launch when a newer release is available — `terminal-mcp` checks the npm registry once per day and caches the result. Headless and MCP-client modes never check or print anything (so MCP stdio stays clean). To opt out entirely, set `NO_UPDATE_NOTIFIER=1` or pass `--no-update-notifier`.\n\n## Features\n\n- **Full Terminal Emulation**: Uses xterm.js headless for accurate VT100/ANSI emulation\n- **Cross-Platform PTY**: Native pseudo-terminal support via node-pty (macOS, Linux, Windows)\n- **MCP Protocol**: Implements Model Context Protocol for AI assistant integration\n- **Session Recording**: Record terminal sessions to asciicast format for playback with asciinema\n- **Simple API**: Nine tools covering input, observation, recording, and session lifecycle\n- **Headless Mode**: Run as a standalone MCP server without a TTY — ideal for CI, containers, and non-interactive environments\n- **Multi-Session**: Run multiple isolated terminal sessions in one process, addressed by `sessionId`\n- **Sandbox Mode**: Optional security restrictions for filesystem and network access\n\n## Building from Source\n\n```bash\nnpm install\nnpm run build\n```\n\n## Usage\n\n### MCP Configuration\n\nAdd to your MCP client settings:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"terminal-mcp\"\n }\n }\n}\n```\n\nWith custom options:\n\n```json\n{\n \"mcpServers\": {\n \"terminal\": {\n \"command\": \"terminal-mcp\",\n \"args\": [\"--cols\", \"100\", \"--rows\", \"30\", \"--shell\", \"/bin/zsh\"]\n }\n }\n}\n```\n\n### Command-Line Options\n\n```\nterminal-mcp [OPTIONS]\n\nOptions:\n --cols\n ![\"Sandbox](\"sandbox-permissions.png\")
\n