home / mcp / enhanced iterm mcp server

Enhanced iTerm MCP Server

Provides native iTerm2 Python API integration for advanced terminal automation and multi-pane control.

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can automate iTerm2 from an MCP client using a dedicated server that exposes terminal management, real-time session data, and multi-pane orchestration through a native Python API. This enables reliable, high-performance control of iTerm2 for AI assistant workflows and complex terminal layouts.

How to use

Set up the enhanced iTerm MCP Server in your MCP client configuration. You will add a local stdio server that runs Node to invoke the built-in Python API bridge, exposing commands for opening terminals, splitting panes, broadcasting input, and querying session details. With the server configured, you can orchestrate multi-pane workflows, monitor sessions in real time, and customize tab visuals across your iTerm2 workspace.

How to install

Prerequisites: Node.js and npm must be available on your system. You should also have Python and iTerm2 with the Python API enabled (see the next section). Ensure you have git for cloning if you install from source.

# From source
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

Configure your MCP client to use the server

Add a stdio MCP entry that runs the Node process and points to the built Python API bridge. This example uses a placeholder path to the built file.

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

Test the setup

Run the server’s test command to verify the MCP integration is wired correctly.

# If installed globally
enhanced-iterm-mcp test

# If installed from source
npm test

Available tools

open-terminal

Create new terminals with profiles and commands.

list-all-sessions

Provide a complete overview of all iTerm2 windows, tabs, and sessions.

split-terminal-horizontal

Split the current terminal horizontally using a chosen profile and command.

split-terminal-vertical

Split the current terminal vertically with a specified profile and command.

execute-command-in-pane

Run a command inside a specific pane.

broadcast-input

Send the same command to multiple panes at once.

get-session-info

Fetch basic information about a session.

get-session-details

Retrieve comprehensive session details and environment variables.

monitor-session

Watch session changes over a defined period.

set-tab-color

Apply a visual color to a tab using a named color or hex value.

list-panes

List all tracked panes for quick reference.

get-terminal-state

Provide an overview of the current terminal state.