How to Deploy GitHub MCP Server: A Cross-Platform Guide for Windows, Linux, and macOS

GitHub MCP Server is the officially maintained Model Context Protocol server from GitHub. It lets AI hosts such as Cursor, Claude Desktop, and VS Code Copilot call the GitHub REST / GraphQL APIs through standardized tools—browse repositories, read issues, open pull requests, search code—without repeatedly pasting gh command output into chat.

This article follows a choose your approach → set up the environment → connect your IDE flow. It covers installation paths for Windows, Linux, and macOS, with copy-paste configuration snippets and a troubleshooting checklist.

As of April 2025, the early community npm package @modelcontextprotocol/server-github is deprecated. The only officially supported local image is now ghcr.io/github/github-mcp-server, and the hosted remote endpoint is https://api.githubcopilot.com/mcp/.

How to Choose a Deployment Method

Before installing anything, use the table below to decide which path fits your setup:

All three methods use the same authentication model: configure a Personal Access Token (PAT), or use OAuth browser login in local Docker / binary mode (the token stays in memory only and is not written to disk).

Common Prerequisites

Whichever path you choose, complete these four steps first:

1. Create a GitHub PAT
   Open the Fine-grained PAT creation page and select permissions for the tools you need. Read-only repository browsing usually requires Contents: Read and Metadata: Read; add write permissions if you need to create PRs or issues.

2. Confirm host version
   - Cursor: v0.48.0+ required for remote Streamable HTTP
   - Claude Desktop / VS Code: refer to each product's MCP documentation

3. (Local Docker) Install and start Docker
   - Windows / macOS: Docker Desktop
   - Linux: Docker Engine + add your user to the docker group

4. Pre-pull the image (optional but recommended)

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

If the pull fails with unauthorized, run docker logout ghcr.io and retry—stale ghcr login sessions are a common cause.

Method 1: Hosted Remote (Easiest)

GitHub provides a hosted MCP endpoint at https://api.githubcopilot.com/mcp/—no Docker required on your machine. This suits Linux servers, lightweight Windows setups, or environments where company policy blocks containers.

Cursor Configuration Example

Edit the global config at ~/.cursor/mcp.json (on Windows: %USERPROFILE%\.cursor\mcp.json):

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

Replace YOUR_GITHUB_PAT with your real token, save, and fully restart Cursor. You should see a green online indicator under Settings → Tools & Integrations → MCP Tools; in Composer, ask something like "list my GitHub repositories" to verify.

Notes

• Remote mode currently relies primarily on PAT authentication; OAuth support varies by host and is still maturing.
• Corporate proxies / firewalls must allow outbound HTTPS to api.githubcopilot.com.
• Never commit PATs to version control; if you use project-level .cursor/mcp.json, add it to .gitignore.

Method 2: Local Docker Deployment (Officially Recommended)

The Docker approach communicates with the host over stdio: the host runs docker run -i ..., and the container process reads and writes standard input/output. This is also the default command behind one-click install buttons in Claude Desktop, Windsurf, and Cursor.

macOS Installation Steps

1. Install Docker Desktop for Mac (choose the ARM64 build on Apple Silicon).
2. Confirm the menu bar whale icon shows Running.
3. Verify in a terminal:

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

4. Write to ~/.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 Installation Steps

1. Install Docker Engine for your distribution (Ubuntu example: sudo apt install docker.io).
2. Add your user to the docker group to avoid sudo on every run:

sudo usermod -aG docker "$USER"
newgrp docker

3. Ensure the Docker daemon is running: sudo systemctl enable --now docker.
4. MCP configuration is identical to macOS—same ~/.cursor/mcp.json path.

On a headless Linux server, if you prefer not to store the PAT in plain text in config, inject it via environment variable instead:

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

