mcp-server-iterm2

CI PyPI Python

A Model Context Protocol (MCP) server that exposes iTerm2 to agents for observation and non-destructive annotation. Agents can inspect sessions and decorate them (badge, title, tab color, user variables, notifications) but cannot inject keystrokes, close or spawn sessions, or otherwise alter the user's working environment.

Install

Configure your MCP client (e.g. Claude Desktop, Claude Code):

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

Requires macOS, iTerm2, and uv installed.

First run

On first invocation, iTerm2 prompts you to authorize API access for the script. Approve it. Subsequent runs are silent.

If you previously denied access: iTerm2 → Preferences → General → Magic → enable "Python API" and remove mcp-server-iterm2 from the denial list.

Tools

Read

Tool Description
list_sessions Tree of windows → tabs → sessions, plus a top-level buried_sessions list.
get_session_info Title, working dir, profile, badge, dimensions, TTY
get_screen_contents Visible buffer + cursor position
get_scrollback Last N lines (default 200, max 5000)
get_recent_output Output since a cursor marker (cursor-based pagination)
get_selection Currently-selected text
get_variable Read a variable by fully-qualified name (e.g. session.path, user.badge)
list_profiles Available profiles by name and GUID

Write (non-destructive)

Tool Description
set_badge Set session badge text
set_title Override session title
set_tab_color Tint the tab (RGB 0-255)
set_user_variable Set a user.* session variable
post_notification Post a macOS notification banner

Every session-targeted tool accepts an optional session_id. If omitted, the server uses $ITERM_SESSION_ID from its environment — which works automatically when the agent runs inside iTerm2.

Notes on rendering

  • Badge: for set_badge to display anything, your iTerm2 profile's badge format must include \(user.badge). Configure in iTerm2 → Profiles → General → Badge.
  • Title: whether a set_title override sticks depends on the profile's "Allow terminal apps to change title" and "Title Components" settings. The server always sets the override; iTerm2 controls the rendering.
  • Tab color: set_tab_color writes the legacy tab color plus both light- and dark-mode variants, so the tint takes effect regardless of the profile's split-color preference.
  • Notifications: routed through macOS via osascript. Make sure Terminal/iTerm2 notifications are allowed in System Settings if banners don't appear.

Excluded by design

For safety, these are not exposed: send_text/keystroke injection, closing or spawning sessions/tabs/windows, splitting panes, focus changes, broadcasting input.

Security model

Installing this server gives any MCP client that uses it broad read access to your iTerm2 sessions (screen contents, scrollback, working directories, variables) and limited write access (badge, title, tab color, user.* variables, macOS notifications). Read tools can capture passwords visible on screen; write tools can spoof titles and notifications. The full threat model and reporting flow live in SECURITY.md.

Development

uv sync
uv run pytest tests/unit       # 122 unit tests
uv run ruff check .            # lint
uv run ruff format --check .   # format check
uv run ty check src            # type check

Integration tests (pytest -m integration) and the smoke script (scripts/smoke.py) require running inside an iTerm2 session. See CONTRIBUTING.md for the full development guide and ARCHITECTURE.md for how the pieces fit together.

API stability

This project follows semantic versioning. The current release is in the 0.x series; expect schema refinements between minor versions as the tool surface settles in response to real-world feedback. Pin to a specific version in production.

From 1.0 onward the following will be part of the stable contract — breaking any of them requires a major bump:

  • Tool names and the set of tools. Names and removal of tools are stable; new tools may be added in minor releases.
  • Tool argument names and types. New optional arguments may be added; existing argument names, types, and required-ness do not change.
  • Top-level response keys and value types. New keys may be added in minor releases; existing keys and their types do not change.
  • Error envelope shape. MCPIterm2Error subclasses surface actionable text via to_error_text; unknown exceptions collapse to Internal error: <ExceptionClass>. Callers may pattern-match on this envelope.

Not part of the stable surface:

  • Internal Python modules (server.py, connection.py, tools/*, errors.py, output_cursor.py) — these are implementation details.
  • Specific cursor payload encoding for get_recent_output. Treat the cursor as opaque; pass back whatever the server returned.
  • iTerm2 SDK and macOS version compatibility windows — these follow upstream and may change in minor releases.

Documentation

License

MIT — see LICENSE.