How to Deploy GitHub MCP Server: Windows, Linux & macOS Guide

You want your Cursor Agent to look up Issues, open PRs, and read repo files—but you're stuck on which GitHub MCP Server to install. The old npm package was deprecated ages ago, and every tutorial online says something different. This guide follows the official github/github-mcp-server repo (latest v1.7.0 as of 2026-07-31) and walks through all four deployment paths—remote hosted, local Docker, prebuilt binaries, and source builds—with copy-paste configs for Windows, Linux, and macOS.

What this covers: PAT setup, config file paths per platform, Cursor / Claude Desktop / VS Code Copilot integration examples, and a seven-step acceptance checklist. Third-party, non-official Server implementations are out of scope.

Quick Answer: Which deployment path to choose

Start with the table below—pick your path in 30 seconds. Most individual developers begin with Method 1 (remote hosted); teams on private networks or with strict credential isolation should look at Method 2 (Docker).

Before you deploy: PAT, host apps, and config paths

1. Create a GitHub Personal Access Token

Go to GitHub → Settings → Personal access tokens and create a Fine-grained or Classic PAT. Common scopes:

• repo — read/write repository content, branches, and commits
• read:org — read organization and team information
• Add read:project, workflow, and others as needed depending on what your Agent will do

2. MCP host apps and config file paths

Each client stores MCP config in a different location. The table below lists the most common paths per OS—after editing JSON, you usually need a full restart. Note: some editors auto-format JSON on save; if you put a PAT in the env field, confirm quotes and commas are still valid after formatting.

If your team needs an isolated Mac environment for MCP integration testing (so PATs never land on personal laptops), rent a Macstripe cloud Mac as a dedicated test node—SSH in, configure Docker or a binary, and connect from your local Cursor over stdio or a remote tunnel.

Method 1: Remote hosted Server (same on every platform)

GitHub provides an official remote MCP endpoint: https://api.githubcopilot.com/mcp/. The big advantage is identical config on Windows, Linux, and macOS—no local process or Docker required.

Authentication: send Authorization: Bearer <YOUR_GITHUB_PAT> in the HTTP request header. Remote Server JSON field names vary slightly by client; below are the common patterns for Cursor and VS Code.

Cursor / VS Code config example

Edit ~/.cursor/mcp.json (or project-level .cursor/mcp.json):

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

After saving, fully quit and restart Cursor. In Settings → MCP, confirm github shows green Connected. If an authorization prompt appears on first connect, follow the client instructions.

With remote hosting, GitHub handles Server upgrades and security patches—you only manage PAT lifecycle. In corporate networks where outbound HTTPS is proxied, configure HTTPS_PROXY in the system or client so api.githubcopilot.com is reachable. Test connectivity from a terminal:

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

A response of 200 or 405 (Method Not Allowed—the endpoint is reachable) means network and token basics are fine. 401 usually means an expired PAT or insufficient scopes.

Method 2: Local Docker deployment

Official image: ghcr.io/github/github-mcp-server. Local Docker suits teams that need credential isolation, offline operation, or custom network policies. The image supports both PAT and OAuth authentication.

Docker prerequisites by platform

• Windows: Install Docker Desktop, enable the WSL2 backend, and confirm docker version works. Under Docker Desktop → Settings → Resources, allocate at least 2GB RAM to avoid OOM on container start.
• macOS: Install Docker Desktop for Mac (Apple Silicon pulls ARM images automatically—no extra config). If you run the Intel Docker build under Rosetta, verify you're pulling the correct architecture layers.
• Linux: Install Docker Engine (sudo apt install docker.io or your distro's equivalent), add your user to the docker group, then log out and back in—otherwise you'll need sudo docker every time.

The mcp.json content is identical across all three platforms—another Docker advantage over binaries: write once, reuse across Windows / macOS / Linux on your team.

PAT mode — mcp.json config

Docker receives the PAT via the GITHUB_PERSONAL_ACCESS_TOKEN environment variable:

{
  "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 mode — map the callback port

For OAuth flow, map the container callback port to 127.0.0.1:8085 on the host and set 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"
      ]
    }
  }
}

On first connect, your browser opens the GitHub authorization page. After approval, the Server manages the token—no PAT in JSON.

Verify the Docker image pulls

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

If your team runs the MCP Server on an isolated remote Mac (e.g. a Macstripe cloud node), Windows developers can forward stdio over an SSH tunnel to local Cursor—macOS-side environment consistency without exposing PATs on personal machines. For more MCP security and production practices, see the AGNTCon MCP deployment guide.

Method 3: Prebuilt binaries

Skip Docker by downloading a prebuilt package from GitHub Releases (available from v1.7.0 onward):

macOS / Linux install and PATH

# macOS ARM example
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 install

# PowerShell
Expand-Archive github-mcp-server_Windows_x86_64.zip -DestinationPath C:\Tools\github-mcp-server
# Add C:\Tools\github-mcp-server to system PATH

mcp.json config (stdio mode)

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

If PATH isn't set on Windows, use an absolute path: "command": "C:\\Tools\\github-mcp-server\\github-mcp-server.exe".

