ghcli-mcp-connector

---

这是一个静态 Go 二进制文件，支持 Model Context Protocol， 让 Agent 能够运行 GitHub CLI 命令：任何 gh <command> <subcommand> 调用——repo、issue、pr、release、gist、workflow、run、 secret、variable、project、ruleset、codespace、extension、api 等——对于任何会更改 GitHub 状态的操作，默认都会启用只读安全保护。

无需 Python、无需 uv，也无需安装运行时依赖——只需一个二进制文件和 一个 .mcp.json。它会调用主机上已安装并完成身份验证的 gh 二进制文件 （通过 gh auth login 登录，凭据保存在操作系统钥匙串中，或使用 GH_TOKEN/GITHUB_TOKEN），而不是重新实现 GitHub API 客户端， 因此无需手动挑选 API 端点，即可直接获得 CLI 的全部功能。

**注意：**这是 github-mcp-connector 的姊妹项目，并非替代品。后者通过 google/go-github 直接调用 GitHub REST API， 并提供一组精心挑选的 18 个工具。此项目则直接调用 gh CLI——这与 aws-mcp-connector 和手写 AWS SDK 客户端的取舍相同：通过单个 ghcli_exec 逃生通道获得更广泛的覆盖范围（包括 gh 扩展、gh 自带的筛选和格式化功能，以及工作流、运行、代码空间、项目和规则集管理），而不是提供一组精选功能。

✨ 为什么要做这个项目

如果 Agent 只能使用一组范围狭窄、经过手动挑选的 GitHub 工具，那么一旦需要执行 集合之外的操作，就会碰壁。此连接器直接封装 gh CLI，让 Agent 可以运行 gh pr list、gh issue create、gh workflow run、gh api repos/owner/repo/issues—— 凡是 CLI 能做的事情都能执行，无需等待有人为此编写新工具。默认会阻止会更改状态的命令， 必须同时启用服务级别的选项并在每次调用时设置 confirm=true，因此开箱即可安全地探索和读取。

🧰 工具

工具	功能	写入？
ghcli_exec	运行任意 gh <command> <subcommand> ... 命令。默认只读——要运行会更改 GitHub 状态的命令，必须在服务端设置 GHCLI_MCP_ALLOW_WRITE=true，并在调用时设置 confirm=true。	✅（受控）
ghcli_help	显示 gh <command> [subcommand] --help 文本——始终安全，可用它在调用 ghcli_exec 前确认准确语法。
ghcli_whoami	显示配置的身份验证所对应的 GitHub 身份（登录名、姓名、个人资料 URL）。

每个工具都接受可选的 response_format：markdown（默认，适合聊天界面阅读）或 json（用于程序化处理）。

此服务没有可用的工作目录 Git 仓库，因此，仓库范围的命令需要明确指定 -R/--repo owner/repo，不能依赖 gh 基于当前工作目录检测仓库。

🚀 快速开始

最快方式： 从最新发布版本获取预构建包—— 下载 ghcli-mcp-connector-plugin-<version>-<os>-<arch>.zip，解压后， 将 Cowork/Claude 指向其中的 plugin/ 文件夹（参见 SETUP.md 的步骤 4）。无需 Go 工具链。

从源码构建：

# 1. Build
cd go-server
go mod tidy
go build -o ghcli-connector-server .
cp ghcli-connector-server ../plugin/servers/go/

# 2. Set up auth — needs the gh CLI itself installed and logged in
#    (gh auth login) — see SETUP.md
gh auth status   # should succeed before running the server

# 3. Run
./go-server/ghcli-connector-server   # serves MCP over stdio

或者运行 make build——所有快捷命令（test、vet、fmt、lint、tidy）请参阅 Makefile。

完整操作指南——包括如何将其配置为 Claude/Cowork 插件——请参阅 SETUP.md。

🔐 配置

所有配置均通过插件的 .mcp.json 传入环境变量：

变量	用途	默认值
GH_TOKEN / GITHUB_TOKEN	gh CLI 自身使用的令牌环境变量。留空即可使用 gh auth login 已配置的身份验证方式。	未设置（使用密钥链身份验证）
GH_HOST	指定 GitHub Enterprise 主机名，而非 github.com。	未设置（github.com）
GHCLI_MCP_ALLOW_WRITE	设置为 "true" 才允许运行会更改状态的命令（每次调用仍需设置 confirm=true）。	false（只读）
GHCLI_MCP_ALLOWED_REPOS	以逗号分隔的 owner/repo 值允许列表，例如 "me/proj,me/other"。仅当调用显式传入 -R/--repo 标志时才会生效。	未设置（不受限制）
GHCLI_MCP_CLI_PATH	gh 二进制文件的路径。	通过 PATH 解析 gh

