iTerm MCP

What is iterm-mcp?

iterm-mcp is a Model Context Protocol (MCP) server designed to enable Large Language Models (LLMs) to interact with and control your iTerm2 terminal session on macOS. It acts as a bridge, allowing AI models to execute commands, read output, and send control characters within the terminal environment.

How to use iterm-mcp?

iterm-mcp can be integrated with MCP clients like Claude Desktop. To use it, you need to configure your MCP client to recognize iterm-mcp as a server. This typically involves adding a JSON configuration to your client's settings, specifying the command to run npx -y iterm-mcp. Alternatively, you can use Smithery to automatically install and configure iterm-mcp for Claude Desktop with a simple npx -y @smithery/cli install iterm-mcp --client claude command.

Key Features of iterm-mcp

• Efficient Token Use: The server allows LLMs to inspect only relevant output, typically the last few lines, optimizing token usage for long-running commands.
• Natural Integration: It enables seamless interaction between the user and the model within iTerm, allowing the model to answer questions about the screen content or perform delegated tasks.
• Full Terminal Control and REPL Support: LLMs can initiate and interact with REPLs (Read-Eval-Print Loops) and send control characters (e.g., Ctrl-C, Ctrl-Z) to the terminal.
• Minimal Dependencies: iterm-mcp is built with minimal dependencies and can be run via npx, making it easy to integrate with various MCP clients.
• Tools for Interaction: It provides specific tools for LLMs: write_to_terminal (to execute commands), read_terminal_output (to read output), and send_control_character (to send control signals).

Use Cases of iterm-mcp

• REPL Assistance: LLMs can assist in REPL environments by executing commands and interpreting results.
• CLI Assistance: Models can help with command-line interface tasks, such as running commands, debugging, and automating workflows.
• Delegated Tasks: Users can delegate multi-step terminal tasks to the LLM, observing its progress and intervening if necessary.
• Interactive Problem Solving: LLMs can analyze terminal output and suggest solutions or next steps for issues encountered in the terminal.

FAQ about iterm-mcp

• What are the safety considerations? Users are responsible for safe usage. iterm-mcp does not evaluate command safety, and models can behave unexpectedly. Users should monitor activity and abort if needed, especially for multi-step tasks.
• What are the requirements? iTerm2 must be running, and Node.js version 18 or greater is required.
• How do I debug iterm-mcp? You can use the MCP Inspector by running yarn run inspector and then yarn debug <command> to access debugging tools in your browser.

iterm-mcp

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

Features

Efficient Token Use: iterm-mcp gives the model the ability to inspect only the output that the model is interested in. The model typically only wants to see the last few lines of output even for long running commands.

Natural Integration: You share iTerm with the model. You can ask questions about what's on the screen, or delegate a task to the model and watch as it performs each step.

Full Terminal Control and REPL support: The model can start and interact with REPL's as well as send control characters like ctrl-c, ctrl-z, etc.

Easy on the Dependencies: iterm-mcp is built with minimal dependencies and is runnable via npx. It's designed to be easy to add to Claude Desktop and other MCP clients. It should just work.

Safety Considerations

• The user is responsible for using the tool safely.
• No built-in restrictions: iterm-mcp makes no attempt to evaluate the safety of commands that are executed.
• Models can behave in unexpected ways. The user is expected to monitor activity and abort when appropriate.
• For multi-step tasks, you may need to interrupt the model if it goes off track. Start with smaller, focused tasks until you're familiar with how the model behaves.

Tools

• write_to_terminal - Writes to the active iTerm terminal, often used to run a command. Returns the number of lines of output produced by the command.
• 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. We recommend using 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.