v0.1.0 · MCP for iTerm2

Your AI controls
the terminal

An MCP server that connects AI assistants to your iTerm2. Run commands, read output, manage sessions — all through conversation.

Star on GitHub go install github.com/phpgao/term2mcp@latest

~/.codebuddy/mcp.json

"mcpServers": {
    "term2mcp": {
      "command": "term2mcp"
    }
  }

How It Works

Talk to your terminal

AI assistants read your terminal output, send commands, and manage sessions — zero friction.

Read Output

AI reads your terminal buffer to understand what's happening.

Send Commands

AI types commands just like a human — tab completion, Enter, everything.

Control Layout

Create tabs, split panes, activate windows — layout managed by AI.

Screenshot

Capture any window, tab, or session as PNG for the AI to analyze.

Secure & Local

Runs entirely on your Mac. No network, no cloud. Stdio transport.

Instant Setup

go install + one JSON line. That's it. Works out of the box.

16 Tools

Everything accessible to AI

Each tool maps directly to an iTerm2 API. AI picks the right one for the task.

Session

list_sessionsList all windows, tabs, sessions with IDs

send_textSend commands as if typed (use \n for Enter)

get_bufferRead terminal screen content

activateFocus a session, bring window to front

inject_keystrokesInject raw bytes / key sequences

close_sessionClose a pane (with optional force)

set_nameRename a session for identification

set_badgeSet overlay badge text on session

Layout

create_tabNew tab or window, optional init command

split_paneVertical or horizontal split

focusGet currently focused session/tab/window

Data

get_variableRead session variable (name, pid, path...)

set_variableWrite session variable

get_promptLast command text, exit code, working dir

list_profilesList iTerm2 profile names

screenshotPNG capture of window or session

Integration

Wire into your AI assistant

Works with CodeBuddy Code, Claude Desktop, Continue, and any MCP-compatible client.

CodeBuddy Code

// ~/.codebuddy/mcp.json
{
  "mcpServers": {
    "term2mcp": {
      "command": "term2mcp"
    }
  }
}

Claude Desktop

// ~/Library/Application Support/
//   Claude/claude_desktop_config.json
{
  "mcpServers": {
    "term2mcp": {
      "command": "term2mcp"
    }
  }
}

1

Enable iTerm2 Python API

Preferences → General → Magic → Enable Python API

2

Install term2mcp

go install github.com/phpgao/term2mcp@latest

3

Add to your MCP config

One JSON entry in mcp.json or Claude Desktop config.

4

Start asking

"List my iTerm2 sessions", "Run npm test in that tab", "Read the last error"

Ecosystem

Your AI controlsthe terminal