iTerm2 Worktree MCP Server

A Model Context Protocol (MCP) server that automates git worktree management with iTerm2 integration for Claude Code.

Screen.Recording.2025-07-11.at.1.39.29.pm.mp4

Prerequisites

iTerm2 Python API Setup (Required)

Before using this MCP server, you must enable iTerm2's Python API:

1. Enable Python API in iTerm2

   • Open iTerm2 Preferences (⌘+,)
   • Go to General → Magic
   • Check "Enable Python API"
   • Allow macOS Accessibility permissions if prompted

2. Install Python Runtime (Optional but recommended)

   • In iTerm2: Scripts → Manage → Install Python Runtime
   • This ensures iTerm2 has the necessary Python environment

3. Verify Setup

   • Restart iTerm2
   • The API should now be listening on port 1912

⚠️ Common Error: If you see [Errno 61] Connect call failed ('127.0.0.1', 1912), it means the Python API is not enabled. Follow the steps above.

Installation

Using uvx (Recommended)

The easiest way to use this MCP server is with uvx, which automatically handles dependencies:

claude mcp add -s user worktree -- uvx --from /path/to/claude-code-iterm-worktree-mcp worktree-mcp-server

Using Python directly (Legacy)

Alternatively, you can install dependencies manually and run with Python:

pip install iterm2
claude mcp add -s user worktree -- python3 /path/to/worktree_mcp_server.py

Features

Core Worktree Management

• Create Worktree: Creates a new git worktree with a feature branch and opens it in a new iTerm2 tab
• Close Worktree: Safely closes worktrees after verifying they're clean and pushed
• Open Worktree: Opens an existing worktree in a new iTerm2 tab (with force option to override if already open)

Navigation & Discovery

• Active Worktrees: Lists all git worktrees and shows which iTerm2 tabs they're running in
• Switch to Worktree: Quickly switch to a worktree's iTerm2 tab by name or specific tab ID

Smart Tab Detection

• Dynamic Discovery: No metadata files - finds tabs by analyzing their working directories in real-time
• Multi-Tab Support: Shows all tabs running the same worktree across different windows
• Window Context: Identifies which tabs are in the current window with thisWindow flag

Available Tools

Tool	Description	Parameters
createWorktree	Create new worktree + branch, open in iTerm2 tab	feature_name, branch_name, worktree_folder, description, start_claude?
closeWorktree	Validate, close, and cleanup worktree	worktree_name
activeWorktrees	List all worktrees and their iTerm2 tabs	None
switchToWorktree	Switch to worktree's iTerm2 tab	worktree_name, tab_id?
openWorktree	Open existing worktree in new tab	worktree_name, force?

Workflow

1. Create: createWorktree - Specify feature name, branch name, and worktree folder - automatically creates the worktree and switches to a new iTerm2 tab
2. Navigate: switchToWorktree or openWorktree - Seamlessly move between worktrees
3. Monitor: activeWorktrees - See all worktrees and their active tabs
4. Develop: Work in isolated worktree environments with full iTerm2 integration
5. Close: closeWorktree - Verify changes are committed and pushed, then safely remove the worktree

Perfect for feature development with isolated git environments and seamless iTerm2 integration.