github-mcp-server

一个极简、只读的 MCP 服务器，通过 stdio 将你的 GitHub 仓库暴露给 Claude Code（或任何兼容 MCP 的客户端）。

它暴露的工具

• list_repos(owner?, include_forks?, limit?) - 列出你的仓库（或其他所有者的公开仓库）

• get_repo_info(owner, repo) - 单个仓库的元数据

• list_directory(owner, repo, path?, ref?) - 浏览仓库的文件树

• read_file(owner, repo, path, ref?, max_bytes?) - 读取文本文件的内容

• get_readme(owner, repo, ref?) - 获取仓库的 README

• search_code(query, owner?, repo?, limit?) - 搜索代码（可选地限定在你的仓库范围内）

• list_commits(owner, repo, path?, limit?) - 最近的提交历史

一切都是只读的——不暴露任何写入、创建或删除端点。

Related MCP server: GitHub MCP Server

设置

1. 创建 GitHub Personal Access Token（推荐使用细粒度令牌）： GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token。

   • Repository access：选择你希望 Claude 读取的仓库（或“All repositories”）

   • Permissions：Contents: Read-only、Metadata: Read-only（如果你希望 search_code 生效，请添加 Code search: Read-only）

2. 安装依赖：

   cd github-mcp-server
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. 设置令牌（不要将其硬编码在脚本中或提交到任何地方）：

   export GITHUB_TOKEN=github_pat_xxxxxxxxxxxx

   如需持久化，请将该行添加到你的 ~/.zshrc / ~/.bashrc，或使用 direnv 之类的工具配合 .env 文件——只需确保它被 gitignore 即可。

4. 向 Claude Code CLI 注册服务器：

   claude mcp add github-repos -- python3 /absolute/path/to/github-mcp-server/server.py

   （如果你使用了 venv，请指向 venv 的 python：/absolute/path/to/github-mcp-server/.venv/bin/python3）

   由于服务器会从其环境中读取 GITHUB_TOKEN，你可以在运行 claude 的 shell 中导出它，或显式传入：

   claude mcp add github-repos --env GITHUB_TOKEN=github_pat_xxxxxxxxxxxx -- python3 /absolute/path/to/github-mcp-server/server.py

5. 验证它已连接：

   claude mcp list

   你应该会看到 github-repos 显示为已连接。然后在 Claude Code 会话中，你可以提出诸如“列出我的仓库”或“读取我的 flight-delay-prediction 仓库的 README”之类的请求，Claude 会调用这些工具。

本地冒烟测试（无需客户端）

python3 -c "
import os
os.environ['GITHUB_TOKEN'] = 'github_pat_xxx'
from server import list_repos
print(list_repos())
"

备注 / 后续步骤

• 速率限制：经过身份验证的请求可从 GitHub 的 REST API 获得每小时 5,000 次的配额，足以满足交互式使用。

• 如果你之后需要写入权限（打开 issue、评论 PR），请使用 requests.post/patch 添加新的 @mcp.tool() 函数——将它们分开并清晰命名，以便始终明确哪些工具会修改 GitHub 状态。

• 如果你希望它能从 claude.ai/Cowork 访问（而不仅仅是 Claude Code CLI/VS Code），则需要从 stdio 传输迁移到带 OAuth 的托管 HTTP 服务器——这是一个实质性的更大步骤，只有在你需要这种可达性时才值得。