Git MCP 服务器故障排除指南

此仓库记录了与 Git MCP 服务器连接问题的常见解决方案，基于真实世界的实践经验。

🎉 安装成功方法

我们找到了解决办法！ 经过大量故障排除后，我们发现 UVX 安装程序无法正确处理带作用域的包名。

请参阅我们的安装成功指南了解完整的解决方案和步骤。

快速开始

如果您正在经历 Git MCP 服务器连接问题：

1. 运行我们的诊断脚本以识别常见问题
2. 遵循连接检查清单进行逐步验证
3. 检查日志分析以了解错误模式
4. 实现特定问题的解决步骤

常见连接问题

1. 包名错误

npm 错误 404 Not Found - GET https://registry.npmjs.org/mcp-server-git - 没有找到

问题： 您尝试使用 mcp-server-git，但此包在 npm 注册表中不存在。

解决方案： 使用正确的包名格式：

# 对于 UVX 安装程序
uvx modelcontextprotocol-git-server

# 对于 NPM 安装程序（如果有）
npm install -g @modelcontextprotocol/git-server

2. UVX 包名格式问题

错误: 不是有效的包或额外名称: "@modelcontextprotocol/git-server"

问题： UVX 不接受带有 @ 符号的范围包名。

解决方案： 删除 @ 符号并使用连字符：

uvx modelcontextprotocol-git-server

3. 服务器传输关闭

Server transport closed unexpectedly, 这可能是由于进程提前退出。

问题： 服务器进程在初始化之前过早终止。

潜在原因：

• 环境变量不正确
• 端口冲突
• 缺少依赖项
• 权限问题
• 标记配置错误

4. 身份验证问题

身份验证问题通常显示与我们看到的不同类型的错误。当您看到：

Server disconnected. {"context":"connection"}

这表示连接问题而不是身份验证问题。

额外的连接问题

端口冲突

如果 Claude 桌面或其他应用程序使用相同的端口：

错误: EADDRINUSE: address already in use :::3000

解决方案：

• 在配置中更改端口
• 使用环境变量：GIT_SERVER_PORT=3001
• 检查并关闭冲突进程

环境变量问题

不同的 Git 提供程序需要不同的环境变量：

• GitHub: GITHUB_TOKEN
• GitLab: GITLAB_PERSONAL_ACCESS_TOKEN（而不是 GITLAB_ACCESS_TOKEN）

错误命名的环境变量会导致连接失败。

进程管理问题

多个服务器实例可能会相互干扰：

• 陈旧的锁定文件阻止新服务器实例启动
• 多个进程尝试写入同一日志时发生日志文件访问冲突
• Claude 桌面可能启动自己的服务器实例导致冲突

工具和资源

验证步骤

在尝试修复后，通过以下方式验证连接：

# 使用自定义端口启动服务器
uvx modelcontextprotocol-git-server --env GIT_SERVER_PORT=3001

# 重新启动应用程序
# 然后检查功能菜单中的 Git 工具

查找这些日志表示成功：

[git-server] [info] Server started and connected successfully