MCP Go Gh

mcp go gh

一个轻量级、全面的基于Go的MCP（模型上下文协议）服务器，封装了GitHub CLI(gh)，显示工具中可用的每个参数和选项。

特性

• 全覆盖：152个MCP工具，涵盖27个 gh 命令组- 100%稳定的gh CLI命令
• 类型安全：使用自动JSON模式生成Go结构
• 代码已生成：YAML定义驱动自动生成Go代码
• 可维护的：易于更新 gh CLI不断发展
• 轻量级：单个二进制文件，没有外部依赖关系（除 gh CLI）

支持的命令

服务器暴露 100%稳定的gh CLI命令 27个指挥组：

核心命令

• 项目 （19） ：GitHub Projects v2-完整的CRUD、字段和项目
• 公关 （14） ：拉取请求管理
• 问题 （14） ：问题跟踪和管理
• 代码空间 （13） ：代码空间创建和管理
• 仓库 （11） ：存储库操作
• 扩展 （8） ：扩展安装和管理
• 发布 （7） ：发布管理
• 跑 （7） ：工作流运行管理
• 认证 （6） ：身份验证和设置
• 要点 （6） ：Gist管理

操作和工作流命令

• 工作流 （5） ：GitHub操作工作流管理
• 变量 （4） ：动作变量
• 秘密 （3） ：秘密管理
• 缓存 （2） ：操作缓存操作

附加命令

• 标签 （5） ：标签管理
• 别名 （4） ：命令快捷方式
• 配置 （4） ：配置管理
• 证明 （3） ：文物证明
• gpg密钥 （3） ：GPG密钥管理
• 规则集 （3） ：存储库规则集
• 搜索 （3） ：搜索存储库、问题和PR
• ssh密钥 （3） ：SSH密钥管理
• 缓存 （2） ：操作缓存管理
• 应用程序接口 （1） ：原始GitHub API访问
• 浏览 （1） ：在浏览器中打开资源
• 完成 （1） ：壳体完工
• 组织 （1） ：组织运作
• 状态 （1） ：状态概述

总计：152个MCP工具=100%稳定的命令覆盖率 ✅

先决条件

• 转到1.25.6或更高版本
• GitHub命令行界面(gh) 已安装并验证

- 安装： brew install gh （macOS）或查看 官方文件 - 身份验证： gh auth login

• （可选） golangci lint v2开发版- 安装指南

安装

来源

# Clone the repository
git clone https://github.com/khalideidoo/mcp-go-gh.git
cd mcp-go-gh

# Build the server
make build

# Or install to GOPATH/bin
make install

使用Go安装

go install github.com/khalideidoo/mcp-go-gh/cmd/mcp-go-gh@latest

用法

使用克劳德桌面

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "gh": {
      "command": "/path/to/mcp-go-gh"
    }
  }
}

与其他MCP客户端

服务器使用stdio传输并遵循MCP协议规范。配置您的客户端以启动 mcp-go-gh 二元的。

环境变量

服务器尊重所有 gh CLI环境变量：

• GH_TOKEN / GITHUB_TOKEN：身份验证令牌
• GH_HOST：GitHub主机名（适用于企业）
• GH_REPO：默认存储库
• GH_EDITOR：文本编辑器首选项
• 更多（参见 gh 文件）

示例工具

创建拉取请求

{
  "name": "gh_pr_create",
  "arguments": {
    "title": "Fix bug in authentication",
    "body": "This PR fixes the authentication bug",
    "base": "main",
    "draft": false,
    "assignee": ["@me"]
  }
}

列出问题

{
  "name": "gh_issue_list",
  "arguments": {
    "state": "open",
    "label": ["bug", "priority"],
    "limit": 10,
    "json": ["number", "title", "author"]
  }
}

搜索存储库

{
  "name": "gh_search_repos",
  "arguments": {
    "query": "language:go stars:>1000",
    "limit": 20
  }
}

GitHub API访问

