iTerm2 MCP Server

An MCP (Model Context Protocol) server that allows AI assistants like Claude to read the contents of iTerm2 terminal panes. This enables AI assistants to see what's happening in your other terminal windows and tabs.

Features

• List all panes: See all open iTerm2 windows, tabs, and panes with their working directories and running jobs
• Read pane contents: Get the screen buffer text from any pane
• Current pane detection: Automatically detects which pane the server is running in
• Status checking: Verify that iTerm2 Python API is properly configured

Prerequisites

1. macOS with iTerm2 installed
2. Node.js >= 18.0.0
3. Python 3 with the iterm2 package:

   pip install iterm2

4. iTerm2 Python API enabled:
   • Open iTerm2 > Settings (Cmd+,)
   • Go to General > Magic
   • Check Enable Python API
   • Restart iTerm2

Installation

Using npx (recommended)

npx iterm2-mcp-server

Global installation

npm install -g iterm2-mcp-server
iterm2-mcp-server

Configuration

Claude Desktop

Add to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "iterm2": {
      "command": "npx",
      "args": ["iterm2-mcp-server"]
    }
  }
}

Claude Code

Add the MCP server using the CLI:

claude mcp add --scope user iterm2 -- npx github:sumchattering/iterm2-mcp-server

This installs it globally so it's available in all your projects. You can verify it's working:

claude mcp list

You should see: iterm2: npx github:sumchattering/iterm2-mcp-server - ✓ Connected

Available Tools

iterm2_list_panes

List all iTerm2 windows, tabs, and panes with their shorthand IDs, names, working directories, and running jobs.

iterm2_read_pane

Read the screen buffer contents of a specific pane.

Parameters:

• session_id (required): The pane ID using shorthand like t3p1 (tab 3, pane 1) or w1t3p1

iterm2_send_text

Send text or commands to an iTerm2 pane as if typed by the user.

Parameters:

• session_id (required): The pane ID (e.g., t3p1)
• text (required): The text or command to send
• newline (optional, default: true): Whether to press Enter after the text

iterm2_send_control_character

Send control characters like Ctrl+C, Ctrl+D, Ctrl+Z, or Ctrl+L to an iTerm2 pane.

Parameters:

• session_id (required): The pane ID (e.g., t3p1)
• control (required): c (Ctrl+C), d (Ctrl+D), z (Ctrl+Z), l (Ctrl+L)

iterm2_split_pane

Split an iTerm2 pane horizontally or vertically, creating a new pane.

Parameters:

• session_id (required): The pane ID to split (e.g., t3p1)
• vertical (optional, default: false): If true, split vertically (side by side)

iterm2_current_pane

Get information about the current iTerm2 pane where Claude Code is running.

iterm2_status

Check if iTerm2 Python API is properly configured and ready to use.

iterm2_enable_api

Enable the iTerm2 Python API in preferences. Note: iTerm2 must be restarted after enabling.

Pane IDs

Panes are identified using shorthand IDs that match iTerm2's UI (1-based indexing):

• t3p1 - Tab 3, Pane 1 (assumes Window 1)
• t3p2 - Tab 3, Pane 2
• w1t3p1 - Window 1, Tab 3, Pane 1 (explicit window)
• w2t1p1 - Window 2, Tab 1, Pane 1

Use iterm2_list_panes to see all available panes and their IDs.

Using with Claude Code

Once installed, Claude Code can see and interact with your terminal panes. Here are effective ways to use it:

Asking about panes

• "What's in tab 3?" - Claude will read the contents of tab 3
• "What's running in the pane next to you?" - Claude can identify adjacent panes
• "Show me all my terminal tabs" - Lists all panes with their shorthand IDs
• "What's the output of my server?" - Claude can find and read server output

Running commands in other panes

• "Run npm test in t3p1" - Sends command to specific pane
• "Stop the process in tab 4" - Sends Ctrl+C to interrupt
• "Clear the terminal in t2p1" - Sends Ctrl+L

Working with multiple panes

• "Split my terminal and run the dev server in the new pane"
• "What errors are showing in my other terminals?"
• "Compare the output in tab 2 and tab 3"

Tips for effective queries

1. Be specific about location: "tab 3" or "t3p1" is clearer than "the other terminal"
2. Reference the pane list: Ask Claude to list panes first if you're unsure of the layout
3. Use relative references: "the pane next to you" or "the tab on the left" work too

Troubleshooting

"Connection failed" error

1. Make sure iTerm2 is running
2. Verify Python API is enabled: iTerm2 > Settings > General > Magic > Enable Python API
3. Restart iTerm2 after enabling the API (Cmd+Q, then reopen)

"iterm2 module not installed"

Install the Python package:

pip install iterm2

"Not running in an iTerm2 session"

The MCP server needs to be started from within an iTerm2 terminal for current pane detection to work.

How It Works

This MCP server uses the iTerm2 Python API to communicate with iTerm2 via a WebSocket connection. The server:

1. Receives tool calls from the AI assistant via MCP
2. Executes Python scripts that use the iterm2 library
3. Returns formatted results back to the assistant

Development

# Clone the repository
git clone https://github.com/sumchattering/iterm2-mcp-server.git
cd iterm2-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Future Improvements

The following features are being considered for future releases. Feedback welcome!

• Create tab/window: iterm2_create_tab and iterm2_create_window tools
• Close pane: iterm2_close_pane tool to close panes programmatically
• Focus pane: iterm2_focus_pane to bring a specific pane to the foreground
• Wait for prompt: iterm2_wait_for_prompt to wait until a command finishes executing
• Set pane title: Ability to set custom titles for panes
• Performance optimization: Persistent Python process instead of spawning per request