GitHub MCP服务器
用于GitHub操作的模型上下文协议（MCP）服务器，使LLM能够通过标准化的接口与GitHub存储库进行交互。可部署到Cloudflare Workers以供生产使用。
特性
- 🔌 符合MCP协议：适用于任何兼容MCP的LLM（OpenAI、Claude、Cursor等）
- 🚀 9 GitHub运营：全面的公关管理能力
- ✅ 类型安全：使用Zod进行运行时验证的完整TypeScript
- ☁️ Cloudflare员工就绪：无需配置即可部署到边缘
- 🧪 已测试：模式和行为验证的黄金测试
- 🔐 安全：GitHub个人访问令牌身份验证
可用工具
- list_prs -列出带过滤器的拉取请求（状态、基、头）
- get_pr -获取详细的公关信息
- create_pr -创建新的pull请求
- update_pr -更新PR标题、描述、状态或基本分支
- add_pr_注释 -向PR添加评论
- merge_r -使用指定方法合并PR（合并/挤压/重基）
- request_pr_viewers -请求PR审阅者（用户或团队）
- add_pr_labels -向PR添加标签
- 移除_pr_标签 -从PR中删除标签
建筑
┌─────────────┐
│ LLM │ (OpenAI, Claude, Cursor, etc.)
│ (Client) │
└──────┬──────┘
│ MCP Protocol
│ (stdio or HTTP)
▼
┌─────────────────┐
│ MCP Server │
│ (This repo) │
├─────────────────┤
│ • Tool Registry │
│ • Validation │
│ • Error Handler │
└──────┬──────────┘
│
│ Octokit REST API
▼
┌─────────────────┐
│ GitHub API │
└─────────────────┘设置
先决条件
- Node.js 18+
- 具有适当权限的GitHub个人访问令牌
安装
# Clone or create project
npm install
# Set GitHub token
export GITHUB_TOKEN="ghp_your_token_here"
# Build project
npm run build创建GitHub令牌
- 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
- 生成具有以下作用域的新令牌：
- repo （完全控制私有存储库） - read:org （如果与组织repo合作）
- 复制令牌并设置为
GITHUB_TOKEN环境变量
用法
地方发展（stdio）
使用stdio传输在本地运行MCP服务器：
export GITHUB_TOKEN="your_token"
npm run dev服务器将在stdio上运行，可以通过MCP客户端连接。
测试客户端
运行示例测试客户端以查看服务器的运行情况：
export GITHUB_TOKEN="your_token"
npm run client这将：
- 启动MCP服务器
- 通过stdio传输连接
- 列出可用工具
- 执行示例操作（列出PR，获取PR详细信息）
- 显示结果
与Cursor集成
要与Cursor一起使用，请在MCP配置中添加：
{
"mcpServers": {
"github": {
"command": "node",
"args": ["path/to/mcp-deployable/dist/server/index.js"],
"env": {
"GITHUB_TOKEN": "your_token_here"
}
}
}
}与OpenAI集成
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';
import OpenAI from 'openai';
// Start MCP server
const serverProcess = spawn('node', ['dist/server/index.js'], {
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
});
// Connect MCP client
const client = new Client({
name: 'openai-github-client',
version: '1.0.0',
}, { capabilities: {} });
const transport = new StdioClientTransport({ command: serverProcess });
await client.connect(transport);
// Get available tools
const tools = await client.listTools();
// Use with OpenAI
const openai = new OpenAI();
const response = await openai.chat.completions.create({
model: 'gpt-4',
messages: [
{ role: 'user', content: 'List open PRs in owner/repo' }
],
tools: tools.tools.map(tool => ({
type: 'function',
function: {
name: tool.name,
description: tool.description,
parameters: tool.inputSchema,
},
})),
});
// Execute tool if requested
if (response.choices[0].message.tool_calls) {
const toolCall = response.choices[0].message.tool_calls[0];
const result = await client.callTool({
name: toolCall.function.name,
arguments: JSON.parse(toolCall.function.arguments),
});
console.log(result);
}Cloudflare员工部署
先决条件
- Cloudflare帐户
- Wrangler CLI已安装(
npm install -g wrangler)
部署
# Build worker bundle
npm run build:worker
# Set GitHub token as secret
wrangler secret put GITHUB_TOKEN
# Deploy to Cloudflare Workers
npm run deployHTTP API
部署后，worker将公开这些端点：
健康检查
curl https://your-worker.workers.dev/health列出工具
curl https://your-worker.workers.dev/tools调用工具
curl -X POST https://your-worker.workers.dev/invoke \
-H "Content-Type: application/json" \
-d '{
"tool": "list_prs",
"arguments": {
"owner": "octocat",
"repo": "hello-world",
"state": "open"
}
}'发展
项目结构
mcp-deployable/
├── src/
│ ├── server/
│ │ ├── index.ts # MCP server (stdio)
│ │ ├── tools/
│ │ │ └── github-tools.ts # GitHub API operations
│ │ └── schemas/
│ │ └── tools.ts # Zod schemas
│ ├── client/
│ │ └── test-client.ts # Example client
│ ├── types/
│ │ └── github.ts # TypeScript types
│ └── worker.ts # Cloudflare Workers entry
├── tests/
│ └── golden/
│ ├── github-tools.test.ts # Golden tests
│ └── fixtures/ # Mock responses
├── wrangler.toml # Workers config
├── package.json
└── tsconfig.json运行测试
# Run all tests
npm test
# Run golden tests only
npm run test:golden
# Run tests in watch mode
npm test -- --watch脚本
npm run build-构建TypeScript和worker包npm run dev-在本地运行MCP服务器（stdio）npm run client-运行测试客户端npm test-运行测试套件npm run deploy-部署到Cloudflare Workers
工具示例
列出拉取请求
{
"tool": "list_prs",
"arguments": {
"owner": "modelcontextprotocol",
"repo": "typescript-sdk",
"state": "open",
"per_page": 10
}
}获取拉取请求详细信息
{
"tool": "get_pr",
"arguments": {
"owner": "modelcontextprotocol",
"repo": "typescript-sdk",
"pull_number": 42
}
}创建拉取请求
{
"tool": "create_pr",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"title": "Add new feature",
"body": "This PR adds feature X",
"head": "feature-branch",
"base": "main",
"draft": false
}
}更新拉取请求
{
"tool": "update_pr",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"pull_number": 42,
"title": "Updated title",
"body": "Updated description"
}
}添加评论
{
"tool": "add_pr_comment",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"pull_number": 42,
"body": "Great work! LGTM 👍"
}
}合并拉取请求
{
"tool": "merge_pr",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"pull_number": 42,
"merge_method": "squash",
"commit_title": "feat: add new feature"
}
}请求审阅者
{
"tool": "request_pr_reviewers",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"pull_number": 42,
"reviewers": ["user1", "user2"],
"team_reviewers": ["team-alpha"]
}
}管理标签
{
"tool": "add_pr_labels",
"arguments": {
"owner": "myorg",
"repo": "myrepo",
"pull_number": 42,
"labels": ["bug", "high-priority"]
}
}错误处理
所有工具都包括全面的错误处理：
- 验证错误：使用Zod模式验证输入参数
- GitHub API错误：捕获并格式化来自GitHub API的HTTP错误
- 速率限制：GitHub API速率限制错误正确浮出水面
- 身份验证错误：缺少或无效的令牌返回明确的错误消息
错误响应示例：
{
"error": "GitHub API error (404): Not Found",
"code": "INTERNAL_ERROR"
}安全
- 认证：使用GitHub个人访问令牌（PAT）
- 最小权限：仅配置具有必要作用域的令牌
- 环境变量：秘密存储在env变量中，从未提交
- 输入验证：在GitHub API调用之前验证的所有输入
许可证
麻省理工学院
贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
支持
对于问题或疑问：
- 在GitHub上打开一个问题
- 检查现有问题的解决方案
- 审查MCP协议文件：https://modelcontextprotocol.io