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

你在 Cursor 裡想讓 Agent 直接查 Issue、開 PR、讀取儲存庫檔案——卻卡在「到底該裝哪個 GitHub MCP Server」：npm 上的舊套件早已棄用，網路教學又各說各話。本文以 GitHub 官方儲存庫 github/github-mcp-server（截至 2026-07-31 最新 v1.7.0）為準，把遠端託管、Docker 本地、預編譯二進位檔、源碼編譯四條路徑寫清楚，Windows / Linux / macOS 照抄即可。

交付聲明： 本文涵蓋 PAT 申請、各平台設定檔路徑、Cursor / Claude Desktop / VS Code Copilot 接入範例，以及七步驗收清單。不討論第三方非官方 Server 實作。

---

Quick Answer：四種部署方式怎麼選

先對照下表，30 秒內確定你的路徑；大多數個人開發者從方式一（遠端託管）開始，團隊內網或需要憑證隔離時選方式二（Docker）。

部署前準備：PAT、主機應用與設定路徑

1. 申請 GitHub Personal Access Token

前往 GitHub → Settings → Personal access tokens 建立 Fine-grained 或 Classic PAT。常用 scope 如下：

• repo — 讀寫儲存庫內容、分支、提交
• read:org — 讀取組織與團隊資訊
• 按需追加 read:project、workflow 等（取決於你要讓 Agent 操作的範圍）

2. MCP 主機應用與設定檔路徑

不同用戶端的設定檔位置不同。下表按作業系統列出最常見路徑——改完 JSON 後通常需要完全重啟用戶端。注意：部分編輯器會在儲存時自動格式化 JSON，若把 PAT 寫進 env 欄位，確認格式化後引號與逗號仍然合法。

若團隊需要隔離的 Mac 環境做 MCP 聯調（避免 PAT 落在個人筆電上），可先租一台 Macstripe 雲 Mac 作為專用測試節點，SSH 進去設定 Docker 或二進位檔，與本機 Cursor 透過 stdio/遠端隧道對接。

方式一：遠端託管 Server（全平台相同）

GitHub 提供官方遠端 MCP 端點：https://api.githubcopilot.com/mcp/。優點是Windows、Linux、macOS 設定完全一致，無需本地跑程序或裝 Docker。

認證方式：在 HTTP 請求標頭中攜帶 Authorization: Bearer <YOUR_GITHUB_PAT>。各用戶端對遠端 Server 的 JSON 欄位名略有差異，下面給出 Cursor 與 VS Code 的通用寫法。

Cursor / VS Code 設定範例

編輯 ~/.cursor/mcp.json（或專案級 .cursor/mcp.json）：

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

儲存後完全退出並重啟 Cursor，在 Settings → MCP 面板確認 github 顯示綠色 Connected。首次連線若彈出授權提示，按用戶端指引完成即可。

遠端託管的優勢在於：GitHub 負責 Server 版本升級與安全修補，你只需維護 PAT 生命週期。對於企業內網環境，若出口 HTTPS 被代理攔截，需在系統或用戶端中設定 HTTPS_PROXY，確保能存取 api.githubcopilot.com。測試連通性可在終端機執行：

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ghp_xxxxxxxxxxxxxxxxxxxx" \
  https://api.githubcopilot.com/mcp/

返回 200 或 405（Method Not Allowed，說明端點可達）即表示網路與 Token 基本正常。若回傳 401，檢查 PAT 是否過期或 scope 不足。

方式二：Docker 本地部署

官方映像檔：ghcr.io/github/github-mcp-server。本地 Docker 適合需要憑證隔離、離線執行或自訂網路策略的團隊。映像檔支援 PAT 與 OAuth 兩種認證模式。

各平台 Docker 前置

• Windows： 安裝 Docker Desktop，啟用 WSL2 後端，確保 docker version 正常。建議在 Docker Desktop → Settings → Resources 分配至少 2GB 記憶體，避免容器啟動時 OOM。
• macOS： 安裝 Docker Desktop for Mac（Apple Silicon 自動拉取 ARM 映像檔，無需額外設定）。若使用 Rosetta 轉譯的 Intel 版 Docker，請確認拉取的是正確架構的映像層。
• Linux： 安裝 Docker Engine（sudo apt install docker.io 或發行版等價套件），將使用者加入 docker 群組後重新登入，否則每次都要 sudo docker。

