在 Google Gemini CLI 中安装 GitHub MCP Server四种接入方式的完整配置指南【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server本篇指南以 GitHub 官方 MCP Server 仓库中的 docs/installation-guides/install-gemini-cli.md 为核心系统讲解如何在 Google Gemini CLI 中配置 GitHub MCP Server覆盖 Gemini 扩展、远程服务、本地 Docker 与原生二进制四种接入方式并深入 OAuth/PAT 两种认证模型与排错要点。读完本文你将掌握 Gemini CLI 的 MCP 配置语法settings.json中的mcpServers结构、如何安全存放 Personal Access TokenPAT、如何用/mcp list验证连通性并理解每种方式的适用场景与底层原理。前置条件在开始之前请确保满足以下条件已安装 Google Gemini CLIgemini命令可用。拥有一个具备合适权限范围的 GitHub Personal Access TokenPAT。若选择本地 Docker 方式需要安装并启动 Docker本地安装可选远程方式不需要。关于 Gemini CLI 在 GitHub MCP Server 各宿主应用中的支持情况可参考 docs/installation-guides/README.md 中的支持矩阵Gemini CLI 支持本地 GitHub MCPLocal与远程 GitHub MCPRemote其中远程方式仅支持 PAT 认证OAuth 暂不支持整体难度评级为 Easy。安全存放你的 PAT为了安全不要将 token 硬编码进配置。在~/.gemini/.env~是你的主目录或项目目录中创建或更新 PAT# ~/.gemini/.env GITHUB_MCP_PATyour_token_here这一做法的核心动机是配置文件如settings.json通常会被纳入版本控制或与他人共享而.env文件则适合加入.gitignore与访问权限控制。仓库 README 的 Handling PATs Securely 一节见 README.md同样推荐先通过环境变量或.env存放 token再在 MCP 配置中以变量引用的方式使用并强调最小权限原则、定期轮换、绝不提交到版本库。GitHub MCP Server 的 Gemini CLI 配置基础Gemini CLI 的 MCP 服务器统一在 settings JSON 的mcpServers键下配置全局配置~/.gemini/settings.json~为主目录项目级配置项目目录下的.gemini/settings.json配置完成后可能需要重启 Gemini CLI才能生效。提示如需获取最新最全的配置选项请参见仓库根目录的 README.md。仓库中还存在 docs/server-configuration.md 这样一份完整的服务端配置指南里面覆盖了 Toolsets工具集、单工具、排除工具、只读模式、Lockdown 模式等所有配置维度的速查表可与本篇安装指南配合阅读。配置生效后的能力概况当 GitHub MCP Server 成功接入后Gemini CLI 会获得 GitHub 平台的完整工具面。以远程服务默认工具集为例实际暴露的工具数量会达到近百个量级涵盖仓库、Issue、Pull Request、Actions、代码扫描等域。完整的工具集清单可以在 README.md 的 Available Toolsets 表格中查到例如Toolset说明context当前用户与 GitHub 上下文相关工具强烈推荐reposGitHub 仓库相关工具issuesGitHub Issues 相关工具pull_requestsGitHub Pull Request 相关工具usersGitHub 用户相关工具actionsGitHub Actions 工作流与 CI/CD 操作当未显式指定工具集时服务端默认启用context、repos、issues、pull_requests、users这五个默认工具集见 README.md 与 docs/server-configuration.md 中的默认行为说明。接入方式一Gemini 扩展推荐最简便的方式是使用 GitHub 托管的 MCP Server远程服务通过官方 gemini 扩展一键接入gemini extensions install https://github.com/github/github-mcp-server注意使用扩展方式时你仍然需要在环境中提供名为GITHUB_MCP_PAT、具备合适权限范围的 Personal Access Token。该扩展的本质在仓库根目录的 gemini-extension.json 中有直接体现——它就是一份描述 MCP 服务器连接信息的清单文件{ name: github, version: 1.0.0, mcpServers: { github: { description: Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language., httpUrl: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer $GITHUB_MCP_PAT } } } }可以看到扩展指向的正是 GitHub 托管的远程 MCP 端点https://api.githubcopilot.com/mcp/并通过Authorization: Bearer $GITHUB_MCP_PAT请求头携带 token 完成认证——这正是方法一「零本地依赖」的原因服务端由 GitHub 托管Gemini CLI 只需持有 token 并建立 HTTP 连接。接入方式二远程服务Remote Server你也可以直接连接托管的 MCP Server。在安全存放 PAT 后按如下方式配置 Gemini CLI// ~/.gemini/settings.json { mcpServers: { github: { httpUrl: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer $GITHUB_MCP_PAT } } } }这一配置本质上就是方法一中 gemini 扩展清单的等价手写版。远程服务的完整能力与可选配置可参考 docs/remote-server.md远程端点支持通过 URL 路径如/readonly只读变体、/insiders内测变体或请求头X-MCP-Toolsets、X-MCP-Tools、X-MCP-Readonly、X-MCP-Lockdown、X-MCP-Insiders做精细化控制并且远程服务还额外提供copilot_spaces、github_support_docs_search等仅在远程端可用的工具集。接入方式三本地 Docker在 Docker 运行的前提下可以在容器中运行 GitHub MCP Server。使用 OAuth 登录推荐无需创建 token在 github.com 上官方镜像已经内置了应用凭据因此你无需提供任何凭据——服务器在首次使用时打开浏览器登录且 token 只保留在内存中。在 Docker 中需要将固定回调端口发布到 loopback 地址即本机回环地址// ~/.gemini/settings.json { mcpServers: { github: { command: docker, args: [ run, -i, --rm, -p, 127.0.0.1:8085:8085, -e, GITHUB_OAUTH_CALLBACK_PORT, ghcr.io/github/github-mcp-server ], env: { GITHUB_OAUTH_CALLBACK_PORT: 8085 } } } }关键点解读镜像ghcr.io/github/github-mcp-server是官方 Docker 镜像见 Dockerfile默认命令为stdio内部暴露端口 8082。固定回调端口 8085容器无法访问宿主机的随机 loopback 端口因此必须固定端口并将其发布进容器。使用 8085 是为了匹配官方应用注册的回调 URL。完整原理与注意事项见 docs/oauth-login.md 的 Running in Docker 一节。仅发布到 loopback-p 127.0.0.1:8085:8085而非-p 8085:8085。容器内回调必然监听所有接口若普通发布会将授权码暴露到你的网络。这也是一个刻意设计的安全点固定端口被占用时服务器会直接报错退出而不会静默降级到设备码流程。使用 PAT 认证优先于 OAuth也可以改用 Personal Access Token 认证它优先于 OAuth// ~/.gemini/settings.json { mcpServers: { github: { command: docker, args: [ run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, ghcr.io/github/github-mcp-server ], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_MCP_PAT } } } }注意这里的环境变量传递技巧-e GITHUB_PERSONAL_ACCESS_TOKEN不带值让 Docker 从宿主机环境继承该变量而env块中的$GITHUB_MCP_PAT则由 Gemini CLI 展开。这与 README.md 中推荐的 PAT 处理方式一致。OAuth 与 PAT 的优先级规则从源码看静态 token 的优先级是写死的在 cmd/github-mcp-server/main.go 的stdio命令逻辑中只有当token 且未配置 GitHub App 认证时才会进入 OAuth 流程oauth.NewManager(...)。也就是说一旦设置了GITHUB_PERSONAL_ACCESS_TOKEN服务器直接使用它并完全跳过 OAuth。同样地GitHub App 认证--app-id等与 PAT、与 OAuth 互为互斥同时设置会直接报错退出。接入方式四原生二进制你可以从 GitHub Releases 页面下载最新的二进制发布包也可以从源码构建go build -o github-mcp-server ./cmd/github-mcp-server然后将/path/to/binary替换为二进制实际路径按如下方式配置 Gemini CLI// ~/.gemini/settings.json { mcpServers: { github: { command: /path/to/binary, args: [stdio], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_MCP_PAT } } } }如需改用 OAuth 登录无需创建或存放 token则省略GITHUB_PERSONAL_ACCESS_TOKEN——原生二进制会使用随机 loopback 回调端口因此无需任何额外配置。详见 docs/oauth-login.md。关于原生二进制的 OAuth 行为有几点值得从源码层面理解官方发布的二进制与镜像通过构建期-ldflags注入了内置 OAuth 客户端见 Dockerfile 中的-X github.com/github/github-mcp-server/internal/buildinfo.OAuthClientID...。因此在 github.com 上运行时你可以零配置启动服务器不需要 token也不需要 client ID。在 cmd/github-mcp-server/main.go 中只有未显式提供--oauth-client-id、未请求 GitHub App 认证、且 host 归一化后为https://github.com时才会回落到内置客户端。若目标 host 是 GitHub Enterprise Server 或ghe.com则必须自带 OAuth 应用并通过--oauth-client-id指定。若三者PAT、GitHub App、OAuth client均未配置服务器会直接以错误退出authentication required: set GITHUB_PERSONAL_ACCESS_TOKEN, configure GitHub App auth, or pass --oauth-client-id to log in via OAuth。OAuth 流程简要原理本地stdio服务器的 OAuth 登录流程详见 docs/oauth-login.md采用authorization code flow with PKCE服务器在本机启动 loopback 回调打开 GitHub 授权页用 PKCE verifier 与 client secret 兑换 token。由于这是公开的分布式客户端内置于二进制中的 secret 并非真正机密——PKCE 才是安全关键它把授权码绑定到本次登录尝试上防止被截获的 code 在其他地方兑换。token 只保留在内存中不落盘GitHub App 的 token 过期后还会通过 refresh token 透明刷新长时间会话无需重新授权。验证配置是否成功配置完成后在终端启动 Gemini CLI运行gemini然后检查 MCP 服务器状态/mcp list正常输出类似ℹConfigured MCP servers: github - Ready (96 tools, 2 prompts) Tools: - github__add_comment_to_pending_review - github__add_issue_comment - github__add_sub_issue ...状态表示服务器就绪工具数量会随所用工具集不同而变化。除了 ToolsGitHub MCP Server 还会注册 MCP Prompts工作流提示词源码可见于 pkg/github/prompts.go这也解释了输出中的 2 prompts。用提示词实测List my GitHub repositories若返回你的仓库列表说明认证与工具调用链路完全打通。进阶配置选项Gemini CLI 本身还支持更多 MCP 配置结构例如跳过工具确认或排除特定工具。这些能力与 GitHub MCP Server 的服务端配置正交你既可以在 Gemini CLI 侧裁剪工具可见性也可以利用仓库自身的配置维度工具集、单工具、排除工具、只读模式、Lockdown 模式等做服务端裁剪二者可组合使用。完整的服务端配置速查见 docs/server-configuration.md其中明确了各类配置在远程与本地两种形态下的对应方式例如配置维度本地 Server工具集Toolsets--toolsets标志或GITHUB_TOOLSETS环境变量单工具Tools--tools标志或GITHUB_TOOLS环境变量排除工具--exclude-tools标志或GITHUB_EXCLUDE_TOOLS环境变量只读模式--read-only标志或GITHUB_READ_ONLY环境变量以 Docker 方式为例通过环境变量启用只读模式与指定工具集的写法docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKENyour-token \ -e GITHUB_READ_ONLYtrue \ -e GITHUB_TOOLSETSrepos,issues,pull_requests,actions,code_security \ ghcr.io/github/github-mcp-server故障排查本地服务端问题Docker 报错确保 Docker Desktop 正在运行docker --version镜像拉取失败尝试先docker logout ghcr.io再重试。镜像ghcr.io/github/github-mcp-server是公开的出现拉取错误通常是本机存在已过期的 ghcr.io token 所致参见 README.md 前置条件说明。Docker 未找到安装 Docker Desktop 并确保其运行。认证问题PAT 无效确认你的 GitHub PAT 具备正确的权限范围repo— 仓库操作read:packages— Docker 镜像访问若使用 Dockertoken 过期重新生成一个新的 GitHub PAT并按文首方式更新~/.gemini/.env。配置问题JSON 无效验证你的配置cat ~/.gemini/settings.json | jq .jq会解析 JSON 并高亮语法错误若未安装 jq也可使用python -m json.tool ~/.gemini/settings.json做等价校验。MCP 连接问题检查日志中的连接错误gemini --debug test command调试模式下Gemini CLI 会输出 MCP 会话的详细通信日志便于定位握手失败、认证头缺失或工具注册异常。OAuth 专属排查要点来自 docs/oauth-login.md固定端口被占用即致命Docker 方式下若 8085 被其他进程占用服务器会直接以错误停止而不会静默降级——这是刻意设计未获得的端口可能属于其他用户的进程。释放端口或改用其他--oauth-callback-port。无头环境 / CI当没有可用浏览器或回调时服务器自动回退到 GitHub 的device-code flow你会得到类似Visit https://github.com/login/device and enter the code WDJB-MJHT的提示在任何设备上完成授权即可无需回调端口。授权 URL 的呈现通道服务器按安全性从高到低选择通道——原生运行自动打开浏览器支持 MCP elicitation 的客户端会带外弹出链接URL 不进入模型上下文最安全最后的兜底是把 URL 放进工具响应并附带安全提示。参考文档Gemini CLI 的 MCP 配置结构文档README.md — 项目总览、工具集/工具配置、默认工具集定义docs/oauth-login.md — 本地 stdio 服务的 OAuth 登录完整说明docs/remote-server.md — 远程 MCP Server 的能力与可选请求头docs/server-configuration.md — 服务端配置速查与组合示例docs/installation-guides/README.md — 各宿主应用安装指南索引与支持矩阵gemini-extension.json — Gemini 扩展清单远程端点与认证头定义cmd/github-mcp-server/main.go — 服务端入口与 OAuth/PAT 优先级逻辑Dockerfile — 官方镜像构建过程与内置 OAuth 凭据注入方式【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Google Gemini CLI 中安装 GitHub MCP Server：四种接入方式的完整配置指南
在 Google Gemini CLI 中安装 GitHub MCP Server四种接入方式的完整配置指南【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server本篇指南以 GitHub 官方 MCP Server 仓库中的 docs/installation-guides/install-gemini-cli.md 为核心系统讲解如何在 Google Gemini CLI 中配置 GitHub MCP Server覆盖 Gemini 扩展、远程服务、本地 Docker 与原生二进制四种接入方式并深入 OAuth/PAT 两种认证模型与排错要点。读完本文你将掌握 Gemini CLI 的 MCP 配置语法settings.json中的mcpServers结构、如何安全存放 Personal Access TokenPAT、如何用/mcp list验证连通性并理解每种方式的适用场景与底层原理。前置条件在开始之前请确保满足以下条件已安装 Google Gemini CLIgemini命令可用。拥有一个具备合适权限范围的 GitHub Personal Access TokenPAT。若选择本地 Docker 方式需要安装并启动 Docker本地安装可选远程方式不需要。关于 Gemini CLI 在 GitHub MCP Server 各宿主应用中的支持情况可参考 docs/installation-guides/README.md 中的支持矩阵Gemini CLI 支持本地 GitHub MCPLocal与远程 GitHub MCPRemote其中远程方式仅支持 PAT 认证OAuth 暂不支持整体难度评级为 Easy。安全存放你的 PAT为了安全不要将 token 硬编码进配置。在~/.gemini/.env~是你的主目录或项目目录中创建或更新 PAT# ~/.gemini/.env GITHUB_MCP_PATyour_token_here这一做法的核心动机是配置文件如settings.json通常会被纳入版本控制或与他人共享而.env文件则适合加入.gitignore与访问权限控制。仓库 README 的 Handling PATs Securely 一节见 README.md同样推荐先通过环境变量或.env存放 token再在 MCP 配置中以变量引用的方式使用并强调最小权限原则、定期轮换、绝不提交到版本库。GitHub MCP Server 的 Gemini CLI 配置基础Gemini CLI 的 MCP 服务器统一在 settings JSON 的mcpServers键下配置全局配置~/.gemini/settings.json~为主目录项目级配置项目目录下的.gemini/settings.json配置完成后可能需要重启 Gemini CLI才能生效。提示如需获取最新最全的配置选项请参见仓库根目录的 README.md。仓库中还存在 docs/server-configuration.md 这样一份完整的服务端配置指南里面覆盖了 Toolsets工具集、单工具、排除工具、只读模式、Lockdown 模式等所有配置维度的速查表可与本篇安装指南配合阅读。配置生效后的能力概况当 GitHub MCP Server 成功接入后Gemini CLI 会获得 GitHub 平台的完整工具面。以远程服务默认工具集为例实际暴露的工具数量会达到近百个量级涵盖仓库、Issue、Pull Request、Actions、代码扫描等域。完整的工具集清单可以在 README.md 的 Available Toolsets 表格中查到例如Toolset说明context当前用户与 GitHub 上下文相关工具强烈推荐reposGitHub 仓库相关工具issuesGitHub Issues 相关工具pull_requestsGitHub Pull Request 相关工具usersGitHub 用户相关工具actionsGitHub Actions 工作流与 CI/CD 操作当未显式指定工具集时服务端默认启用context、repos、issues、pull_requests、users这五个默认工具集见 README.md 与 docs/server-configuration.md 中的默认行为说明。接入方式一Gemini 扩展推荐最简便的方式是使用 GitHub 托管的 MCP Server远程服务通过官方 gemini 扩展一键接入gemini extensions install https://github.com/github/github-mcp-server注意使用扩展方式时你仍然需要在环境中提供名为GITHUB_MCP_PAT、具备合适权限范围的 Personal Access Token。该扩展的本质在仓库根目录的 gemini-extension.json 中有直接体现——它就是一份描述 MCP 服务器连接信息的清单文件{ name: github, version: 1.0.0, mcpServers: { github: { description: Connect AI assistants to GitHub - manage repos, issues, PRs, and workflows through natural language., httpUrl: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer $GITHUB_MCP_PAT } } } }可以看到扩展指向的正是 GitHub 托管的远程 MCP 端点https://api.githubcopilot.com/mcp/并通过Authorization: Bearer $GITHUB_MCP_PAT请求头携带 token 完成认证——这正是方法一「零本地依赖」的原因服务端由 GitHub 托管Gemini CLI 只需持有 token 并建立 HTTP 连接。接入方式二远程服务Remote Server你也可以直接连接托管的 MCP Server。在安全存放 PAT 后按如下方式配置 Gemini CLI// ~/.gemini/settings.json { mcpServers: { github: { httpUrl: https://api.githubcopilot.com/mcp/, headers: { Authorization: Bearer $GITHUB_MCP_PAT } } } }这一配置本质上就是方法一中 gemini 扩展清单的等价手写版。远程服务的完整能力与可选配置可参考 docs/remote-server.md远程端点支持通过 URL 路径如/readonly只读变体、/insiders内测变体或请求头X-MCP-Toolsets、X-MCP-Tools、X-MCP-Readonly、X-MCP-Lockdown、X-MCP-Insiders做精细化控制并且远程服务还额外提供copilot_spaces、github_support_docs_search等仅在远程端可用的工具集。接入方式三本地 Docker在 Docker 运行的前提下可以在容器中运行 GitHub MCP Server。使用 OAuth 登录推荐无需创建 token在 github.com 上官方镜像已经内置了应用凭据因此你无需提供任何凭据——服务器在首次使用时打开浏览器登录且 token 只保留在内存中。在 Docker 中需要将固定回调端口发布到 loopback 地址即本机回环地址// ~/.gemini/settings.json { mcpServers: { github: { command: docker, args: [ run, -i, --rm, -p, 127.0.0.1:8085:8085, -e, GITHUB_OAUTH_CALLBACK_PORT, ghcr.io/github/github-mcp-server ], env: { GITHUB_OAUTH_CALLBACK_PORT: 8085 } } } }关键点解读镜像ghcr.io/github/github-mcp-server是官方 Docker 镜像见 Dockerfile默认命令为stdio内部暴露端口 8082。固定回调端口 8085容器无法访问宿主机的随机 loopback 端口因此必须固定端口并将其发布进容器。使用 8085 是为了匹配官方应用注册的回调 URL。完整原理与注意事项见 docs/oauth-login.md 的 Running in Docker 一节。仅发布到 loopback-p 127.0.0.1:8085:8085而非-p 8085:8085。容器内回调必然监听所有接口若普通发布会将授权码暴露到你的网络。这也是一个刻意设计的安全点固定端口被占用时服务器会直接报错退出而不会静默降级到设备码流程。使用 PAT 认证优先于 OAuth也可以改用 Personal Access Token 认证它优先于 OAuth// ~/.gemini/settings.json { mcpServers: { github: { command: docker, args: [ run, -i, --rm, -e, GITHUB_PERSONAL_ACCESS_TOKEN, ghcr.io/github/github-mcp-server ], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_MCP_PAT } } } }注意这里的环境变量传递技巧-e GITHUB_PERSONAL_ACCESS_TOKEN不带值让 Docker 从宿主机环境继承该变量而env块中的$GITHUB_MCP_PAT则由 Gemini CLI 展开。这与 README.md 中推荐的 PAT 处理方式一致。OAuth 与 PAT 的优先级规则从源码看静态 token 的优先级是写死的在 cmd/github-mcp-server/main.go 的stdio命令逻辑中只有当token 且未配置 GitHub App 认证时才会进入 OAuth 流程oauth.NewManager(...)。也就是说一旦设置了GITHUB_PERSONAL_ACCESS_TOKEN服务器直接使用它并完全跳过 OAuth。同样地GitHub App 认证--app-id等与 PAT、与 OAuth 互为互斥同时设置会直接报错退出。接入方式四原生二进制你可以从 GitHub Releases 页面下载最新的二进制发布包也可以从源码构建go build -o github-mcp-server ./cmd/github-mcp-server然后将/path/to/binary替换为二进制实际路径按如下方式配置 Gemini CLI// ~/.gemini/settings.json { mcpServers: { github: { command: /path/to/binary, args: [stdio], env: { GITHUB_PERSONAL_ACCESS_TOKEN: $GITHUB_MCP_PAT } } } }如需改用 OAuth 登录无需创建或存放 token则省略GITHUB_PERSONAL_ACCESS_TOKEN——原生二进制会使用随机 loopback 回调端口因此无需任何额外配置。详见 docs/oauth-login.md。关于原生二进制的 OAuth 行为有几点值得从源码层面理解官方发布的二进制与镜像通过构建期-ldflags注入了内置 OAuth 客户端见 Dockerfile 中的-X github.com/github/github-mcp-server/internal/buildinfo.OAuthClientID...。因此在 github.com 上运行时你可以零配置启动服务器不需要 token也不需要 client ID。在 cmd/github-mcp-server/main.go 中只有未显式提供--oauth-client-id、未请求 GitHub App 认证、且 host 归一化后为https://github.com时才会回落到内置客户端。若目标 host 是 GitHub Enterprise Server 或ghe.com则必须自带 OAuth 应用并通过--oauth-client-id指定。若三者PAT、GitHub App、OAuth client均未配置服务器会直接以错误退出authentication required: set GITHUB_PERSONAL_ACCESS_TOKEN, configure GitHub App auth, or pass --oauth-client-id to log in via OAuth。OAuth 流程简要原理本地stdio服务器的 OAuth 登录流程详见 docs/oauth-login.md采用authorization code flow with PKCE服务器在本机启动 loopback 回调打开 GitHub 授权页用 PKCE verifier 与 client secret 兑换 token。由于这是公开的分布式客户端内置于二进制中的 secret 并非真正机密——PKCE 才是安全关键它把授权码绑定到本次登录尝试上防止被截获的 code 在其他地方兑换。token 只保留在内存中不落盘GitHub App 的 token 过期后还会通过 refresh token 透明刷新长时间会话无需重新授权。验证配置是否成功配置完成后在终端启动 Gemini CLI运行gemini然后检查 MCP 服务器状态/mcp list正常输出类似ℹConfigured MCP servers: github - Ready (96 tools, 2 prompts) Tools: - github__add_comment_to_pending_review - github__add_issue_comment - github__add_sub_issue ...状态表示服务器就绪工具数量会随所用工具集不同而变化。除了 ToolsGitHub MCP Server 还会注册 MCP Prompts工作流提示词源码可见于 pkg/github/prompts.go这也解释了输出中的 2 prompts。用提示词实测List my GitHub repositories若返回你的仓库列表说明认证与工具调用链路完全打通。进阶配置选项Gemini CLI 本身还支持更多 MCP 配置结构例如跳过工具确认或排除特定工具。这些能力与 GitHub MCP Server 的服务端配置正交你既可以在 Gemini CLI 侧裁剪工具可见性也可以利用仓库自身的配置维度工具集、单工具、排除工具、只读模式、Lockdown 模式等做服务端裁剪二者可组合使用。完整的服务端配置速查见 docs/server-configuration.md其中明确了各类配置在远程与本地两种形态下的对应方式例如配置维度本地 Server工具集Toolsets--toolsets标志或GITHUB_TOOLSETS环境变量单工具Tools--tools标志或GITHUB_TOOLS环境变量排除工具--exclude-tools标志或GITHUB_EXCLUDE_TOOLS环境变量只读模式--read-only标志或GITHUB_READ_ONLY环境变量以 Docker 方式为例通过环境变量启用只读模式与指定工具集的写法docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKENyour-token \ -e GITHUB_READ_ONLYtrue \ -e GITHUB_TOOLSETSrepos,issues,pull_requests,actions,code_security \ ghcr.io/github/github-mcp-server故障排查本地服务端问题Docker 报错确保 Docker Desktop 正在运行docker --version镜像拉取失败尝试先docker logout ghcr.io再重试。镜像ghcr.io/github/github-mcp-server是公开的出现拉取错误通常是本机存在已过期的 ghcr.io token 所致参见 README.md 前置条件说明。Docker 未找到安装 Docker Desktop 并确保其运行。认证问题PAT 无效确认你的 GitHub PAT 具备正确的权限范围repo— 仓库操作read:packages— Docker 镜像访问若使用 Dockertoken 过期重新生成一个新的 GitHub PAT并按文首方式更新~/.gemini/.env。配置问题JSON 无效验证你的配置cat ~/.gemini/settings.json | jq .jq会解析 JSON 并高亮语法错误若未安装 jq也可使用python -m json.tool ~/.gemini/settings.json做等价校验。MCP 连接问题检查日志中的连接错误gemini --debug test command调试模式下Gemini CLI 会输出 MCP 会话的详细通信日志便于定位握手失败、认证头缺失或工具注册异常。OAuth 专属排查要点来自 docs/oauth-login.md固定端口被占用即致命Docker 方式下若 8085 被其他进程占用服务器会直接以错误停止而不会静默降级——这是刻意设计未获得的端口可能属于其他用户的进程。释放端口或改用其他--oauth-callback-port。无头环境 / CI当没有可用浏览器或回调时服务器自动回退到 GitHub 的device-code flow你会得到类似Visit https://github.com/login/device and enter the code WDJB-MJHT的提示在任何设备上完成授权即可无需回调端口。授权 URL 的呈现通道服务器按安全性从高到低选择通道——原生运行自动打开浏览器支持 MCP elicitation 的客户端会带外弹出链接URL 不进入模型上下文最安全最后的兜底是把 URL 放进工具响应并附带安全提示。参考文档Gemini CLI 的 MCP 配置结构文档README.md — 项目总览、工具集/工具配置、默认工具集定义docs/oauth-login.md — 本地 stdio 服务的 OAuth 登录完整说明docs/remote-server.md — 远程 MCP Server 的能力与可选请求头docs/server-configuration.md — 服务端配置速查与组合示例docs/installation-guides/README.md — 各宿主应用安装指南索引与支持矩阵gemini-extension.json — Gemini 扩展清单远程端点与认证头定义cmd/github-mcp-server/main.go — 服务端入口与 OAuth/PAT 优先级逻辑Dockerfile — 官方镜像构建过程与内置 OAuth 凭据注入方式【免费下载链接】github-mcp-serverGitHubs official MCP Server项目地址: https://gitcode.com/GitHub_Trending/gi/github-mcp-server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考