Which integrations are available for this server?

Provides comprehensive tools for managing iTerm2 terminal sessions, windows, tabs, and profiles, including the ability to read screen contents, execute commands, and control window layouts.

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@it2mcp list my open sessions and read the content of the active one" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Install Server

A

security – no known vulnerabilities

A

license - permissive license

A

quality - confirmed to work

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

it2mcp

it2mcp

Prerequisites

Installation

Usage

Add to Claude Code

Add to other MCP clients

Run standalone

Security

Session tagging

Permission tiers

Audit log

Configuration

Tools

Session

Window

Tab

App

Broadcast

Profile

Batch

Acknowledgments

License

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API