Local Git MCP

本地git mcp

一个轻量级的MCP服务器，代表AI编码助手处理git操作。作为本地HTTP服务运行——默认情况下没有外部网络暴露。

为什么？

当AI助手在带有文件系统挂载的沙盒环境中运行时（例如FUSE/bindfs），git锁文件(HEAD.lock, index.lock由于权限限制，沙盒进程无法清理在提交期间创建的文件（如文件、文件等）。这会阻止后续的git操作。

沙盒代理无法通过生成辅助进程来解决这个问题——子进程继承了沙盒。解决方案是一个持续运行的服务 外面 代理通过HTTP连接到的沙箱。

运作原理

服务器在任何沙箱外作为每个用户的服务（macOS LaunchAgent或Linux systemd用户单元）运行，可以完全访问您的git凭据和文件系统。您的AI代理通过HTTP连接到它 127.0.0.1.

Sandboxed agent ──HTTP──► local-git-mcp service (runs as your user)
                                  ▼
                                 git (full host permissions)

身份验证令牌（存储在模式为0600的文件中）确保只有您的用户帐户可以使用该服务。看 安全模型 了解详情。

工具

安装

curl -fsSL https://raw.githubusercontent.com/jrokeach/local-git-mcp/main/install.sh | bash

安装程序的作用：

1. 在您的系统上查找Python 3.11+解释器
2. 将此仓库克隆到 ~/.local/share/local-git-mcp （用覆盖 LOCAL_GIT_MCP_DIR)
3. 创建虚拟环境并安装软件包
4. 在以下位置生成身份验证令牌 ~/.local/share/local-git-mcp/auth-token （模式0600）
5. 检查服务使用的所需本地工具，包括 lsof 用于检测过期锁
6. 注册并启动每个用户的服务：

- macOS：LaunchAgent(com.local-git-mcp) - Linux：systemd用户单元(local-git-mcp.service)

完成后，安装程序将打印一个准备粘贴的MCP客户端配置代码段（带有您的身份验证令牌）。打印的URL使用默认端口 44514；如果在另一个端口上运行该服务，请相应地更新URL。

安装 没有 注册服务（例如手动运行）：

curl -fsSL https://raw.githubusercontent.com/jrokeach/local-git-mcp/main/install.sh | bash -s -- --no-service

手动安装

git clone https://github.com/jrokeach/local-git-mcp.git
cd local-git-mcp
pip install .        # or: uv pip install .
local-git-mcp       # starts on 127.0.0.1:44514

卸载

curl -fsSL https://raw.githubusercontent.com/jrokeach/local-git-mcp/main/uninstall.sh | bash

这将：

1. 停止并删除系统服务（macOS上的LaunchAgent，Linux上的systemd单元）
2. 删除包含身份验证令牌的安装目录

卸载程序会 不 移除 .git-mcp-allowed 存储库中的哨兵文件或MCP客户端配置条目——这些必须手动清理。

如果使用自定义安装路径，请设置相同的环境变量：

curl -fsSL ... | LOCAL_GIT_MCP_DIR=/your/custom/path bash

MCP客户端配置

替换 YOUR_TOKEN_HERE 下面是内容 ~/.local/share/local-git-mcp/auth-token安装脚本使用默认端口打印完整的配置代码段，并填写您的令牌 44514.

克劳德代码（CLI/IDE扩展）

因为配置包含每个用户的身份验证令牌，请使用 用户范围 因此，它适用于所有项目，而无需签入git。最简单的方法是CLI：

claude mcp add local-git-mcp --transport http --scope user \
  --header "Authorization: Bearer YOUR_TOKEN_HERE" \
  http://127.0.0.1:44514/mcp

或手动添加到 ~/.claude.json:

{
  "mcpServers": {
    "local-git-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:44514/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}

哪个配置文件？ Claude Code有四个MCP作用域。 用户 (~/.claude.json)这里推荐使用，因为令牌是特定于用户的，服务器在所有项目中都很有用。避免项目范围 .mcp.json 因为它被签入git并将暴露令牌。如果您只希望服务器位于单个项目中，请使用 --scope local 相反。

克劳德桌面

Claude Desktop不直接支持自定义HTTP标头。使用 mcp-remote 作为传递不记名令牌的代理。这需要安装Node.js/npm； npx 将下载 mcp-remote 首次使用时自动。

在以下位置打开配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

（或通过应用程序：设置→ 开发者→ 编辑配置。)

添加到 mcpServers 对象：

{
  "mcpServers": {
    "local-git-mcp": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:44514/mcp",
        "--header",
        "Authorization: Bearer YOUR_TOKEN_HERE"
      ]
    }
  }
}

