AI导哈

Git工作树管理服务器

一个与iTerm2集成的Git工作树管理服务器，用于自动化创建、关闭和切换Git工作树，提高开发效率。

  • by cctuan
  • Python
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 cctuan/claude-code-iterm-worktree-mcp

使用说明

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：

  1. 在iTerm2中启用Python API

    • 打开iTerm2首选项(⌘+,)
    • 首选 General → Magic
    • 检查 “启用Python API”
    • 如果系统提示，允许macOS辅助功能权限

  2. 安装Python运行时 （可选，但推荐）

    • 在iTerm2中： Scripts → Manage → Install Python Runtime
    • 这确保了iTerm2具有必要的Python环境

  3. 验证设置

    • 重新启动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?

工作流程

  1. 创建: createWorktree -指定特征名称、分支名称和工作树文件夹-自动创建工作树并切换到新的iTerm2选项卡
  2. 导航: switchToWorktree 或 openWorktree -在工作台之间无缝移动
  3. 监视器: activeWorktrees -查看所有工作树及其活动选项卡
  4. 开发：在完全集成iTerm2的独立工作台环境中工作
  5. 关闭: closeWorktree -验证更改是否已提交并推送，然后安全地移除工作台

非常适合使用隔离的git环境和无缝的iTerm2集成进行功能开发。

相关 MCP