slim-github-mcp

一个只读的 GitHub MCP 服务器，返回精简的结果。

大多数 GitHub MCP 服务器会把 GitHub API 的原始对像直接交给模型。对于跑在快速 API 后面的前沿模型来说这没问题，但对本地模型来说是灾难：单页仓库搜索结果就有约 14 KB 的 JSON（约 3.5k tokens），其中大部分是没人会读的 URL 和权限标志。再加上约 7k tokens 的工具 schema，本地托管的模型可能要花几分钟来“列出我的仓库”——甚至永远做不完。

这个服务器反其道而行之。每个工具只返回少量有用字段，所有列表都在服务端限制数量，整个工具面只有九个函数。无论模型编造什么参数，都无法拉取到庞大的数据量。

工具

每个 limit 默认是 10，并被限制在 30 以内。gh_file 在 20k 个字符处截断，并通过 truncated 标志说明这一点。仓库返回时仅包含 full_name、private、160 个字符的 description、language、stars、updated、url——没有其他内容。

这里刻意不做任何写入路径：客户端永远只向 api.github.com 发出 GET 请求。

Related MCP server: GitHub MCP Server

获取 GitHub token

该服务器只需要一个 token，所有调用都会使用它。仅需读取权限。

1. 打开 GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token。

2. 设置有效期，并选择该 token 可以访问哪些仓库——如果你永远不希望私有数据离开 GitHub，请选择 Public repositories only；如果你希望 gh_my_repos(visibility="private") 能正常工作，请选择 All repositories。

3. 在 Repository permissions 下，为你实际需要的内容授予只读权限：

   • Metadata：Read-only —— 必选，并且对搜索和仓库列表已经足够

   • Contents：Read-only —— 用于 gh_file 和 gh_commits

   • Issues：Read-only —— 用于 gh_issues

   • Pull requests：Read-only —— 用于 gh_pulls

4. 保持所有 Account permissions 不变。

5. 复制你提交的 token—— GitHub 只会显示一次。

带 repo 范围的经典 token 也可以，但它的权限比这个服务器需要的宽的多，建议优先使用 fine-grained token。

未经认证的 GitHub API 调用限制为 60 次/小时，因此实际上 token 是不可选的。使用 token 后，每小时可以请求 5,000 次。

安装

git clone https://github.com/0xBakeer/slim-github-mcp.git
cd slim-github-mcp

python3 -m venv venv
./venv/bin/pip install -r requirements.txt

cp .env.example .env
$EDITOR .env            # put your token in GITHUB_MCP_TOKEN

运行它：

set -a; . ./.env; set +a
./venv/bin/uvicorn slim_github_mcp.main:app --host 127.0.0.1 --port "${GITHUB_MCP_PORT:-9130}"

检查它启动成功，并且 token 能正常工作：

curl -s http://127.0.0.1:9130/api/health
curl -s -H "Authorization: Bearer $GITHUB_MCP_SECRET" \
     'http://127.0.0.1:9130/api/my-repos?visibility=public&limit=5'

MCP 端点本身是：

http://127.0.0.1:9130/tools/mcp/v1

它支持 streamable HTTP，所以任何接受 URL 的 MCP 客户端都可以直接使用。

配置

如果端口能被非 localhost 的任意主机访问了，请设置 GITHUB_MCP_SECRET。 服务器持有你的 token，该 token 可能具有读取私有仓库的权限，并且该服务器不会以其他方式对调用者进行认证。用 openssl rand -hex 24 生成一个密钥。

GITHUB_MCP_PUBLIC_HOST 的存在是因为 MCP 默认启用了 DNS 重绑定保护：来自反向代理的请求会带有公开的 Host 请求头，除非声明了下述主机名，否则请求会被拒。如果不设置它，会发现 MCP 端点返回 400，而 /api/health 却正常响应。

以服务方式运行

scripts/github-mcp.service 是一个需要替换适配的 systemd 单元——设置 User、路径，并将 EnvironmentFile 指向一个 root 拥有且权限为 0600 的文件，该文件用来存放上述变量。不要把 token 直接写在单元文件里。

此外还有一个 Dockerfile：

docker build -t slim-github-mcp .
docker run -d --name github-mcp -p 127.0.0.1:9130:9130 --env-file .env slim-github-mcp

反向代理之后

没有什么特殊的，但 MCP 是流式的，所以必须关闭：

location /tools/mcp/ {
    proxy_pass http://127.0.0.1:9130;
    proxy_set_header Host $host;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
}

将 GITHUB_MCP_PUBLIC_HOST 设置为你的反向代理使用的主机名。

在 Open WebUI 中使用

Open WebUI 原生支持 MCP（0.6.x 及更高版本）。通过辅助脚本注册服务器：

export OPEN_WEBUI_URL=https://webui.example.com
export OPEN_WEBUI_KEY=sk-...                      # Settings -> Account -> API keys
export GITHUB_MCP_URL=http://127.0.0.1:9130/tools/mcp/v1
export GITHUB_MCP_SECRET=...                      # if you set one

./scripts/register-open-webui.sh

它会将该条目合并到 Open WebUI 现有的工具服务器中（按 id 匹配，重复运行只会更新），随后打印发现的工具：

==> Verifying tool discovery
    9 tools: gh_whoami, gh_my_repos, gh_user_repos, ...

手动操作：进入 Admin Settings → Tools → Add Tool Server，类型选择 MCP，URL 按上面写，认证 Bearer 并填写你的 secret。

两个容易遗漏的地方：

• 在聊天的工具选择器中启用该工具。 注册过的服务器不会自动提供给模型。

• 如果你按模型固定工具（Workspace → Models → Tools），也要在这里添加它。Open WebUI 会将其存储为 server:mcp:<id>。以后重命名服务器 id 时，被固定的引用会被固定引用消失——模型仍然会继续回答，但通常只能靠猜测，没有这些工具。

值得知道的是：用 tool_ids 直接通过调用 /api/chat/completions 来不会挂载工具服务器。工具连接是在前端完成的，所以要通过 UI 测试。

许可证

MIT