Then reference the same variable name in the env block of mcp.json (some hosts support ${env:GITHUB_PERSONAL_ACCESS_TOKEN} syntax—check your host's documentation).

Windows Installation Steps

1. Install Docker Desktop for Windows.
   - Prefer the WSL 2 backend (Settings → General → Use WSL 2 based engine).
2. Confirm the Docker Desktop tray icon shows a running state.
3. Config file path: %USERPROFILE%\.cursor\mcp.json.
4. JSON content matches macOS; command remains docker (Docker Desktop adds the CLI to PATH).

Common Windows pitfall: docker may work inside WSL, but Windows-hosted Cursor reads the Windows-side mcp.json—do not mix configs across both. If Cursor runs on Windows and your project lives in WSL, configure MCP in the Windows user profile first.

OAuth Login (No Manual PAT)

The official image ships with built-in OAuth app credentials. In Docker mode, map the callback port to localhost:

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

On first connect, a browser opens for GitHub sign-in; the token is kept in memory and expires when the container exits. For headless servers, see the official device code fallback flow.

Method 3: Go Source Build (No Docker)

Best when Docker is unavailable, or when you need to trim the toolset (expose only a subset of API capabilities).

Shared Steps Across All Platforms

Prerequisite: Install 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

You can name the binary anything; the examples below use ./github-mcp-server.

Start with PAT (stdio mode):

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

Connect the local binary to Cursor:

{
  "mcpServers": {
    "github": {
      "command": "/absolute/path/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

To upgrade, run git pull && go build again—no need to wait for a Docker image release.

Connecting Other IDEs and CLIs

Config key names vary by host, but the core Docker command is the same:

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

• Claude Desktop: the mcpServers block in claude_desktop_config.json mirrors Cursor's structure.
• VS Code Copilot: supports remote + local; Docker image is recommended for local setups.
• Claude Code CLI: favors a lightweight binary to reduce container overhead.

See the official repository's docs/installation-guides/ directory for full per-host examples.

Security and Operations

1. Least-privilege PAT: grant only the permissions your toolset needs; rotate regularly.
2. Config file permissions: chmod 600 ~/.cursor/mcp.json (Linux / macOS).
3. Read-only mode: startup flags can enable read-only to prevent accidental repo changes by AI.
4. GitHub Enterprise Server: you must create your own OAuth App / GitHub App—github.com default OAuth credentials do not apply. See official docs/oauth-login.md.

Platform-Specific Notes

Paths and Environment Variables

~/.cursor/mcp.json

Global MCP config on macOS and Linux; on Windows, use %USERPROFILE%\.cursor\mcp.json.

GITHUB_PERSONAL_ACCESS_TOKEN

Environment variable for PAT in Docker / binary mode; when set, it takes priority over OAuth.

GITHUB_OAUTH_CALLBACK_PORT

OAuth browser callback listen port; in Docker setups this is typically 8085.

Shortcuts and Conventions

In Cursor Composer, press Cmd+Shift+P (Windows: Ctrl+Shift+P) to open the command palette and search for MCP settings. Some users once relied on npx @modelcontextprotocol/server-github as a one-liner to start the server—that approach is deprecated; use the Docker or remote endpoint methods in this article instead.

In production, store your PAT in environment variables or a secrets manager—never in project files tracked by git.

Verification Checklist (Before Going Live)

1. Green dot in the MCP panel
2. Tool list shows items prefixed with github_*
3. A read-only call (e.g. list repositories) succeeds

Log Locations

In Cursor, open Help → Toggle Developer Tools → Console and filter for MCP. Claude Desktop log paths vary by platform; the official troubleshooting section has the full list.

Troubleshooting Quick Reference

Quick local check: run the Docker command manually in a terminal and watch stderr for immediate errors; compare with the MCP startup command in IDE logs.

Summary

• Fastest path: remote https://api.githubcopilot.com/mcp/ + PAT; on Cursor v0.48+, configure url directly.
• Stable and reproducible: same docker run -i --rm ... ghcr.io/github/github-mcp-server on all three platforms.
• Lightweight or customized: go build a binary and connect via stdio.

Once deployed, the real time savings come from using natural language in AI chat to work with GitHub—for example, "summarize the 5 most recent open issues in the kvmkit repo." If you are also building CI/CD pipelines or need 24/7 cloud Mac build nodes, you can plan MCP-assisted development and automated releases as part of the same toolchain.

FAQ