iterm-mcp

A Model Context Protocol server that provides access to your iTerm session.

Efficient Token Use: Only the visible content of the terminal is passed to the model. The model can retrieve content that's not visible if necessary.
Supports Long-Running Processes: iterm-mcp knows when the terminal is waiting for user input. Long-running processes are handled gracefully.
Interrupt When Needed: Send control characters to the terminal to interrupt processes.
Inspect Terminal Activity: Gives the model visibility into the current terminal content.

write_to_terminal - Writes to the active iTerm terminal, often used to run a command.
read_terminal_output - Reads the output from the active iTerm terminal.
send_control_character - Sends a control character to the active iTerm terminal.

Installation

To use with Claude Desktop, add the server config:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "iterm-mcp"
      ]
    }
  }
}

To install iTerm for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install iterm-mcp --client claude

Install dependencies:

yarn install

Build the server:

yarn run build

For development with auto-rebuild:

yarn run watch

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

yarn run inspector
yarn debug 

The Inspector will provide a URL to access debugging tools in your browser.