iterm2-mcp 0.1.0

MCP server that gives Claude full control over iTerm2 via the iTerm2 Python API.

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.

Tool	Purpose
list_sessions	Tree of windows/tabs/sessions with IDs
get_active_session	ID and name of the focused session
focus_session	Bring a session to the foreground
write_to_terminal	Send text (optionally with newline)
send_control_character	Send Ctrl-C, Ctrl-D, Ctrl-Z, ESC, etc.
send_escape_sequence	Send a raw ANSI escape (e.g. \x1b[2J)
read_screen	Read the visible screen as plain text
get_cursor_position	Current cursor (x, y)
run_command	Send a command and wait for COMMAND_END
create_window	Open a new iTerm2 window
create_tab	Open a new tab
split_pane	Split a pane horizontally or vertically
close_session	Close a specific session
set_session_name	Rename a session
set_badge	Set the iTerm2 badge text
clear_buffer	Clear screen and scrollback
list_profiles	Enumerate iTerm2 profiles
get_variable	Read an iTerm2 session variable

Development

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

License

MIT