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

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

🚀 快速开始

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

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

✨ 主要特性

本指南提供了全面的故障排除方案，涵盖常见及额外的连接问题，还包含实用的工具和资源，助您高效解决 Git MCP 服务器连接问题。

📦 安装指南

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

💻 使用示例

常见连接问题

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