it2mcp
MCP server for controlling iTerm2 from AI assistants, editors, and other MCP clients.
Built on iTerm2's official Python API, it2mcp exposes 40 tools for managing sessions, windows, tabs, profiles, and more — with a security model that keeps you in control.
Prerequisites
- macOS with iTerm2 installed
- Python 3.10+
- uv (recommended) or pip
- iTerm2's Python API enabled: Preferences → General → Magic → Enable Python API
Installation
git clone https://github.com/youruser/it2mcp.git
cd it2mcp
uv sync
Usage
Add to Claude Code
claude mcp add -s user it2mcp -- uv --directory /path/to/it2mcp run it2mcp
Add to other MCP clients
Add to your MCP client configuration:
{
"mcpServers": {
"it2mcp": {
"command": "uv",
"args": ["--directory", "/path/to/it2mcp", "run", "it2mcp"]
}
}
}
Run standalone
uv run it2mcp
Security
it2mcp ships secure by default. Two mechanisms protect your terminal sessions:
Session tagging
Sessions must be explicitly tagged before MCP can interact with them. Untagged sessions are invisible to all tools except session_list (which shows their mcp_enabled status so you know what to tag).
Tag a session (run this in the session's terminal):
# Using the it2 CLI
it2 session set-var user.mcp_enabled true
# Or using iTerm2's escape sequence (no dependencies)
printf '\033]1337;SetUserVar=%s=%s\007' mcp_enabled $(echo -n true | base64)
Untag a session:
it2 session set-var user.mcp_enabled false
Tags are not persistent — they reset when the session ends. This is intentional: you opt in per-session, per-lifetime.
Permission tiers
Tools are grouped into three tiers:
| Tier | Tools | Description |
|---|---|---|
| read | session_list, session_read, session_get_variable, tab_list, window_list, app_get_focus, profile_list, profile_show, app_version, app_theme, window_arrange_list | Observation only |
| interact | session_send, session_run, session_split, session_clear, session_focus, session_set_name, session_set_variable, tab_new, tab_select, tab_next, tab_prev, tab_move, window_new, window_focus, window_move, window_resize, window_fullscreen, window_arrange_save, window_arrange_restore, app_activate, broadcast_on, broadcast_off, broadcast_add, profile_apply, batch, send_keystrokes | Can send input and modify layout |
| destructive | session_close, session_restart, tab_close, window_close | Can terminate sessions and close windows |
By default, only read is enabled.
Audit log
Every tool invocation is logged to ~/.local/share/it2mcp/audit.jsonl with timestamp, tool name, parameters, and result.
Configuration
Create ~/.config/it2mcp/config.yaml:
# Which permission tiers to enable
permissions:
- read
- interact
# - destructive
# Require sessions to have user.mcp_enabled set (default: true)
require_tag: true
# Audit log path (set to null to disable)
audit_log: ~/.local/share/it2mcp/audit.jsonl
Override the config path with the IT2MCP_CONFIG environment variable.
Tools
Session
| Tool | Tier | Description |
|---|---|---|
session_list | read | List all sessions with IDs, names, sizes, and mcp_enabled status |
session_read | read | Read visible screen contents |
session_get_variable | read | Get a session variable (e.g. path, name, tty) |
session_send | interact | Send text without pressing Enter |
session_run | interact | Execute a command (text + Enter) |
session_split | interact | Split into a new pane |
session_clear | interact | Clear screen (Ctrl+L) |
session_focus | interact | Activate a specific session |
session_set_name | interact | Set session name |
session_set_variable | interact | Set a session variable |
session_close | destructive | Close a session |
session_restart | destructive | Restart a session |
Window
| Tool | Tier | Description |
|---|---|---|
window_list | read | List all windows with positions and sizes |
window_arrange_list | read | List saved window arrangements |
window_new | interact | Create a new window |
window_focus | interact | Activate a specific window |
window_move | interact | Move window to screen position |
window_resize | interact | Resize a window |
window_fullscreen | interact | Set fullscreen on/off/toggle |
window_arrange_save | interact | Save current arrangement |
window_arrange_restore | interact | Restore a saved arrangement |
window_close | destructive | Close a window |
Tab
| Tool | Tier | Description |
|---|---|---|
tab_list | read | List all tabs with IDs and active state |
tab_new | interact | Create a new tab |
tab_select | interact | Select tab by ID or index |
tab_next | interact | Switch to next tab |
tab_prev | interact | Switch to previous tab |
tab_move | interact | Move tab to its own window |
tab_close | destructive | Close a tab |
App
| Tool | Tier | Description |
|---|---|---|
app_get_focus | read | Get focused window/tab/session info |
app_version | read | Get iTerm2 version |
app_theme | read | Get or set theme |
app_activate | interact | Bring iTerm2 to front |
Broadcast
| Tool | Tier | Description |
|---|---|---|
broadcast_on | interact | Enable broadcasting to all sessions in current tab |
broadcast_off | interact | Disable broadcasting |
broadcast_add | interact | Create broadcast group with specific sessions |
Profile
| Tool | Tier | Description |
|---|---|---|
profile_list | read | List all profiles |
profile_show | read | Show profile details |
profile_apply | interact | Apply a profile to a session |
Batch
| Tool | Tier | Description |
|---|---|---|
batch | interact | Execute multiple operations in a single iTerm2 connection |
The batch tool accepts a list of operations and runs them sequentially over one connection. Supports a sleep operation for timing between steps. Each operation's tier is checked individually.
[
{"op": "session_run", "command": "echo hello"},
{"op": "sleep", "seconds": 1.0},
{"op": "session_read"}
]
Acknowledgments
Built on top of it2 by @mkusaka — a powerful CLI for controlling iTerm2 via its Python API. it2mcp wraps the same underlying iterm2 Python API and was heavily inspired by it2's command structure.
License
MIT