iterm2-mcp

An MCP server that provides full control over iTerm2.

Prerequisites

1. iTerm2 running on macOS.

2. Preferences > General > Magic > "Enable Python API" must be checked.

3. Install iTerm2 shell integration in your shell. run_command and session variables like path/jobName depend on it. Without it, run_command falls back to its timeout.

The first time the server connects, iTerm2 will prompt you to approve the binary. Approve once; subsequent launches are automatic.

Install

uv tool install iterm2-mcp

Or from source:

git clone https://github.com/lorencarvalho/iterm2-mcp.git
cd iterm2-mcp
uv sync

Register with Claude

Claude Code:

claude mcp add iterm2 -- uvx iterm2-mcp

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Security

This server can type into terminals, run commands, and close sessions — anything you can do in iTerm2. Only connect it to MCP clients you trust. It has no sandboxing beyond what iTerm2 itself provides.

Tools

Most tools accept an optional session_id — omit it to target the currently active session.

Development

uv sync
uv run ruff check
uv run ruff format
uv run ty check

License

MIT