iTerm2 MCP Server

An MCP (Model Context Protocol) server that lets Claude interact with your iTerm2 terminal sessions with an approval workflow. You see proposed commands before they execute!

Features

• 🔍 List all iTerm2 sessions - See all your terminal windows, tabs, and sessions

• 📝 Propose commands - Claude types commands but waits for your approval

• ✅ Execute on approval - You explicitly approve each command before it runs

• 👀 Read output - Claude can see command results to help debug or continue

• ⚡ Run and wait - Executing returns just the new output once the command finishes (no polling)

• 🪶 Token-lean - Reads return only output Claude hasn't seen yet, capped, optionally grep-filtered

• 🎯 Targets sessions by ID - Work in any pane; refuses the pane Claude itself runs in

• 🆕 Create new tabs - Spin up fresh terminal sessions as needed

• 🌐 Works with SSH - Control remote sessions just like local ones

Related MCP server: iterm2-mcp

How It Works

1. You chat with Claude in Claude Code or the Claude desktop app

2. Claude proposes a command - It gets typed in your terminal but doesn't execute

3. You review it - See the actual command in your terminal window

4. You approve or reject - Tell Claude to proceed or cancel

5. Claude executes - Only then does it press Enter

Installation

Prerequisites

• macOS (tested on macOS 10.15+)

• iTerm2 installed

• Node.js 18+ (required for MCP SDK)

• Claude Code and/or Claude Desktop

Quick Install

cd iterm2-mcp-server
./install.sh

The installer will:

• Detect your Node.js installation (handles nvm automatically)

• Install npm dependencies

• Show you the exact config to add

• Guide you through iTerm2 automation setup

Manual Setup

If you prefer to set up manually:

1. Install Dependencies

npm install
chmod +x index.js

2. Find Your Node.js Path

CRITICAL: You must use the full path to Node.js, not just "node".

# If using nvm (most common issue)
which node
# Example output: /Users/yourname/.nvm/versions/node/v20.20.0/bin/node

# If using Homebrew
which node
# Example output: /opt/homebrew/bin/node

Why? Claude Desktop doesn't inherit your shell's nvm setup, so it defaults to an old Node version if you just use "node". Using the full path ensures it always uses the right version.

3. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "iterm2": {
      "command": "/Users/yourname/.nvm/versions/node/v20.20.0/bin/node",
      "args": ["/absolute/path/to/iterm2-mcp-server/index.js"]
    }
  }
}

Replace:

• The node path with YOUR actual path from step 2

• The index.js path with the absolute path to where you installed this

3b. Or add to Claude Code

claude mcp add --scope user iterm2 -- "$(which node)" /absolute/path/to/iterm2-mcp-server/index.js

4. Set Up iTerm2 Automation (One-Time)

IMPORTANT: To grant initial permissions, you need to temporarily allow automation:

1. Open iTerm2 Preferences (⌘,)

2. Go to General → Magic

3. Change "Require 'Automation' permission" to: "Allow all apps to connect"

4. Restart iTerm2

5. Restart Claude Desktop (⌘Q then reopen)

6. Use Claude to interact with iTerm2 once (e.g., "list my sessions")

7. Change back to "Require 'Automation' permission" for security

Why? macOS needs to see an actual automation attempt before it registers Claude's access. This one-time setup makes it work.

5. Restart Claude Desktop

Quit completely (⌘Q) and reopen.

Usage

Basic Workflow

1. Open Claude Desktop and start a conversation

2. Make sure iTerm2 is running

3. Ask Claude to help with terminal tasks

Example Conversations

List Sessions:

You: "List my iTerm sessions"
Claude: [shows your sessions]

Run Commands:

You: "Check disk space on my system"
Claude: "I've typed 'df -h' in your terminal. Should I execute it?"
You: "Yes"
Claude: [executes and shows results]

SSH Sessions:

