Prepare the server locally
Run this once before adding it to Claude Code.
git clone https://github.com/urjitbhatia/it2mcp.git
cd it2mcp
uv syncRegister it in Claude Code
claude mcp add it2mcp -- uv --directory /path/to/it2mcp run it2mcpReplace any placeholder paths in the command with the real path on your machine.
Make your agent remember this setup
it2mcp's config, env vars, and the gotchas you hit — recalled in every future Claude Code, Cursor, and Codex session.
npx conare@latestFree · one command · indexes the sessions already on disk. Set up in the browser instead →
What it does
- Control iTerm2 sessions, windows, tabs, and profiles
- Secure session tagging to prevent unauthorized access
- Tiered permission system (read, interact, destructive)
- Audit logging for all tool invocations
- Built on the official iTerm2 Python API
Tools 5
session_listList all sessions with IDs, names, sizes, and mcp_enabled statussession_readRead visible screen contentssession_runExecute a command in a sessionwindow_listList all windows with positions and sizeswindow_newCreate a new windowEnvironment Variables
IT2MCP_CONFIGPath to the configuration fileTry it
Original README from urjitbhatia/it2mcp
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 |