iterm2-mcp
An MCP server that provides full control over iTerm2.
Prerequisites
- iTerm2 running on macOS.
- Preferences > General > Magic > "Enable Python API" must be checked.
- Install iTerm2 shell integration
in your shell.
run_commandand session variables likepath/jobNamedepend on it. Without it,run_commandfalls 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