GitHub MCP Custom (Cross-Platform NPX Wrapper)

GitHub MCP Custom（跨平台 NPX 封装器）

自定义打包的 GitHub MCP Server，可通过 npx 在 Windows、Linux 和 macOS 上无缝运行。它使用 Node.js 启动器封装 Go 二进制文件，让使用 Claude Desktop 的开发者无需 Docker 或手动编译即可使用 GitHub MCP 功能。

---

📦 为什么要创建此项目

官方 GitHub MCP Server 需要：

• Docker，或
• 手动编译 Go。

这些方式在 Linux/macOS 上运行良好，但会导致 Windows 使用受阻或变得复杂。

此软件包通过 npx 提供服务，无需：

• Docker
• 安装 Go
• 自定义 PATH 配置

---

🧠 此软件包的功能

• 提供跨平台的 github-mcp-custom 命令
• 通过 Node.js 封装器运行预构建的 Go 二进制文件
• 完全兼容所有操作系统上的 NPX
• 开箱即用，可与 Claude Desktop 或其他兼容 MCP 的工具配合使用
• 协议版本兼容 Claude Desktop

---

🚀 安装与使用

🔹 选项 1：通过 NPX 运行（推荐）

npx -y [email protected] stdio

首次使用时会下载软件包并自动运行。

🔹 选项 2：全局安装

npm install -g [email protected]
github-mcp-custom stdio

🔹 选项 3：直接运行可执行文件（Windows 备用方案）

如果 NPX 在 Windows 上遇到问题，请使用直接路径：