三種平台的 mcp.json 內容完全相同——這是 Docker 方案相比二進位檔方案的另一個優勢：寫一次設定，團隊內 Windows / macOS / Linux 開發者直接複用。

PAT 模式 — mcp.json 設定

Docker 透過環境變數 GITHUB_PERSONAL_ACCESS_TOKEN 傳入 PAT：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

OAuth 模式 — 需對應回呼埠

若使用 OAuth 流程，需將容器內回呼埠對應到本機 127.0.0.1:8085，並設定 GITHUB_OAUTH_CALLBACK_PORT=8085：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT=8085",
        "ghcr.io/github/github-mcp-server"
      ]
    }
  }
}

首次連線時瀏覽器會開啟 GitHub 授權頁；授權完成後 Token 由 Server 管理，無需在 JSON 裡寫 PAT。

驗證 Docker 映像檔可拉取

docker pull ghcr.io/github/github-mcp-server
docker run --rm ghcr.io/github/github-mcp-server --version

若團隊把 MCP Server 跑在隔離的遠端 Mac 上（例如 Macstripe 雲節點），Windows 開發者可透過 SSH 隧道把 stdio 轉發到本機 Cursor——既保留 macOS 側的環境一致性，又不在個人電腦上暴露 PAT。更多 MCP 安全與上線實踐可參考 AGNTCon MCP 部署指南。

方式三：預編譯二進位檔

不想裝 Docker 時，可從 GitHub Releases 下載對應平台的預編譯套件（v1.7.0 起）：

macOS / Linux 安裝與 PATH

# 以 macOS ARM 為例
tar -xzf github-mcp-server_Darwin_arm64.tar.gz
sudo mv github-mcp-server /usr/local/bin/
chmod +x /usr/local/bin/github-mcp-server
github-mcp-server --version

Windows 安裝

# PowerShell
Expand-Archive github-mcp-server_Windows_x86_64.zip -DestinationPath C:\Tools\github-mcp-server
# 將 C:\Tools\github-mcp-server 加入系統 PATH

mcp.json 設定（stdio 模式）

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Windows 上若 PATH 未生效，可寫絕對路徑："command": "C:\\Tools\\github-mcp-server\\github-mcp-server.exe"。

二進位檔方案的優點是啟動快、不依賴 Docker 常駐程序；缺點是版本升級需手動下載新 Release 並替換檔案。建議團隊維護一份內部文件，記錄目前使用的版本號（如 v1.7.0）與校驗和，避免不同成員跑不同版本的 Server 導致工具行為不一致。

方式四：源碼編譯（進階）

需要打自訂分支、貢獻 PR 或稽核全部源碼時，從官方儲存庫編譯。要求 Go 1.24+。

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
git checkout v1.7.0   # 或 main
go build -o github-mcp-server ./cmd/github-mcp-server
./github-mcp-server --version

編譯產物用法與方式三相同，在 mcp.json 裡把 command 指向你編譯出的二進位檔路徑即可。生產環境更推薦固定 tag（如 v1.7.0）而非直接追蹤 main。

源碼編譯適合兩類人：一是要給 github/github-mcp-server 提 PR 的貢獻者；二是企業安全團隊需要稽核每一行程式碼、打內部修補後再分發二進位檔。一般開發者若無客製需求，方式一或方式二已足夠，不必為此安裝 Go 工具鏈。

接入主流 MCP 主機：Cursor、Claude Desktop、VS Code Copilot

三种用戶端的 JSON 结构略有差异，核心都是声明一个 mcpServers 條目。下面彙總最常見寫法（以 Docker PAT 模式為例，遠端託管只需把 command/args 換成 url + headers）。

Cursor

全域設定 ~/.cursor/mcp.json，專案級用 .cursor/mcp.json。專案級設定適合「只有這個儲存庫需要 GitHub MCP」的場景——比如開源貢獻專案與個人 side project 使用不同的 PAT。重啟後在聊天視窗輸入「列出我的 GitHub 儲存庫」驗證工具是否可用；若 Agent 回覆「我沒有 GitHub 工具」，說明 MCP 未正確載入，回到 MCP 面板檢查日誌。

Claude Desktop

編輯对应平台的 claude_desktop_config.json，結構與 Cursor 相同，頂層鍵也是 mcpServers：

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

儲存後退出 Claude Desktop 再開啟。macOS 使用者可在選單列圖示 → Settings → Developer 查看 MCP 連線日誌。

VS Code Copilot（Agent 模式）