Binaries start fast and don't need a Docker daemon; the trade-off is manual upgrades—download a new Release and replace the file. Teams should document the pinned version (e.g. v1.7.0) and checksum so members don't run mismatched Server versions with inconsistent tool behavior.

Method 4: Build from source (advanced)

Build from the official repo when you need a custom branch, want to contribute a PR, or must audit every line of code. Requires Go 1.24+.

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

Use the binary the same way as Method 3—point command in mcp.json at your build output. In production, pin a release tag (e.g. v1.7.0) rather than tracking main.

Source builds suit two audiences: contributors opening PRs to github/github-mcp-server, and security teams that audit code and ship internal patches before distributing binaries. Without customization needs, Method 1 or 2 is enough—no Go toolchain required.

Connect to popular MCP hosts: Cursor, Claude Desktop, VS Code Copilot

JSON structure differs slightly across clients, but each declares an mcpServers entry. Below is the most common pattern (Docker PAT mode; for remote hosting, swap command/args for url + headers).

Cursor

Global config: ~/.cursor/mcp.json; project-level: .cursor/mcp.json. Project config fits repos that need GitHub MCP only—e.g. an open-source contribution project with a different PAT than your side projects. After restart, ask in chat to "list my GitHub repositories." If the Agent replies it has no GitHub tools, MCP didn't load—check the MCP panel logs.

Claude Desktop

Edit claude_desktop_config.json for your platform. Structure matches Cursor—the top-level key is also 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"
      }
    }
  }
}

Quit and reopen Claude Desktop after saving. On macOS, check MCP connection logs via the menu bar icon → Settings → Developer.

VS Code Copilot (Agent mode)

In VS Code 1.99+, Copilot Chat supports MCP. Open Command Palette → MCP: Add Server, or create .vscode/mcp.json in your workspace. Remote hosting config is identical to Cursor.

Not sure whether to use Cursor or Claude Code? See our AI coding tools comparison before picking an MCP host.

Seven-step acceptance checklist and troubleshooting

After configuration, work through this checklist to confirm your Agent can actually call GitHub tools.

• Step 1: PAT created with repo scope (and read:org etc. as needed)
• Step 2: mcp.json JSON is valid (check with jq . or an online validator)
• Step 3: Client was fully restarted (not just the window closed)
• Step 4: MCP panel shows github as Connected / green
• Step 5: "List my GitHub repositories" in chat returns real repo names
• Step 6: Read a file from a private repo to confirm PAT permissions
• Step 7: Client logs show no 401 Unauthorized or connection refused

Common issues

Old assumption: "Install an npm package and you're connected to GitHub."
Since April 2025 the official path is github/github-mcp-server; for remote hosting use api.githubcopilot.com/mcp/—don't search for server-github anymore.

Frequently Asked Questions

Should I use remote hosting or local Docker deployment?

For personal experimentation or quick team validation, start with GitHub remote hosting (https://api.githubcopilot.com/mcp/)—same config on every platform, no process to maintain. Choose local Docker (ghcr.io/github/github-mcp-server) when you need offline operation, a custom tool set, or strict credential isolation.

Can I still use npm's @modelcontextprotocol/server-github?

No. That npm package was deprecated in April 2025. Use the official GitHub repository github/github-mcp-server (latest v1.7.0).

What PAT scopes do I need?

Fine-grained or Classic PATs need at least repo (read/write repositories) and read:org (read organization info). Add scopes for Issues, Pull Requests, or Projects based on the tools your Agent will call.

Docker image pull fails on Windows—what should I do?

Confirm Docker Desktop is running with a healthy WSL2 backend; allocate enough memory under Settings → Resources; run docker login ghcr.io, then retry docker pull ghcr.io/github/github-mcp-server.

I edited mcp.json in Cursor but nothing changed—why?

Fully quit and restart Cursor after saving JSON; check for conflicts between ~/.cursor/mcp.json and project .cursor/mcp.json (project-level wins); open Settings → MCP to inspect connection status and error logs.

Conclusion

The official GitHub MCP Server deployment story is straightforward:

1. Fastest start — remote hosting at https://api.githubcopilot.com/mcp/ + PAT, one JSON config for every platform
2. Local control — Docker image ghcr.io/github/github-mcp-server, PAT or OAuth
3. No Docker — download a prebuilt binary from Releases, set PATH, done
4. Advanced customization — Go 1.24+ source build, pin a release tag for production

Start with remote hosting in Cursor and run through list repos → read file → look up Issue. Once PAT scopes are confirmed, decide whether to move to Docker or an isolated remote Mac environment.

For teams, version-control MCP config files (with PAT plaintext removed) and inject tokens via environment variables or a secrets manager—consistent with MCP secure deployment best practices. Windows developers who also need iOS builds and Agent workflows can rent a Macstripe cloud Mac by the day—SSH ready in about five minutes, with MCP Server, Xcode, and Fastlane on the same macOS node while your laptop stays a remote terminal. That's far more stable than mixing Docker and remote Xcode plugins on a personal machine.

Further Reading

• AGNTCon MCPCon Europe 2026 MCP Deployment Guide →
• Claude Code vs Cursor vs Codex: AI Coding Tools Comparison 2026 →
• Slow iOS CI on GitHub Actions? Cloud Mac fixes it →