iterm-mcp is a Model Context Protocol (MCP) server that provides access to the current iTerm session. It is mainly used to execute commands in iTerm and to let the model ask questions or operate on what is displayed in the terminal, making it suitable for REPL and CLI assistance scenarios.
Main capabilities:
- Efficient token usage: iterm-mcp lets the model inspect only the output it is interested in. Even for long-running commands, the model usually only needs to view the last few lines of output.
- Natural integration: the user and the model share iTerm. You can ask questions about what is on the screen, or delegate tasks to the model and watch it perform each step.
- Full terminal control and REPL support: the model can start a REPL and interact with it, and can also send control characters such as ctrl-c and ctrl-z.
- Simple dependencies: iterm-mcp is built with very few dependencies, can be run via npx, and is designed to be easy to add to Claude Desktop and other MCP clients.
Tool interface:
- write_to_terminal: writes to the active iTerm terminal, usually used to run commands. Returns the number of output lines produced by the command.
- read_terminal_output: reads the specified number of output lines from the active iTerm terminal.
- send_control_character: sends a control character to the active iTerm terminal.
Usage:
- Prerequisites: iTerm2 must be running; Node version must be 18 or higher.
- When used with Claude Desktop, a server configuration must be added. The macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path is %APPDATA%/Claude/claude_desktop_config.json.
- iTerm can be automatically installed for Claude Desktop via Smithery.
- Install dependencies, build the server, and development can use automatic rebuilds.
- Because the MCP server communicates over stdio, debugging can be difficult. MCP Inspector is recommended; it is provided as a package script and will givea URL for accessing the debugging tool in a browser.
Security considerations:
- Users are responsible for using the tool safely.
- No built-in restrictions: iterm-mcp does not attempt to evaluate the safety of the commands it executes.
- The model may behave in unexpected ways, and users should monitor activity and abort when appropriate.
- For multi-step tasks, it may be necessary to interrupt the model if it goes off track. It is recommended to start with smaller, focused tasks until you are familiar with how the model behaves.
