📌Overview

Purpose: The iTerm-MCP framework provides a Model Context Protocol server to enhance interaction with iTerm sessions, enabling seamless task delegation and output monitoring for models.

Overview: iTerm-MCP allows models to intelligently engage with terminal outputs, sharing your iTerm interface. It emphasizes an intuitive interaction where users can observe and interact with how models process command-line tasks in real-time, making it ideal for integrated workflows.

Key Features:

• Efficient Token Use: The framework optimizes output inspection by allowing models to focus on the most relevant recent lines, enhancing performance during long-running commands.

• Natural Integration: It enables direct interaction with iTerm, allowing users to ask questions or delegate tasks, fostering a collaborative environment between the user and the model.

• Full Terminal Control and REPL support: Models can effectively start and manage REPL sessions, send control characters, and interact precisely with terminal commands, enabling comprehensive terminal manipulation.

• Easy on the Dependencies: Designed with minimal dependencies, it can be effortlessly run via npx, ensuring straightforward integration with applications like Claude Desktop and others.

---

iterm-mcp

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

Features

• Efficient Token Use: Allows the model to inspect only the output it is interested in, typically the last few lines even for long-running commands.
• Natural Integration: Share iTerm with the model to ask questions about the screen or delegate tasks and watch the model perform each step.
• Full Terminal Control and REPL support: The model can start and interact with REPLs and send control characters like ctrl-c, ctrl-z, etc.
• Easy on Dependencies: Built with minimal dependencies and runnable via npx. Designed to be easy to add to Claude Desktop and other MCP clients.

Safety Considerations

• The user is responsible for using the tool safely.
• No built-in restrictions: iterm-mcp does not evaluate the safety of commands executed.
• Models can behave unexpectedly; monitor activity and abort when appropriate.
• For multi-step tasks, interrupt the model if it goes off track; start with smaller, focused tasks until familiar with the model’s behavior.

Tools

• write_to_terminal - Writes to the active iTerm terminal, often to run commands. Returns the number of lines of output produced.
• read_terminal_output - Reads the requested number of lines from the active iTerm terminal.
• send_control_character - Sends a control character to the active iTerm terminal.

Requirements

• iTerm2 must be running
• Node version 18 or greater

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"
      ]
    }
  }
}

Installing via Smithery

To install iTerm for Claude Desktop automatically via Smithery:

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

Development

Install dependencies:

yarn install

Build the server:

yarn run build

For development with auto-rebuild:

yarn run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. It is recommended to use the MCP Inspector, which is available as a package script:

yarn run inspector
yarn debug <command>

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