Iterm Terminal

🚀 iterm-mcp

A Model Context Protocol (MCP) server that provides access to your iTerm sessions.

🚀 Quick Start

iterm-mcp is a Model Context Protocol (MCP) server that enables seamless access to your iTerm sessions. It offers a range of features designed to enhance the interaction between models and iTerm terminals.

✨ Features

• Efficient Token Usage: iterm-mcp allows the model to view only the parts of the output it is interested in. Models typically only want to see the last few lines of output from long commands.
• Natural Integration: You can share your iTerm with the model. You can ask about the content on the screen, delegate tasks to the model, and watch it perform each step.
• Full Terminal Control and REPL Support: The model can start and interact with REPL environments and send control characters (e.g., ctrl-c, ctrl-z, etc.).
• Lightweight Dependencies: iterm-mcp is built with minimal dependencies and can be run via npx. It is designed for Claude Desktop and other MCP clients and works out of the box.

⚠️ Important Note

• Users are responsible for the safe use of the tool.
• No Built-in Restrictions: iterm-mcp does not evaluate the safety of commands.
• The model may behave unexpectedly. Users should monitor activities and terminate operations if necessary.
• 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 the model's behavior.

💻 Usage Examples

Tools

• write_to_terminal - Write content to the current iTerm terminal, typically used to run commands. Returns the number of lines of command output.
• read_terminal_output - Read a specified number of lines from the current iTerm terminal.
• send_control_character - Send control characters to the current iTerm terminal.

📦 Installation

Installation with Claude Desktop

When using iterm-mcp with Claude Desktop, add the server configuration:

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

Installation via Smithery

Automatically install the iTerm plugin for Claude Desktop:

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

🔧 Technical Details

Development

Install dependencies:

yarn install

Build the server:

yarn run build

Develop with automatic rebuild:

yarn run watch

Debugging

Since MCP servers communicate via standard input and output, debugging can be challenging. We recommend using MCP Inspector, which is available as a package script:

yarn run inspector
yarn debug <command>

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