iTerm2 MCP Server for Multiple Sessions

Overview

This MCP (Model Context Protocol) server lets you manage multiple iTerm2 sessions from a single, external process. It implements a centralized control layer that can create, route input to, and monitor several iTerm2 terminal sessions at once. The server is intended for workflows that need coordinated terminal control: demos, classroom/live-coding setups, integration tests, orchestration scripts, and automation hooks.

Running an MCP server alongside iTerm2 lets external tools send commands or snippets into one or more terminal sessions, query session state, and handle session lifecycle events. Instead of manually switching windows or copying text, you can integrate your tooling (CI, web apps, bots) with iTerm2 using a consistent API so multiple interactive shells can be driven programmatically and reproducibly.

Features

• Centralized control of multiple iTerm2 sessions
• Create and destroy sessions programmatically
• Send commands or text to individual sessions or broadcast to many
• Query session metadata (id, title, working directory, PID)
• Simple JSON-based API (HTTP/WebSocket/CLI adapters possible)
• Optional authentication and origin restrictions
• Logging and session activity history for auditing and replay
• Lightweight: designed to run alongside existing iTerm2 setups

Installation / Configuration

The repository contains a small server you can run locally or inside a container. Typical installation steps:

1. Clone the repository:

git clone https://github.com/rishabkoul/iTerm-MCP-Server.git
cd iTerm-MCP-Server

2. Create a Python virtual environment and install dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. Start the server (example command — actual entrypoint may vary):

# Example: run server with default config
python -m iterm_mcp_server

Example YAML configuration (config.yml):

# config.yml
socket_path: "/tmp/iterm-mcp.sock"   # path used by iTerm2 or local adapter
http_port: 8765                      # optional HTTP API port
log_level: "info"
allowed_origins:
  - "http://localhost:3000"
auth_token: "changeme"               # optional API token

Run with explicit config:

python -m iterm_mcp_server --config config.yml

Docker example:

docker build -t iterm-mcp-server .
docker run -it --rm \
  -v /tmp/iterm-mcp.sock:/tmp/iterm-mcp.sock \
  -p 8765:8765 \
  iterm-mcp-server

Note: The exact file names and flags in the repo may differ. Check the repository root for the main script and README for the authoritative command names.

Available Tools / Resources

The server typically exposes a small set of API endpoints or message types for controlling sessions. Example endpoints and payloads:

• List sessions

  • GET /sessions
  • Response:

  [
    {"id": "s1", "title": "app-1", "cwd": "/home/user/project", "pid": 1234}
  ]
  

• Create a session

  • POST /sessions
  • Request:

  {"title": "demo", "command": "/bin/zsh", "cwd": "/home/user"}
  

  • Response:

  {"id": "s2", "status": "created"}
  

• Send input to a session

  • POST /sessions/{id}/send
  • Request:

  {"text": "echo hello && ls -la\n"}
  

• Broadcast to multiple sessions

  • POST /broadcast
  • Request:

  {"ids": ["s1","s2"], "text": "git pull && ./deploy.sh\n"}
  

• WebSocket endpoint (optional) for real-time session events and output streaming:

  • ws://localhost:8765/mcp
  • Messages are JSON objects containing event, session id and payload.

These examples show typical patterns; check the repository for exact API and authentication mechanisms.

Use Cases

1. Live demos and presentations

   • Launch one session per demo target, then use the server to step through commands across windows in a reproducible order. Example: broadcast a command to set up environments across multiple panes at once.

2. Teaching and onboarding

   • Instructors can prepare multiple pre-configured shells and push code snippets or exercises to students’ terminals (or to multiple panes) so everyone follows the same sequence.

3. Cross-environment test orchestration