每个存储库访问控制

服务器会 不 在任意路径上操作。在执行任何git操作之前，它会通过检查哨兵文件来验证目标存储库是否已明确选择加入。

允许服务器在存储库上运行，创建一个 .git-mcp-allowed 存储库根目录中的文件：

cd /path/to/your/repo
touch .git-mcp-allowed
git add .git-mcp-allowed
git commit -m "Allow local-git-mcp operations"

该文件可能为空或包含可选的自由形式注释。如果文件不存在，则对该存储库的所有操作都将被拒绝，并显示明确的错误消息。

安全原理： 如果没有这个，任何可以向服务器进行身份验证的进程都可以在用户有权访问的任何目录上请求git操作。哨兵文件确保必须在仓库级别由对该仓库具有写访问权限的人有意授予访问权限。

凭据和身份验证

服务如何验证git操作

该服务以如下方式运行 您的用户帐户 （通过LaunchAgent或systemd用户单元）。它不是系统范围的守护进程，也不以root身份运行。因为它像你一样运行，所以它继承了你的完整环境：

• SSH密钥 从 ~/.ssh/
• Git凭据助手 从 ~/.gitconfig （例如。 osxkeychain 在macOS上， libsecret 在Linux上）
• macOS钥匙扣 条目
• 环境变量 喜欢 SSH_AUTH_SOCK, GIT_SSH_COMMAND, GIT_ASKPASS
• Git配置 从 ~/.gitconfig 回购级别 .git/config

服务器不存储、管理或代理任何凭据。如果 git push 或 git pull 遇到身份验证错误时，git会按原样返回错误。由于服务器以非交互方式运行，需要终端输入的凭据提示将彻底失败，而不是挂起。

服务如何对客户端进行身份验证（身份验证令牌）

对服务器的每个请求都必须在 Authorization 头球令牌是一个随机的64个字符的十六进制字符串，存储在 ~/.local/share/local-git-mcp/auth-token 带文件模式 0600 （所有者只读）。

为什么需要令牌： 服务器监听TCP端口。TCP端口的作用域不限于用户——机器上运行的任何进程都可以连接到 127.0.0.1。如果没有令牌，任何本地用户或进程都可以向您的服务发送请求，并使用您的凭据执行git操作。令牌确保只有可以读取令牌文件的进程（即以用户或root身份运行的进程）才能进行身份验证。

在多用户计算机上

每个用户都运行自己的服务实例。身份验证令牌文件(0600)确保用户B无法对用户A的服务进行身份验证，即使TCP端口访问不是用户范围的。如果多个用户安装该服务，则每个用户应使用不同的端口（通过配置 --port 或 LOCAL_GIT_MCP_PORT).

这 /health 端点是唯一未经身份验证的端点，因此监控工具可以在没有令牌的情况下检查服务的活性。

配置

服务器通过CLI参数或环境变量接受配置：

要监听所有接口（例如，从另一台机器进行远程访问）：

local-git-mcp --host 0.0.0.0

当暴露给其他机器时，确保令牌与授权客户端安全共享。

安全模型

• 需要身份验证令牌：每个请求（除 /health)必须包含有效的Bearer令牌。令牌文件是使用mode创建的 0600，确保只有拥有它的用户可以读取它。
• 需要Sentinel文件：每个存储库都必须包含 .git-mcp-allowed 服务器将对其执行任何git命令之前的文件。
• 存储库验证：服务器验证 repo_path 是一个真正的git存储库的实际根，在执行任何命令之前，向git询问存储库的顶层。
• 默认情况下为本地主机：绑定到 127.0.0.1，无法从网络访问。可配置为有意远程访问。
• 按用户隔离：每个用户都使用自己的令牌和凭据运行自己的服务。用户之间没有共享状态。
• 锁定文件清理: git_commit 只有在检查已知的过时锁文件是否足够旧且不再使用后，才会删除这些文件。
• 未存储凭据：服务器将所有身份验证委托给主机操作系统的现有git凭据配置。

发展

使用Python 3.11+运行最小回归测试：

python3.11 -m unittest discover -s tests -p 'test_server.py' -v

许可证

麻省理工学院