🧪 质量标准

这不是一个玩具脚本——它具备生产级 Go 服务应有的同等检查：

• ✅ 对每条输入验证路径进行单元测试（go test ./...）
• ✅ go vet + gofmt 检查通过
• ✅ golangci-lint（govet、staticcheck、errcheck、gosec 等）
• ✅ govulncheck——依赖关系图中没有已知漏洞
• ✅ 每次推送时进行 CodeQL 静态安全分析
• ✅ 开发期间针对真实 GitHub 完成端到端验证——不使用模拟对象
• ✅ Dependabot 持续更新 Go 模块和 Actions

所有检查都会在每次推送和 PR 时通过 CI 运行。

🏷️ 发布与版本管理

版本遵循 semver，并根据 main 上的 Conventional Commits 提交信息，由 release-please 自动生成：

• fix: ... → 补丁版本（v0.1.0 → v0.1.1）
• feat: ... → 次版本（v0.1.1 → v0.2.0）
• feat!: ... / BREAKING CHANGE: 页脚 → 主版本（v0.2.0 → v1.0.0）

每个合并的 PR 都会更新一个长期存在的 "chore(main): release vX.Y.Z" PR， 并附带自动生成的 CHANGELOG.md。合并该 PR 会：

1. 为发布版本打标签，并在 GitHub 上发布
2. 构建并附上可直接安装的压缩插件包，适用于 linux/darwin/windows × amd64/arm64
3. 根据这些确切的资源重新生成 server.json（更新版本 + SHA-256 哈希），并通过 mcp-publisher 发布到 官方 MCP Registry，使用 GitHub OIDC 进行身份验证——无需存储密钥

请参阅 .github/workflows/release-please.yml 和 .github/workflows/publish-mcp-registry.yml （也可通过 workflow_dispatch 手动运行，以发布现有标签）。

📁 目录结构

ghcli-mcp-connector/
├── README.md                  ← you are here
├── SETUP.md                   ← step-by-step setup guide
├── CONTRIBUTING.md             ← how to contribute
├── CODE_OF_CONDUCT.md
├── SECURITY.md                 ← vulnerability reporting
├── CODEOWNERS
├── LICENSE                     ← MIT
├── Makefile                    ← build / test / lint shortcuts
├── .golangci.yml                ← lint rules
├── release-please-config.json  ← semver/changelog automation config
├── .release-please-manifest.json
├── server.json                  ← MCP Registry manifest (regenerated fresh per release by CI)
├── scripts/
│   └── render-server-json.sh    ← rebuilds server.json from a release's zip assets
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                     ← build, vet, test, lint, govulncheck
│   │   ├── codeql.yml                 ← security scanning
│   │   ├── pr-title.yml               ← Conventional Commits PR title check
│   │   ├── release-please.yml         ← version PRs, tagging, GitHub releases
│   │   ├── publish-mcp-registry.yml   ← publishes server.json to the MCP Registry
│   │   └── rebuild-release-assets.yml ← manual re-attach fallback
│   ├── ISSUE_TEMPLATE/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml
├── go-server/                  ← the MCP server source
│   ├── main.go
│   ├── main_test.go
│   ├── go.mod / go.sum
│   └── README.md
└── plugin/                     ← installable Cowork/Claude plugin
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                ← holds credentials locally — never commit real ones
    ├── skills/ghcli-mcp/SKILL.md ← teaches Claude when/how to use the tools
    └── servers/go/              ← compiled binary goes here

🤝 贡献

欢迎提交 PR 和问题——完整指南（环境设置、编码规范、如何添加新工具）请参阅 CONTRIBUTING.md， 以及 行为准则。

main 分支受保护：所有更改（包括维护者的更改）都必须通过 PR 合并，且 CI 检查必须通过。PR 标题必须遵循 Conventional Commits 规范——版本自动管理由此驱动。

发现安全问题？请按照 SECURITY.md 中的说明处理，不要公开提交问题。

📄 许可证

MIT © FerhatDundar