Git MCP Server Troubleshooting

🚀 Git MCP 服务器故障排除指南

本仓库基于实际经验，记录了 Git MCP 服务器连接问题的常见解决方案，助您快速解决服务器连接难题。

🚀 快速开始

若您遇到 Git MCP 服务器连接问题，可按以下步骤操作：

1. 运行诊断脚本，识别常见问题。
2. 依照连接检查清单，进行逐步验证。
3. 查看日志分析，了解错误模式。
4. 执行特定问题的解决步骤。

✨ 主要特性

• 提供完整的安装成功解决方案和步骤。
• 详细列举常见及额外的连接问题，并给出对应解决办法。
• 提供多种工具和资源，助力故障排除。
• 明确验证步骤，确保连接修复成功。

📦 安装指南

我们找到解决办法啦！ 经大量故障排除，发现 UVX 安装程序无法正确处理带作用域的包名。 请查阅安装成功指南，获取完整解决方案和步骤。

💻 使用示例

基础用法

解决包名错误

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

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

解决 UVX 包名格式问题

uvx modelcontextprotocol-git-server

高级用法

验证连接

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

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

📚 详细文档

常见连接问题

1. 包名错误

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

问题：您尝试使用 mcp-server-git，但此包在 npm 注册表中不存在。 解决方案：使用正确的包名格式，见上述基础用法示例。

2. UVX 包名格式问题

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

问题：UVX 不接受带有 @ 符号的范围包名。 解决方案：删除 @ 符号并使用连字符，见上述基础用法示例。

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 桌面可能启动自己的服务器实例导致冲突

工具和资源

验证步骤

查找以下日志表示连接修复成功：

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