enhanced-iterm

Enhanced iTerm MCP Server provides a bridge between MCP tooling and iTerm2's Python API. It exposes a set of tools for terminal management, pane operations, and real-time session information, enabling automated control of iTerm2 from your AI assistants or automation scripts. With native Python API integration, you can create and configure terminals, split panes, broadcast commands across multiple panes, monitor sessions, and customize tab colors, all through a consistent MCP interface.

To use it, configure the MCP entry for enhanced-iterm in your MCP config (as shown in the example). Once running, you can invoke tools such as open-terminal, split-terminal-horizontal, broadcast-input, get-session-details, and set-tab-color. This lets you programmatically launch new terminals with profiles, split existing windows, or run commands across multiple panes in parallel, while querying session state in real time. The server emphasizes robust error handling and retries, helping maintain reliable automation even when iTerm2 or the environment experiences transient issues.

Prerequisites:

• Node.js v18 or newer
• npm (comes with Node.js)
• Python 3.8+ for the Python API components
• iTerm2 installed on macOS with Python API access enabled

Installation steps:

1. Global installation (recommended for quick setup):

npm install -g enhanced-iterm-mcp-server

2. Verify installation and usage:

enhanced-iterm-mcp --help

3. (From source) Clone and install dependencies, then build:

git clone https://github.com/2black0/enhanced-iterm-mcp-server.git
cd enhanced-iterm-mcp-server
npm install
./setup-python-api.sh
npm run build

4. Add to your MCP configuration (example):

{
  "mcpServers": {
    "enhanced-iterm": {
      "command": "node",
      "args": ["/path/to/enhanced-iterm-mcp-server/dist/index-python-api.js"],
      "type": "stdio"
    }
  }
}

5. Start the MCP server as part of your environment (depending on your setup).

Tips and common issues:

• Ensure iTerm2 is running and the Python API is enabled: iTerm2 Preferences -> General -> Magic -> Enable Python API, then restart iTerm2.
• If you encounter a connection error, verify the Python virtual environment and the iterm2 package installation (e.g., source iterm_env/bin/activate; pip list | grep iterm2).
• When using the NPX or local installation paths, adjust the dist/index-python-api.js path in your MCP config to match your build output.
• For production deployments, rely on the robust error handling and retries implemented in the Python API integration.
• The npm package name is enhanced-iterm-mcp-server; use npm run build to compile TypeScript before deploying the server.