GitHub MCP Server 如何部署？Windows、Linux、macOS 全平台教學

GitHub MCP Server 是 GitHub 官方維護的 Model Context Protocol 伺服端，讓 Cursor、Claude Desktop、VS Code Copilot 等 AI 宿主能透過標準化工具呼叫 GitHub REST / GraphQL API——查詢儲存庫、讀取 Issue、開啟 PR、搜尋程式碼，不必在對話中反覆貼上 gh 命令輸出。

本文依「先選型、再裝環境、最後接入 IDE」的順序，涵蓋 Windows、Linux、macOS 三種安裝路徑，並附上可直接複製的設定片段與故障排除清單。

2025 年 4 月起，社群早期的 npm 套件 @modelcontextprotocol/server-github 已停用；目前唯一受官方支援的本地映像為 ghcr.io/github/github-mcp-server，遠端託管端點為 https://api.githubcopilot.com/mcp/。

部署方式怎麼選

在動手安裝軟體之前，先對照下方表格，確認自己要走哪條路：

三種方式驗證邏輯相同：可設定 Personal Access Token（PAT），或在本地 Docker / 二進位模式下走 OAuth 瀏覽器登入（token 僅駐留記憶體，不寫入磁碟）。

通用前置準備

無論選擇哪條路徑，建議先完成以下四步：

1. 建立 GitHub PAT
   開啟 Fine-grained PAT 建立頁，依你要使用的工具勾選權限。唯讀瀏覽儲存庫通常需要 Contents: Read、Metadata: Read；若要建立 PR / Issue，再追加寫入權限。

2. 確認宿主版本
   - Cursor：v0.48.0+ 才支援遠端 Streamable HTTP
   - Claude Desktop / VS Code：請參考各自 MCP 文件

3. （本地 Docker 方案）安裝並啟動 Docker
   - Windows / macOS：Docker Desktop
   - Linux：Docker Engine + 將目前使用者加入 docker 群組

4. 預先拉取映像（選用但建議）

docker pull ghcr.io/github/github-mcp-server

若拉取出現 unauthorized，執行 docker logout ghcr.io 後重試——有時是過期的 ghcr 登入狀態造成干擾。

方式一：遠端託管（最省事）

GitHub 在 https://api.githubcopilot.com/mcp/ 提供託管 MCP 端點，本機無需 Docker。適合 Linux 伺服器、Windows 輕量環境，或公司政策禁止執行容器的情境。

Cursor 設定範例

編輯全域設定 ~/.cursor/mcp.json（Windows 路徑為 %USERPROFILE%\.cursor\mcp.json）：

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

將 YOUR_GITHUB_PAT 替換為真實 token，儲存後完全重啟 Cursor。在 Settings → Tools & Integrations → MCP Tools 中應看到綠色線上指示；在 Composer 裡問一句「列出我的 GitHub 儲存庫」即可驗收。

注意事項

• 遠端模式目前以 PAT 驗證為主；部分宿主對 OAuth 的支援仍在完善中。
• 公司代理 / 防火牆需放行對 api.githubcopilot.com 的 HTTPS 出站連線。
• 不要把 PAT 寫進版本庫；專案級設定使用 .cursor/mcp.json 時記得加入 .gitignore。

方式二：Docker 本地部署（官方推薦）

Docker 方案透過 stdio 與宿主通訊：宿主啟動 docker run -i ...，容器內行程讀寫標準輸入輸出。這也是 Claude Desktop、Windsurf、Cursor 一鍵安裝按鈕背後的預設命令。

macOS 安裝步驟

1. 安裝 Docker Desktop for Mac（Apple Silicon 選 ARM64 版）。
2. 選單列鯨魚圖示顯示 Running。
3. 終端機驗證：

docker run --rm ghcr.io/github/github-mcp-server --help

4. 寫入 ~/.cursor/mcp.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": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Linux 安裝步驟

1. 依發行版安裝 Docker Engine（Ubuntu 範例：sudo apt install docker.io）。
2. 將使用者加入 docker 群組，避免每次 sudo：

sudo usermod -aG docker "$USER"
newgrp docker

3. 確認 Docker 守護行程已啟動：sudo systemctl enable --now docker。
4. MCP 設定與 macOS 完全相同——~/.cursor/mcp.json 路徑一致。

在 無圖形介面的 Linux 伺服器上，若不想在設定裡明文寫入 PAT，可改用環境變數注入：

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

然後在 mcp.json 的 env 區塊裡引用同名變數（部分宿主支援 ${env:GITHUB_PERSONAL_ACCESS_TOKEN} 語法，以宿主文件為準）。

Windows 安裝步驟

1. 安裝 Docker Desktop for Windows。
   - 建議使用 WSL 2 後端（Settings → General → Use WSL 2 based engine）。
