GitHub - sumchattering/iterm2-mcp-server

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

macOS with iTerm2 installed
Node.js >= 18.0.0
Python 3 with the iterm2 package:
iTerm2 Python API enabled:
- Open iTerm2 > Settings (Cmd+,)
- Go to General > Magic
- Check Enable Python API
- Restart iTerm2

Installation

Using npx (recommended)

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:

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

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

Troubleshooting

"Connection failed" error

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

"iterm2 module not installed"

Install the Python package:

"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:

Receives tool calls from the AI assistant via MCP
Executes Python scripts that use the iterm2 library
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