Overview

iTerm MCP creates a bridge between AI models and your active iTerm terminal session, allowing models to execute commands and interact with your terminal environment. This enables powerful use cases like guided debugging, REPL assistance, and automated terminal workflows.

Features

• Terminal Access: Models can write commands to your active iTerm terminal and read the resulting output
• Efficient Token Usage: Models can selectively read only the relevant terminal output, preserving context window space
• REPL Support: Full support for interactive programming environments and REPLs
• Control Characters: Send control characters like Ctrl+C, Ctrl+Z for terminal control
• Minimal Dependencies: Built to be lightweight and easy to integrate

Requirements

• iTerm2 must be running
• Node.js version 18 or greater
• macOS (iTerm2 is macOS-only)

Installation

Using Claude Desktop

1. Create or edit the Claude Desktop configuration file:

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

2. Add the following server configuration:

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

Using Smithery (Automated Installation)

You can use Smithery to automatically install iTerm MCP for Claude Desktop:

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

Available Tools

write_to_terminal

Writes text to the active iTerm terminal, typically used to run commands.

Returns: The number of lines of output produced by the command.

read_terminal_output

Reads the specified number of lines from the active iTerm terminal.

Parameters:

• Number of lines to read

send_control_character

Sends a control character to the active iTerm terminal.

Parameters:

• Control character to send (e.g., "c" for Ctrl+C)

Safety Considerations

• The tool provides unrestricted access to your terminal - monitor model activity carefully
• No built-in safety restrictions on command execution
• Models may behave unexpectedly - be prepared to interrupt if necessary
• Start with smaller, focused tasks until you're comfortable with the tool's behavior
• You are responsible for the safety of commands executed through this tool

Example Usage

You can ask the model to:

1. Help debug errors in your terminal
2. Assist with complex command-line operations
3. Guide you through using unfamiliar CLI tools
4. Interact with REPL environments for languages like Python, Ruby, or JavaScript
5. Execute multi-step terminal workflows while explaining each step

Development and Debugging

For developers interested in modifying or debugging the server:

1. Clone the repository: git clone https://github.com/ferrislucas/iterm-mcp.git
2. Install dependencies: yarn install
3. Build the server: yarn run build
4. For development with auto-rebuild: yarn run watch

Since MCP servers communicate over stdio, debugging can be challenging. The project includes support for the MCP Inspector:

yarn run inspector
yarn debug <command>

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