home / mcp / iterm mcp server

Iterm MCP Server

A Model Context Protocol server that executes commands in the current iTerm session - useful for REPL and CLI assistance

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run an MCP server that exposes control over your iTerm2 session, letting a model inspect only the portion of your terminal output that matters and perform tasks by interacting with REPLs and sending control signals directly to the terminal.

How to use

You connect an MCP client to the iterm-mcp server to share your iTerm session with the model. The model can read the latest terminal output you allow, ask questions about what’s on the screen, and guide or execute steps by sending commands and control characters. You can observe the model’s actions as it progresses through each step, including starting and interacting with REPLs and using control signals like Ctrl-C or Ctrl-Z.

How to install

Prerequisites you need before starting:

- iTerm2 must be running.

- Node.js version 18 or greater.

Install with Claude Desktop configuration

Add the MCP server configuration for Claude Desktop to enable iterm-mcp. Use the following path for macOS or Windows depending on your environment.

Clipboard-friendly server config snippet

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

Installing via Smithery

If you prefer automatic installation, you can set up iTerm for Claude Desktop with Smithery. Run the following command to install the MCP server client for Claude.

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

Run and verify

Once installed, start the MCP server via the command configured in your environment (the JSON snippet above uses npx to launch the iterm-mcp package). Ensure iTerm2 remains open and the MCP client is ready to connect.

Development and debugging notes

Development workflows use standard Node tooling. You can install dependencies, build, and run tests as you would with a typical Node.js project. When debugging MCP servers that communicate over stdio, you may find it helpful to use the MCP Inspector for browser-based debugging tools.

Configuration and safety notes

The server provides direct terminal access without built-in safety checks. You are responsible for supervising model activity and aborting operations if needed. For multi-step tasks, start with focused tasks to understand how the model interacts with your terminal.

Tools and capabilities

The MCP server exposes tools to interact with your active iTerm session. Available capabilities include writing to the terminal, reading terminal output, and sending control characters (such as Ctrl-C). Use these tools to guide the model’s actions and monitor progress in real time.

Safety considerations

- You are responsible for using the tool safely. - There are no built-in safety restrictions on commands the model can run. - Models can behave in unexpected ways, so you should monitor activity and abort if necessary. - For complex tasks, break them into smaller steps and supervise the model as it progresses.

Requirements

- iTerm2 must be running. - Node version 18 or greater.

Available tools

write_to_terminal

Writes to the active iTerm terminal, useful for executing commands and advancing tasks.

read_terminal_output

Reads a specified number of lines from the active iTerm terminal to feed the model with current context.

send_control_character

Sends a control character (such as Ctrl-C or Ctrl-Z) to the active iTerm terminal to manage processes.