{
  "name": "gh_api_request",
  "arguments": {
    "endpoint": "repos/{owner}/{repo}/issues",
    "method": "GET",
    "jq": ".[] | {number, title}"
  }
}

发展

项目结构

mcp-go-gh/
├── cmd/
│   └── mcp-go-gh/          # Server entry point
├── internal/
│   ├── commands/
│   │   ├── definitions/    # YAML command definitions (27 files)
│   │   └── generated/      # Generated Go code (152 tools)
│   ├── executor/           # gh CLI executor
│   └── server/             # MCP server logic
├── tools/
│   └── gen/                # Code generator
├── .golangci.yml           # golangci-lint v2 configuration
├── Makefile                # Build automation
└── README.md

添加新命令

1. 在中创建或更新YAML定义 internal/commands/definitions/
2. 跑 make generate 生成Go代码
3. 构建： make build

YAML定义示例：

command: example
description: Example command
subcommands:
  - name: create
    description: Create something
    parameters:
      - name: title
        type: string
        flag: --title
        short: -t
        description: Title for the item
      - name: draft
        type: boolean
        flag: --draft
        description: Create as draft

建筑

# Generate code and build (default)
make

# Just generate code
make generate

# Just build
make build

# Build for all platforms
make build-all

# Clean build artifacts
make clean

# Install to GOPATH/bin
make install

代码质量

此项目使用 golangci lint v2 对于全面的代码质量检查：

# Run all linters
make lint

# Auto-fix issues (formatting, imports, etc.)
make lint-fix

# Format code
make fmt

# Or use golangci-lint v2 formatter directly
golangci-lint fmt

Linters已启用：25+，包括errcheck、gover、staticcheck、gosec、revenue等。看 .golangci.yml 用于完整配置。

运行测试

# Run all tests
make test

# Run tests with coverage
go test -v -coverprofile=coverage.out ./...

# View coverage report
go tool cover -html=coverage.out

可用生成目标

建筑

代码生成

该项目使用YAML驱动的代码生成方法：

1. YAML定义：中定义的命令结构 internal/commands/definitions/*.yaml
2. 代码生成器: tools/gen/ 读取YAML并生成Go代码
3. 生成的代码：中的类型安全结构和注册函数 internal/commands/generated/

这种方法确保：

• 所有命令的一致性
• 易于维护和更新
• 全面的参数覆盖
• 自动生成JSON模式

执行者

这 internal/executor 包裹把手 gh CLI执行：

• 查找 gh PATH中的二进制
• 执行具有适当超时处理的命令
• 捕获stdout/stderr
• 将所有操作记录到stderr（stdout保留用于MCP协议）

最低要求

• gh命令行界面：2.30.0或更高版本
• 走1.25.6或更高版本（用于开发）
• 操作系统：macOS、Linux或Windows
• 戈朗茨皮棉：v2.8.0或更高版本（可选，用于开发）

故障排除

gh未找到CLI

确保 gh 在您的路径中：

which gh
# Should output: /usr/local/bin/gh or similar

身份验证问题

检查 gh 身份验证状态：

gh auth status

如果未通过身份验证：

gh auth login

调试

服务器记录到stderr。启用调试日志记录：

# Run directly to see logs
./bin/mcp-go-gh

# Or check your MCP client's logs

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 为新命令添加/更新YAML定义
4. 跑 make generate 生成Go代码
5. 跑 make lint 确保代码质量
6. 跑 make test 验证测试是否通过
7. 跑 make build 验证它是否编译
8. 提交拉取请求

开发工作流程

# 1. Make changes to YAML definitions
vim internal/commands/definitions/example.yaml

# 2. Generate code
make generate

# 3. Run quality checks
make lint-fix  # Auto-fix issues
make lint      # Verify all checks pass

# 4. Run tests
make test

# 5. Build
make build

许可证

MIT许可证-请参阅 许可证 详细信息文件

致谢

• 与 MCP Go SDK
• 包裹
• 受模型上下文协议规范的启发

链接

• 模型上下文协议
• MCP Go SDK