iterm

iterm-mcp provides a direct bridge to your active iTerm2 session, allowing the model to read terminal output, write commands, and send control characters. Tools exposed include write_to_terminal for injecting commands, read_terminal_output to fetch a portion of the session’s output, and send_control_character to dispatch control keys like Ctrl-C or Ctrl-Z. The server is designed to let the model interact with your current terminal screen and, when requested, start and manage REPLs or other interactive processes within iTerm2. This setup is intended to be integrated with MCP clients such as Claude Desktop, enabling natural language driven control over terminal tasks while keeping the model focused on the most relevant on-screen information. You can configure the MCP client to point at the iterm-mcp server and then issue prompts that leverage the terminal tools to inspect and manipulate your iTerm session as needed.

Prerequisites:\n- Node.js v18 or higher\n- iTerm2 running on macOS\n- An MCP client (e.g., Claude Desktop) that supports MCP servers\n\nInstall and run the server via npx (no local install required):\n1) Ensure Node.js is installed (v18+). You can verify with:\n node -v\n\n2) Start the iterm-mcp server through your MCP client configuration. A typical configuration uses npx to fetch and run the package:\n On macOS / Claude Desktop config:\n\n {\n "mcpServers": {\n "iterm-mcp": {\n "command": "npx",\n "args": [\n "-y",\n "iterm-mcp"\n ]\n }\n }\n }\n\n3) Alternatively, install via Smithery for automated client integration:\n\nbash\nnpx -y @smithery/cli install iterm-mcp --client claude\n``\nThis will expose the server to Claude Desktop using the Smithery workflow.\n\nStep-by-step usage:\n- Ensure iTerm2 is running and you are connected to a live session.\n- Add the MCP server entry to your client configuration (as shown above).\n- Launch the MCP server via your client, and then you can issue prompts that call the available tools (write_to_terminal, read_terminal_output, send_control_character).\n\nDevelopment and building (optional):\nbash\nyarn install\n\nyarn run build\n\n# For auto-rebuild during development:\nyarn run watch\n```

Tips and common issues:\n- iTerm2 must be actively running and the target session should be accessible by the user running the MCP server.\n- The model will only see the portion of terminal output you fetch; adjust read_terminal_output requests to balance context with performance.\n- When sending control characters, ensure the target process in the terminal is in a state that can handle such input (e.g., a running REPL or shell).\n- Debugging MCP servers can be challenging since communication is via stdio. Consider using the MCP Inspector tooling for easier debugging.\n- Environment variables are typically not required for basic operation, but you can expose additional configurables via env if supported by your deployment (e.g., customizing terminal capture size or safe command prefixes).