📌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 relevant output, typically the last few lines of running commands.

• Natural Integration: iTerm can be shared with the model for asking questions or delegating tasks.

• Full Terminal Control and REPL Support: The model can interact with REPLs and send control characters (e.g., ctrl-c, ctrl-z).

• Easy on the Dependencies: Built with minimal dependencies, it can be run via npx and is compatible with Claude Desktop and other MCP clients.

Safety Considerations

• Users are responsible for safe tool usage.
• No built-in command safety evaluations.
• Users should monitor model activities and abort as necessary.
• For multi-step tasks, start small to understand model behavior.

Tools

• write_to_terminal: Writes to the active iTerm terminal and returns the output line count.
• read_terminal_output: Reads a specified number of lines from the 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:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

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

Debugging can be challenging due to MCP servers communicating over stdio. Use the MCP Inspector for better debugging:

yarn run inspector
yarn debug <command>

The Inspector will provide a URL for accessing debugging tools in your browser.