2. 確認 Docker Desktop 系統匣圖示為執行狀態。
3. 設定檔路徑：%USERPROFILE%\.cursor\mcp.json。
4. JSON 內容與 macOS 一致；command 仍為 docker（Docker Desktop 會將 CLI 加入 PATH）。

Windows 常見陷阱：WSL 裡能跑 docker，但 Windows 宿主 Cursor 讀的是 Windows 端的 mcp.json——兩邊設定不要混用。若 Cursor 裝在 Windows、專案在 WSL，優先在 Windows 使用者目錄 設定 MCP。

OAuth 登入（免手動輸入 PAT）

官方映像內建 OAuth 應用程式憑證。Docker 模式下需將回呼埠映射到本機回環位址：

{
  "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"
      }
    }
  }
}

首次連線會跳出瀏覽器完成 GitHub 登入；token 儲存在記憶體，容器結束即失效。無頭伺服器可查閱官方文件的 device code 回退流程。

方式三：Go 原始碼編譯（無 Docker）

適合無法安裝 Docker、或需要精簡 toolset（只暴露部分 API 能力）的情境。

三平台共同步驟

前置：安裝 Go 1.24+。

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build -o github-mcp-server cmd/github-mcp-server/main.go

編譯產物命名可自訂；下文以 ./github-mcp-server 為例。

以 PAT 啟動（stdio 模式）：

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
./github-mcp-server stdio

Cursor 接入本地二進位：

{
  "mcpServers": {
    "github": {
      "command": "/绝对路径/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

升級時重新 git pull && go build 即可；不必等待 Docker 映像發版。

接入其他 IDE 與 CLI

設定鍵名因宿主而異，但 Docker 命令列核心一致：

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

• Claude Desktop：claude_desktop_config.json 裡的 mcpServers 區塊，結構與 Cursor 相同。
• VS Code Copilot：支援遠端 + 本地；本地同樣建議使用 Docker 映像。
• Claude Code CLI：傾向輕量二進位方案，減少容器開銷。

各宿主完整範例請見官方儲存庫 docs/installation-guides/ 目錄。

安全與維運建議

1. 最小權限 PAT：依 toolset 開啟權限，定期輪換。
2. 設定檔權限：chmod 600 ~/.cursor/mcp.json（Linux / macOS）。
3. 唯讀模式：啟動參數可啟用 read-only，防止 AI 誤改儲存庫。
4. 企業 GitHub Enterprise Server：需自建 OAuth App / GitHub App，不能使用 github.com 預設 OAuth 憑證——詳見官方 docs/oauth-login.md。

平台差異補充說明

路徑與環境變數

~/.cursor/mcp.json

macOS 與 Linux 的全域 MCP 設定；Windows 對應 %USERPROFILE%\.cursor\mcp.json。

GITHUB_PERSONAL_ACCESS_TOKEN

Docker / 二進位模式下的 PAT 環境變數名稱；設定後優先順序高於 OAuth 流程。

GITHUB_OAUTH_CALLBACK_PORT

OAuth 瀏覽器回呼監聽埠，Docker 情境通常固定為 8085。

快速鍵與慣用做法

在 Cursor Composer 中，可用 Cmd+Shift+P（Windows 為 Ctrl+Shift+P）開啟命令面板，搜尋 MCP 相關設定。早期有人習慣用 npx @modelcontextprotocol/server-github 一行命令啟動服務——該方式已停用，請改用本文的 Docker 或遠端端點方案。

正式環境務必將 PAT 放在環境變數或金鑰管理器裡，不要寫進會被 git 追蹤的專案檔案。

驗證清單（發佈前）

1. MCP 面板綠點
2. 工具列表出現 github_* 前綴項目
3. 試呼叫唯讀操作（如列儲存庫）成功

日誌位置提示

Cursor 日誌可在 Help → Toggle Developer Tools → Console 中過濾 MCP 關鍵字查看；Claude Desktop 日誌路徑因平台而異，官方 troubleshooting 章節有完整列表。

故障排除速查

本地快速自檢：在終端機手動執行 Docker 命令，看 stderr 是否立即報錯；再比對 IDE 日誌裡的 MCP 啟動命令是否一致。

小結

• 想最快用上：遠端 https://api.githubcopilot.com/mcp/ + PAT，Cursor v0.48+ 直接設定 url。
• 想穩定可重現：三平台統一 docker run -i --rm ... ghcr.io/github/github-mcp-server。
• 想極致輕量或自訂：go build 出二進位，stdio 接入。

部署完成後，在 AI 對話裡用自然語言操作 GitHub——例如「為 kvmkit 儲存庫最近 5 個 open issue 做個摘要」——才是 MCP 真正省時間的地方。若你同時在搭建 CI/CD 流水線 或需要 7×24 雲端 Mac 建置節點，可以把 MCP 輔助開發與自動化發佈放在同一套工具鏈裡統籌規劃。

常見問題