iTerm-MCP: Supercharge Your LLMs with Real-Time Terminal Interaction

Unlock the power of Large Language Models (LLMs) by seamlessly integrating them with your iTerm2 terminal using iTerm-MCP. This open-source Model Context Protocol (MCP) server empowers LLMs to interact directly with your terminal, enabling a new level of automation, analysis, and control.

Key Features:

• Intelligent Token Management: iTerm-MCP optimizes token usage by allowing the LLM to selectively inspect only the relevant output from your terminal, focusing on the last few lines even for long-running commands.
• Natural Workflow Integration: Seamlessly blend LLMs into your existing workflows. Ask questions about your terminal's state, delegate tasks, and observe the LLM execute commands in real-time.
• Full Terminal Control: Grant LLMs complete control over your iTerm2 session, including the ability to start and interact with REPLs, send control characters (Ctrl+C, Ctrl+Z, etc.), and execute complex commands.
• Lightweight and Dependency-Free: Built with minimal dependencies and easily runnable via npx, iTerm-MCP is designed for effortless integration with Claude Desktop and other MCP clients.

Safety First: Responsible LLM Integration

• User Responsibility: You are solely responsible for the safe and ethical use of iTerm-MCP.
• No Built-in Restrictions: iTerm-MCP does not impose any restrictions on the commands executed by the LLM.
• Monitor LLM Behavior: LLMs can exhibit unexpected behavior. Closely monitor their actions and abort tasks when necessary.
• Start Small: Begin with small, focused tasks to understand the LLM's behavior before delegating complex, multi-step operations.

Available Tools:

• write_to_terminal: Writes a command to the active iTerm2 terminal and returns the number of output lines generated.
• read_terminal_output: Reads a specified number of lines from the active iTerm2 terminal.
• send_control_character: Sends a control character (e.g., Ctrl+C) to the active iTerm2 terminal.

Prerequisites:

• iTerm2 must be running.
• Node.js version 18 or higher is required.

Installation Guide:

Claude Desktop Integration:

1. Locate the Claude Desktop configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
2. Add the following iTerm-MCP server configuration to the mcpServers section:

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

Smithery Installation (Recommended):

Simplify the installation process using Smithery:

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

Development Setup:

1. Install dependencies:

yarn install

2. Build the server:

yarn run build

3. For development with automatic rebuilding:

yarn run watch

Debugging Tips:

Debugging MCP servers can be challenging due to their reliance on standard input/output (stdio) communication. We recommend using the MCP Inspector for enhanced debugging capabilities.

1. Run the MCP Inspector:

yarn run inspector

2. Start your debugging session:

yarn debug <command>

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