iTerm2工作树MCP服务器
一个模型上下文协议（MCP）服务器，通过Claude Code的iTerm2集成自动化git工作树管理。
https://github.com/user-attachments/assets/16188878-8fe8-450c-b2a3-cfd617d74f43
先决条件
iTerm2 Python API设置（必需）
在使用此MCP服务器之前，您 必须 启用iTerm2的Python API：
- 在iTerm2中启用Python API
- 打开iTerm2首选项(⌘+,) - 首选 General → Magic - 检查 “启用Python API” - 如果系统提示，允许macOS辅助功能权限
- 安装Python运行时 （可选，但推荐）
- 在iTerm2中： Scripts → Manage → Install Python Runtime - 这确保了iTerm2具有必要的Python环境
- 验证设置
- 重新启动iTerm2 - API现在应该监听端口1912
⚠️ 常见错误：如果你看到 [Errno 61] Connect call failed ('127.0.0.1', 1912)，这意味着Python API未启用。按照上述步骤操作。安装
使用uvx（推荐）
使用此MCP服务器的最简单方法是 uvx，它自动处理依赖关系：
claude mcp add -s user worktree -- uvx --from /path/to/claude-code-iterm-worktree-mcp worktree-mcp-server直接使用Python（遗留）
或者，您可以手动安装依赖项并使用Python运行：
pip install iterm2
claude mcp add -s user worktree -- python3 /path/to/worktree_mcp_server.py特性
核心工作树管理
- 创建工作树：使用功能分支创建新的git工作树，并在新的iTerm2选项卡中打开它
- 关闭工作树：在确认工作台清洁并被推动后，安全关闭工作台
- 打开工作树：在新的iTerm2选项卡中打开现有的工作树（如果已打开，则使用强制选项进行覆盖）
导航与发现
- 主动工作树：列出所有git工作树，并显示它们在哪些iTerm2选项卡中运行
- 切换到工作树：按名称或特定选项卡ID快速切换到工作树的iTerm2选项卡
智能标签检测
- 动态发现：无元数据文件-通过实时分析选项卡的工作目录来查找选项卡
- 多标签支持：显示在不同窗口中运行相同工作树的所有选项卡
- 窗口上下文：标识当前窗口中的选项卡
thisWindow旗帜
可用工具
| 工具 | 说明 | 参数 |
|---|---|---|
createWorktree | 创建新的工作树+分支，在iTerm2选项卡中打开 | feature_name, branch_name, worktree_folder, description, start_claude? |
closeWorktree | 验证、关闭和清理工作台 | worktree_name |
activeWorktrees | 列出所有工作树及其iTerm2选项卡 | 无 |
switchToWorktree | 切换到工作台的iTerm2选项卡 | worktree_name, tab_id? |
openWorktree | 在新选项卡中打开现有工作树 | worktree_name, force? |
工作流程
- 创建:
createWorktree-指定特征名称、分支名称和工作树文件夹-自动创建工作树并切换到新的iTerm2选项卡 - 导航:
switchToWorktree或openWorktree-在工作台之间无缝移动 - 监视器:
activeWorktrees-查看所有工作树及其活动选项卡 - 开发：在完全集成iTerm2的独立工作台环境中工作
- 关闭:
closeWorktree-验证更改是否已提交并推送，然后安全地移除工作台
非常适合使用隔离的git环境和无缝的iTerm2集成进行功能开发。