GitHub MCP（Model Context Protocol）服务器为 AI 工具提供了与 GitHub API 交互的标准接口。通过该服务器，AI 代理可以直接执行仓库操作、管理 Issue、处理 Pull Request 等任务。GitHub 官方维护的仓库为 github/github-mcp-server，支持远程托管和本地运行两种模式。

前置条件

一个 GitHub 账户

兼容的 MCP 主机（VS Code 1.101+、Claude Desktop、Cursor、Windsurf 等）

对于本地模式：需要安装 Docker

了解 GitHub Personal Access Token 的创建方法

远程 vs 本地安装

远程 GitHub MCP 服务器

远程模式由 GitHub 托管，是最简单的启动方式。如果你的 MCP 主机不支持远程服务器，请使用本地版本。

#### 在 VS Code 中安装

使用 OAuth 认证（推荐）：

json
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

使用 GitHub PAT 认证：

json
{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "github_mcp_pat",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ]
}

#### 在其他 MCP 主机中安装

Copilot CLI - 参考 安装指南

Claude Desktop / Claude Code - 参考 安装指南

Cursor - 参考 安装指南

Windsurf - 参考 安装指南

Zed - 参考 安装指南

OpenCode - 参考 安装指南

Google Gemini CLI - 参考 安装指南

本地 GitHub MCP 服务器

本地模式通过 Docker 容器运行，镜像地址为 ghcr.io/github/github-mcp-server。

#### 使用 Docker 安装

OAuth 认证（推荐，无需手动创建令牌）：

json
{
  "mcp": {
    "servers": {
      "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"
        }
      }
    }
  }
}

使用 PAT 认证：

json
{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "github_token",
        "description": "GitHub Personal Access Token",
        "password": true
      }
    ],
    "servers": {
      "github": {
        "command": "docker",
        "args": [
          "run",
          "-i",
          "--rm",
          "-e",
          "GITHUB_PERSONAL_ACCESS_TOKEN",
          "ghcr.io/github/github-mcp-server"
        ],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"
        }
      }
    }
  }
}

#### 从源码构建

如果没有 Docker，可以使用 Go 编译：

bash
go build -o /path/to/github-mcp-server ./cmd/github-mcp-server

配置示例：

json
{
  "mcp": {
    "servers": {
      "github": {
        "command": "/path/to/github-mcp-server",
        "args": ["stdio"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": ""
        }
      }
    }
  }
}

认证

Personal Access Token (PAT)

推荐使用细粒度 PAT，最小权限原则：

repo - 仓库操作

read:packages - Docker 镜像访问

read:org - 组织团队访问

安全存储 PAT

环境变量（推荐）：

bash
export GITHUB_PAT=your_token_here

创建 .env 文件：

env
GITHUB_PAT=your_token_here

保护配置文件：

bash
chmod 600 ~/.your-app/config.json

工具集与常用工具

默认工具集

当未指定工具集时，默认启用：

context

repos

issues

pull_requests

users

配置工具集

通过命令行参数：

bash
github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security

通过环境变量：

bash
GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server

配置单个工具

通过命令行参数：

bash
github-mcp-server --tools get_file_contents,issue_read,create_pull_request

通过环境变量：

bash
GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server

特殊工具集

all：启用所有可用工具集

default：默认配置，可与其他工具集组合使用

Docker 中的工具集配置

bash
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN= \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" \
  ghcr.io/github/github-mcp-server

只读模式与安全建议

只读模式

通过 --read-only 标志启用只读模式，所有写入工具将被跳过：

bash
github-mcp-server --read-only

安全最佳实践

最小权限：仅授予必要的权限范围

分离令牌：不同项目使用不同 PAT

定期轮换：定期更新令牌

永不提交：令牌不要提交到版本控制

文件权限：限制配置文件访问权限

GitHub Enterprise 支持

GitHub Enterprise Cloud（ghe.com）

json
{
  "servers": {
    "github-octocorp": {
      "type": "http",
      "url": "https://copilot-api.octocorp.ghe.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:github_mcp_pat}"
      }
    }
  }
}

GitHub Enterprise Server

使用本地服务器配置，通过 --gh-host 或 GITHUB_HOST 环境变量设置主机名：

json
{
  "servers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITHUB_HOST",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
        "GITHUB_HOST": "https://"
      }
    }
  }
}

FAQ

Q: 远程模式和本地模式有什么区别？

A: 远程模式由 GitHub 托管，无需本地运行 Docker 容器，适合 VS Code 1.101+ 等支持远程 MCP 的主机。本地模式通过 Docker 运行 ghcr.io/github/github-mcp-server 镜像，适用于所有支持本地 MCP 的主机。

Q: 如何选择 OAuth 还是 PAT 认证？

A: OAuth 认证无需手动创建令牌，令牌仅保存在内存中，更安全。PAT 认证需要手动创建令牌，适合需要持久化配置或无法使用 OAuth 的场景。GITHUB_PERSONAL_ACCESS_TOKEN 环境变量优先级高于 OAuth。

Q: 如何启用只读模式？

A: 使用 --read-only 命令行参数或设置环境变量。只读模式下所有写入工具（如创建 Issue、推送代码）都会被跳过，即使通过 --tools 明确指定也会被忽略。

Q: 工具集和单个工具可以同时使用吗？

A: 可以。工具集和单个工具是累加关系。例如 --toolsets repos,issues --tools get_gist 会注册 repos 和 issues 工具集中的所有工具，再加上 get_gist 工具。

Q: 如何排查连接问题？

A: 使用 github-mcp-server tool-search 命令搜索可用工具，例如 github-mcp-server tool-search "issue" --max-results 5。在 Docker 中运行时需要添加 -t 或 -it 参数以启用彩色输出。

*最后更新：2026 年 7 月。以 GitHub 官方仓库 github/github-mcp-server 为准。*