{
  "mcpServers": {
    "github": {
      "command": "C:\\Users\\[USERNAME]\\AppData\\Roaming\\npm\\node_modules\\github-mcp-custom\\dist\\github-mcp-server.exe",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

将 [USERNAME] 替换为你的实际 Windows 用户名。

注意： 为获得最佳 Claude Desktop 兼容性，请使用 @1.0.20 或更高版本。

---

🛠️ 前置条件

• 必须安装 Node.js v14 或更高版本
• 一个具有适当权限范围的有效 GitHub Personal Access Token：
  • repo（用于访问仓库）
  • read:org（用于访问组织）
  • user（用于获取用户信息）

---

🔐 创建 GitHub Personal Access Token

1. 前往 GitHub 设置 > Developer Settings > Personal Access Tokens
2. 点击“Generate new token (classic)”
3. 选择以下权限范围：
   • ✅ repo - 完全控制私有仓库
   • ✅ read:org - 读取组织和团队成员信息
   • ✅ user - 更新用户数据
4. 复制生成的令牌

---

🖥️ Claude Desktop 配置

Windows

将以下内容添加到位于此处的 Claude Desktop 配置文件中： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "[email protected]", "stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

macOS

将以下内容添加到位于此处的 Claude Desktop 配置文件中： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "[email protected]", "stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Linux

将以下内容添加到位于此处的 Claude Desktop 配置文件中： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "[email protected]", "stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

全局安装的替代配置

如果你已全局安装，可以使用：

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-custom",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

---

🎯 可用工具与功能

配置完成后，你将可以使用以下 GitHub MCP 工具：

📂 仓库管理

• search_repositories - 搜索 GitHub 仓库
• get_file_contents - 读取仓库中的文件内容
• create_or_update_file - 创建或修改文件
• create_repository - 创建新仓库
• fork_repository - 复刻仓库
• create_branch - 创建分支
• push_files - 推送文件更改
• list_commits - 查看提交历史
• get_commit - 获取特定提交的详细信息

🐛 问题与项目管理

• get_issue - 获取问题详情和时间戳
• create_issue - 创建新问题
• update_issue - 更新问题（返回包含时间戳的更新后信息）
• search_issues - 搜索所有问题
• list_issues - 列出仓库问题
• get_issue_comments - 获取问题评论和时间戳
• add_issue_comment - 为问题添加评论

🔀 拉取请求

• get_pull_request - 获取 PR 详情
• create_pull_request - 创建新的 PR
• update_pull_request - 更新现有 PR
• merge_pull_request - 合并 PR
• get_pull_request_files - 查看 PR 更改
• get_pull_request_comments - 获取 PR 评论
• create_and_submit_pull_request_review - 审查 PR

🔒 安全与扫描

• list_code_scanning_alerts - 代码安全警报
• list_secret_scanning_alerts - 密钥扫描警报

🔔 通知

• list_notifications - 获取通知
• dismiss_notification - 忽略通知
• mark_all_notifications_read - 全部标记为已读

👤 用户与上下文

• get_me - 获取已通过身份验证的用户详情
• search_users - 搜索 GitHub 用户

---

🧪 测试设置

1. 直接测试命令：

   npx -y [email protected] stdio
   

   应输出：GitHub MCP Server running on stdio

2. 使用 Claude Desktop 测试：

   • 更新配置后重启 Claude Desktop
   • 尝试询问：“你能获取我的 GitHub 用户信息吗？”
   • Claude 应该能够使用 get_me 工具

---

🔧 故障排除

常见问题

❌ Claude Desktop 中显示“Server disconnected”

• 确保使用的是 1.0.20 或更高版本
• 检查 GitHub 令牌是否有效且具有适当的权限范围
• 确认 JSON 配置有效（没有尾随逗号）

❌ “Command not found”

• 确保已安装 Node.js，且其位于 PATH 中
• 尝试运行 npm --version，验证 npm 是否正常工作

❌ “Authentication failed”

• 确认 GitHub Personal Access Token 正确
• 检查令牌是否具有所需的权限范围（repo、read:org、user）
• 确保令牌尚未过期

❌ “Method not found”错误

• 更新到最新版本：npm install -g github-mcp-custom@latest

---

📁 文件结构

github-mcp-custom/
├── bin/
│   └── index.js               # Node.js launcher
├── dist/
│   ├── github-mcp-server.exe  # Windows binary
│   ├── github-mcp-server-macos # macOS binary  
│   └── github-mcp-server-linux # Linux binary
├── package.json
└── README.md

---

🖥️ 平台兼容性

平台	已测试	备注
✅ Windows 10/11	✔️	无需 Docker 或 Go
✅ Linux (Ubuntu)	✔️	开箱即用
✅ macOS (Intel/M1)	✔️	可轻松使用 NPX

---

📈 版本历史

• v1.0.20 - 修复 Claude Desktop 协议兼容性
• v1.0.16 - 上一版本（存在连接问题）
• v1.0.x - 更早的版本

---

👷 构建方式

1. 克隆官方 GitHub MCP Server 仓库。
2. 更新协议版本，以兼容 Claude Desktop。
3. 为所有平台编译 Go 二进制文件：

   GOOS=linux GOARCH=amd64 go build -o dist/github-mcp-server-linux ./cmd/github-mcp-server
   GOOS=darwin GOARCH=amd64 go build -o dist/github-mcp-server-macos ./cmd/github-mcp-server  
   GOOS=windows GOARCH=amd64 go build -o dist/github-mcp-server.exe ./cmd/github-mcp-server
   

4. 创建 Node.js 封装脚本（bin/index.js），以支持跨平台执行。
5. 设置兼容 NPM 的 package.json，并配置适当的 bin。
6. 发布修复了协议兼容性问题的包。

---

🤝 参与贡献

欢迎贡献！请访问我们的 GitHub 仓库：

🔗 仓库： https://github.com/idletoaster/github-mcp-custom

• 🐛 报告问题： GitHub Issues
• 💡 功能建议： GitHub Discussions
• 🔧 拉取请求： 欢迎提交改进和修复

开发环境设置

1. Fork 并克隆仓库
2. 安装依赖：go mod tidy
3. 构建二进制文件：npm run build
4. 在本地测试：node bin/index.js stdio
5. 进行更改并测试
6. 提交拉取请求

---

📜 许可证

MIT 许可证

版权所有 (c) 2025 idletoaster

特此免费授予任何获得本软件及相关文档文件副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和／或销售本软件副本的权利，以及允许获得本软件的人这样做，但须遵守以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或实质性部分中。

本软件按“原样”提供，不附带任何明示或默示的保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权所有者均不对任何索赔、损害或其他责任负责，无论该责任源于合同、侵权行为或其他原因，也无论其是否与本软件或本软件的使用或其他交易有关。