{
  "markdown": "# Terminal MCP Server\n\n[![npm version](https://img.shields.io/npm/v/mcp-server-terminal.svg)](https://www.npmjs.com/package/mcp-server-terminal)\n[![npm downloads](https://img.shields.io/npm/dm/mcp-server-terminal.svg)](https://www.npmjs.com/package/mcp-server-terminal)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMCP server enabling AI agents to interact with terminal applications through structured Terminal State Tree representation. Works with any AI assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io/).\n\n## Installation\n\n### Via npm (Recommended)\n\n```bash\nnpx mcp-server-terminal\n```\n\n### Via GitHub Releases\n\nDownload pre-built binaries from [Releases](https://github.com/aybelatchane/mcp-server-terminal/releases).\n\n### Build from Source\n\n```bash\ngit clone https://github.com/aybelatchane/mcp-server-terminal.git\ncd mcp-server-terminal\ncargo build --release\n# Binary: ./target/release/terminal-mcp\n```\n\n## Configuration\n\n### Claude\n\n#### Claude Code (CLI)\n\n```bash\nclaude mcp add terminal -- npx mcp-server-terminal\n```\n\n#### Claude Desktop\n\nAdd to `~/.claude.json` (macOS/Linux) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### OpenAI Codex\n\n#### Codex CLI\n\n```bash\ncodex mcp add terminal -- npx mcp-server-terminal\n```\n\n#### Codex Configuration File\n\nAdd to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.terminal]\ncommand = \"npx\"\nargs = [\"mcp-server-terminal\"]\n```\n\n---\n\n### Google Gemini\n\n#### Gemini CLI\n\n```bash\ngemini mcp add terminal npx mcp-server-terminal\n```\n\n---\n\n### VS Code / GitHub Copilot\n\nVS Code 1.101+ supports MCP. Add to your VS Code settings (`settings.json`):\n\n```json\n{\n  \"mcp.servers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` or `.cursor/mcp.json` in your project:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### Zed\n\nAdd to your Zed settings (Preferences → Settings):\n\n```json\n{\n  \"context_servers\": {\n    \"terminal\": {\n      \"command\": {\n        \"path\": \"npx\",\n        \"args\": [\"mcp-server-terminal\"]\n      }\n    }\n  }\n}\n```\n\n---\n\n### Cline (VS Code Extension)\n\nClick MCP Servers icon → Configure → Advanced MCP Settings, then add:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### AWS Bedrock\n\nAdd to your Bedrock agent MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"]\n    }\n  }\n}\n```\n\n---\n\n### Other MCP Clients\n\nFor any MCP-compatible client, configure the server with:\n\n- **Command**: `npx`\n- **Args**: `[\"mcp-server-terminal\"]`\n\nOr if using the binary directly:\n\n- **Command**: `terminal-mcp`\n\n## Usage\n\nAsk your AI agent:\n\n- *\"Create a terminal session running htop\"*\n- *\"Take a snapshot of the terminal\"*\n- *\"Press the down arrow key\"*\n- *\"Type 'ls -la' and press Enter\"*\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `terminal_session_create` | Start a terminal session |\n| `terminal_session_list` | List active sessions |\n| `terminal_session_close` | Close a session |\n| `terminal_session_resize` | Resize terminal dimensions |\n| `terminal_snapshot` | Capture terminal state with UI elements |\n| `terminal_type` | Type text into terminal |\n| `terminal_press_key` | Press keys (arrows, F-keys, Ctrl+X) |\n| `terminal_click` | Click on detected UI element |\n| `terminal_wait_for` | Wait for text, element, or idle state |\n| `terminal_read_output` | Read raw terminal output |\n\n## Visual Mode\n\nBy default, sessions spawn a visible terminal window (xterm). For headless operation:\n\n```bash\nnpx mcp-server-terminal --headless\n```\n\nOr in your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\", \"--headless\"]\n    }\n  }\n}\n```\n\n### X11 Setup (Linux/WSL)\n\nVisual mode requires X11. Add the DISPLAY environment variable to your MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"],\n      \"env\": {\n        \"DISPLAY\": \":0\"\n      }\n    }\n  }\n}\n```\n\n## Logging\n\nSet the `RUST_LOG` environment variable:\n\n```json\n{\n  \"mcpServers\": {\n    \"terminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-server-terminal\"],\n      \"env\": {\n        \"RUST_LOG\": \"info\"\n      }\n    }\n  }\n}\n```\n\nLog levels: `error`, `warn`, `info`, `debug`, `trace`\n\nLogs go to stderr (stdout is reserved for MCP protocol).\n\n## Platform Support\n\n| Platform | Architecture | Status | Visual Mode |\n|----------|--------------|--------|-------------|\n| Linux | x64, arm64 | ✅ Full support | xterm + tmux |\n| macOS | x64, arm64 | ✅ Full support | Terminal.app / iTerm2 |\n| Windows (WSL) | x64, arm64 | ✅ Full support | xterm + tmux (via X11) |\n| Windows (native) | x64 | ⚠️ Headless only | Not supported |\n\n> **Windows users:** Use WSL for full functionality including visual mode.\n\n## License\n\nMIT\n",
  "bytes": 5437,
  "sha": "08f55e52f293232869dca273e8106caa3f32c4e6a3903d166b037e7a264c7a30",
  "repo_slug": "aybelatchane/mcp-server-terminal",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aybelatchane_mcp_server_termin_84d13c35/readme"
}