iterm2-mcp

# iterm2-mcp [中文](README.md) | [English](README_EN.md) A Model Context Protocol (MCP) local server providing access to iTerm2 terminal sessions. ### Features **Efficient Token Usage:** iterm2-mcp allows models to only see the output they are interested in. Even for long-running commands, models typically only need to see the last few lines of output. **Natural Integration:** You share an iTerm with the model. You can ask about what's on the screen or delegate tasks to the model and watch it perform them step-by-step. **Full Terminal Control and REPL Support:** Models can launch and interact with REPLs and can also send control characters like ctrl-c, ctrl-z. **Minimal Dependencies:** iterm2-mcp is built with minimal dependencies and can be run via npx. It is designed to be easily added to Claude Desktop and other MCP clients out of the box. ## Security Considerations * Users are responsible for using the tool safely. * No built-in restrictions: iterm2-mcp does not evaluate the safety of commands executed. * Models may exhibit unexpected behavior. Users should monitor activity and terminate as appropriate. * For multi-step tasks, you may need to interrupt the model if it goes off-track. Start with smaller, focused tasks until you are familiar with how the model behaves. ### Tools - `write_to_terminal` - Writes to the active iTerm2 terminal, typically used to execute commands. Returns the number of output lines produced by the command. - `read_from_terminal` - Reads a specified number of lines of output from the active iTerm2 terminal. - `send_control_character` - Sends a control character to the active iTerm2 terminal. - `get_terminal_list` - Returns information about all open iTerm2 windows, tabs, and sessions, including the currently active session. All tools support an optional `sessionId` parameter to specify the target session for the operation. Session IDs can be obtained via `get_terminal_list`. ### Environment Requirements * iTerm2 must be running * Node.js 18 or higher ## Installation via Claude Code CLI ```bash claude mcp add iterm2-mcp -- node /path/to/iterm2-mcp/build/index.js ``` ## Development Install dependencies: ```bash npm install ``` Build the server: ```bash npm run build ``` Development mode (auto-rebuilds): ```bash npm run watch ``` ### Debugging Debugging can be challenging since the MCP server communicates via stdio. Debugging is recommended with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which can be launched via the package scripts: ```bash npm run inspector npm run debug <command> ``` The Inspector provides a URL that can be visited in a browser for debugging tools.