You: "SSH to my server and check if nginx is running"
Claude: [proposes: ssh user@server]
You: "Go ahead"
Claude: [connects, then proposes: systemctl status nginx]

Tools

session_id is optional after the first call; it defaults to the last session used.

Limitations

• Multi-line commands are refused by design. Join with ;/&&, or write a script file and run that.

• Prompt detection is heuristic (ends in $ # % > ❯ -->, --More--, Password:, ?; right-aligned prompt segments are ignored). If it doesn't match your prompt, output is returned once it stops changing (settle_ms), or pass prompt_regex.

• Staged-command tracking lives in the server process; if you run or clear a staged command by hand, the next propose notices the line changed and carries on.

Security

What's Protected

✅ Explicit approval required - Commands are typed but not run automatically
✅ Visible actions - Every command appears in your terminal
✅ Local only - No network communication, MCP over stdio
✅ No credentials stored - Uses your existing SSH sessions
✅ SSH safe - Works with remote sessions without installing anything remotely

Best Practices

• Review every command before approving

• Use iTerm2's "Require 'Automation' permission" setting after initial setup

• Don't approve commands you don't understand

• Claude can see terminal output after commands run

Troubleshooting

"Node.js version too old" or MCP server crashes

Problem: You're using Node.js < 18
Solution: The installer handles this automatically, or manually:

# Check version
node --version

# If using nvm
nvm use 20  # or higher

# Update your config with the new path
which node  # Use this full path in claude_desktop_config.json

"Can't get session" or AppleScript errors

Problem: iTerm2 automation not set up
Solution:

1. Temporarily set iTerm2 to "Allow all apps to connect"

2. Restart iTerm2 and Claude Desktop

3. Use Claude once ("list my sessions")

4. Lock down automation again

Commands don't appear in terminal

Problem: Wrong session ID or permissions
Solution:

• Ask Claude to run list_iterm_sessions again (IDs change when panes are closed/reopened)

• "Session not found" means the ID is stale; "Not permitted" means Automation permission

"Server disconnected" in logs

Problem: Usually Node version mismatch
Solution:

• Check ~/Library/Logs/Claude/mcp-server-iterm2.log

• Verify you're using the full path to Node 18+

• Run ./install.sh again to get the right path

Permission dialog never appears

Problem: macOS doesn't show the automation dialog
Solution:

• Use the temporary "Allow all apps" method described above

• Make sure iTerm2 is running when you restart Claude

• Check System Settings → Privacy & Security → Automation

Architecture

┌─────────────────┐
│  Claude Code /  │  
│  Claude Desktop │  
└────────┬────────┘
         │ MCP Protocol
         │ (JSON-RPC over stdio)
         ▼
┌─────────────────┐
│  MCP Server     │  
│  (Node.js)      │  
└────────┬────────┘
         │ AppleScript
         │ (session by ID)
         ▼
┌─────────────────┐
│    iTerm2       │  
│  (your shells)  │  
└─────────────────┘

Development

Running Tests

# Check if iTerm2 can be controlled
osascript -e 'tell application "iTerm2" to get version'

# End-to-end test: opens a scratch tab, runs echo/seq through the server, closes it
npm test

Logs

# Watch MCP server logs
tail -f ~/Library/Logs/Claude/mcp-server-iterm2.log

Future Improvements

• Multi-session support (target sessions by ID) — v0.2.0

• Quote/special character handling — v0.2.0

• Multi-line commands (needs a staging approach that doesn't press Enter per line)

• Command history tracking

• Integration with tmux/screen

• Python API integration for better reliability

Contributing

Improvements welcome! Key areas:

• Safe multi-line staging

• Prompt detection for more shells/devices

• Tests and documentation

License

MIT

Credits

Built with:

• MCP SDK - Model Context Protocol from Anthropic

• AppleScript - macOS automation

• iTerm2 - Best terminal for macOS

• Node.js - Runtime environment

Acknowledgments

Special thanks to the community for testing and feedback during development!