在 VS Code 1.99+ 中，Copilot Chat 支援 MCP。開啟 Command Palette → MCP: Add Server，或在工作區建立 .vscode/mcp.json。遠端託管寫法與 Cursor 完全一致。

不確定該用 Cursor 還是 Claude Code？可參考 AI 程式設計工具選購對比，再決定 MCP 主機。

七步驗收清單與常見故障排除

設定完成後，按下面清單逐項打勾，確保 Agent 能真正呼叫 GitHub 工具。

• Step 1： PAT 已建立且 scope 包含 repo（及所需的 read:org 等）
• Step 2： mcp.json JSON 語法合法（可用 jq . 或線上校驗器檢查）
• Step 3： 用戶端已完全重启（不是只关窗口）
• Step 4： MCP 面板顯示 github 為 Connected / 綠色
• Step 5： 對話中執行「列出我的 GitHub 儲存庫」能回傳真實儲存庫名
• Step 6： 嘗試讀取某個私有儲存庫檔案，確認 PAT 權限足夠
• Step 7： 检查用戶端日志无 401 Unauthorized 或 connection refused

常見故障排除表

舊觀念：「裝個 npm 套件就能連 GitHub。」
2025 年 4 月起官方路線是 github/github-mcp-server；遠端託管則連 api.githubcopilot.com/mcp/，不要再搜 server-github。

常見問題

遠端託管與 Docker 本地部署該怎麼選？

個人嘗鮮或團隊快速驗證，優先選 GitHub 遠端託管（https://api.githubcopilot.com/mcp/），全平台設定相同、無需維護程序。需要離線執行、自訂工具集或嚴格憑證隔離時，選 Docker 本地部署（ghcr.io/github/github-mcp-server）。

還能用 npm 的 @modelcontextprotocol/server-github 嗎？

不能。該 npm 套件已於 2025 年 4 月棄用，請改用 GitHub 官方儲存庫 github/github-mcp-server（目前最新 v1.7.0）。

PAT 需要哪些權限範圍？

Fine-grained 或 Classic PAT 至少包含 repo（讀寫儲存庫）與 read:org（讀取組織資訊）。若需操作 Issues、Pull Requests 或 Projects，按實際工具呼叫範圍追加對應 scope。

Windows 上 Docker 拉映像檔失敗怎麼辦？

確認 Docker Desktop 已启动且 WSL2 后端正常；在 Settings → Resources 给 Docker 分配足够内存；执行 docker login ghcr.io 後重試 docker pull ghcr.io/github/github-mcp-server。

Cursor 改了 mcp.json 不生效怎麼辦？

儲存 JSON 後完全退出 Cursor 再重啟；檢查 ~/.cursor/mcp.json 與專案 .cursor/mcp.json 是否衝突（專案級優先）；在 Settings → MCP 面板查看連線狀態與錯誤日誌。

總結

GitHub MCP Server 的官方部署路線已經很清晰：

1. 最快上手 — 遠端託管 https://api.githubcopilot.com/mcp/ + PAT，全平台同一套 JSON
2. 本地可控 — Docker 镜像 ghcr.io/github/github-mcp-server，PAT 或 OAuth 二選一
3. 無 Docker — Releases 下載預編譯二進位檔，配好 PATH 即可
4. 進階客製 — Go 1.24+ 源碼編譯，固定 tag 上線

建議先用遠端託管在 Cursor 裡跑通「列儲存庫 → 讀檔案 → 查 Issue」三步，確認 PAT 權限無誤後，再決定是否遷到 Docker 或遠端 Mac 隔離環境。

對於團隊場景，推薦把 MCP 設定檔（去掉 PAT 明文後）納入版本管理，用環境變數或金鑰管理服務注入 Token——這與 MCP 安全部署最佳實踐一致。Windows 開發者若同時要 iOS 建置與 Agent 工作流，Macstripe 雲 Mac 可按天租用專用節點，約 5 分鐘開通 SSH，把 MCP Server、Xcode 與 Fastlane 放在同一台 macOS 上，筆電只當遠端終端——比在個人電腦上混跑 Docker + Xcode 遠端外掛穩定得多。

延伸閱讀

• AGNTCon MCPCon Europe 2026 MCP 部署指南 →
• Claude Code vs Cursor vs Codex：AI 程式設計工具選購 2026 →
• iOS CI 慢、GitHub Actions 一直排隊？用 Cloud Mac 這樣解決（2026） →