github-featured/github--github-mcp-server

Files

T

Sam Morrow fab5fc5ff2 docs: lead local/stdio install with OAuth login (#2776 )

* docs: lead local/stdio install with OAuth login

Surface OAuth 2.1 login as a first-class option above the Personal Access
Token in the README install section and in every local-capable installation
guide, each in that client's own config syntax, linking to the dedicated
docs/oauth-login.md guide.

The github.com OAuth example needs no token; in Docker it publishes a fixed
callback port to loopback (-p 127.0.0.1:8085:8085). The PAT block is retained
below it and noted as taking precedence over OAuth.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(oauth): correct PKCE/client-secret explanation

The previous "How it works" text claimed PKCE removes the need for a client
secret. In practice GitHub requires the client secret at the token endpoint for
both OAuth Apps and GitHub Apps, and the implementation sends it alongside the
PKCE verifier (Manager.oauth2Config populates ClientSecret; flow.go exchanges
with VerifierOption). The secret is baked into the distributed binary and is not
truly confidential; PKCE is what actually secures the flow. Reword to reflect
this accurately.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: don't frame OAuth login as github.com-only

The intro line said "On github.com you can skip the token entirely", which
implied OAuth login only works on github.com. OAuth works on GitHub Enterprise
too — you just supply your own app credentials there. Reword to lead with OAuth
as the mechanism and scope the zero-config claim correctly: on github.com the
official image already includes the app credentials, so the user provides none.
Enterprise / bring-your-own-app is covered by the linked OAuth guide.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

2026-06-26 14:45:06 +02:00

4.3 KiB

Raw Permalink Blame History

Install GitHub MCP Server in Windsurf

Prerequisites

Windsurf IDE installed (latest version)
GitHub Personal Access Token with appropriate scopes
For local installation: Docker installed and running

Remote Server Setup (Recommended)

The remote GitHub MCP server is hosted by GitHub at https://api.githubcopilot.com/mcp/ and supports Streamable HTTP protocol. Windsurf currently supports PAT authentication only.

Streamable HTTP Configuration

Windsurf supports Streamable HTTP servers with a serverUrl field:

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

Local Server Setup

Docker Installation (Required)

Important: The npm package @modelcontextprotocol/server-github is no longer supported as of April 2025. Use the official Docker image ghcr.io/github/github-mcp-server instead.

Log in with OAuth instead of a token. On github.com the official image already includes the app credentials, so you provide none yourself — the server opens a browser login on first use and keeps the token in memory only. In Docker, publish a fixed callback port to loopback:

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

See Local Server OAuth Login for the native-binary flow (no fixed port), headless/device-code fallback, GitHub Enterprise, and bringing your own OAuth or GitHub App.

To authenticate with a Personal Access Token instead (it takes precedence over OAuth):

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

Installation Steps

Via Plugin Store

Open Windsurf and navigate to Cascade
Click the Plugins icon or hammer icon (🔨)
Search for "GitHub MCP Server"
Click Install and enter your PAT when prompted
Click Refresh (🔄)

Manual Configuration

Click the hammer icon (🔨) in Cascade
Click Configure to open ~/.codeium/windsurf/mcp_config.json
Add your chosen configuration from above
Save the file
Click Refresh (🔄) in the MCP toolbar

Configuration Details

File path: ~/.codeium/windsurf/mcp_config.json
Scope: Global configuration only (no per-project support)
Format: Must be valid JSON (use a linter to verify)

Verification

After installation:

Look for "1 available MCP server" in the MCP toolbar
Click the hammer icon to see available GitHub tools
Test with: "List my GitHub repositories"
Check for green dot next to the server name

Troubleshooting

Remote Server Issues

Authentication failures: Verify PAT has correct scopes and hasn't expired
Connection errors: Check firewall/proxy settings for HTTPS connections
Streamable HTTP not working: Ensure you're using the correct serverUrl field format

Local Server Issues

Docker errors: Ensure Docker Desktop is running
Image pull failures: Try docker logout ghcr.io then retry
Docker not found: Install Docker Desktop and ensure it's running

General Issues

Invalid JSON: Validate with jsonlint.com
Tools not appearing: Restart Windsurf completely
Check logs: ~/.codeium/windsurf/logs/

Important Notes

Official repository: github/github-mcp-server
Remote server URL: https://api.githubcopilot.com/mcp/
Docker image: ghcr.io/github/github-mcp-server (official and supported)
npm package: @modelcontextprotocol/server-github (deprecated as of April 2025 - no longer functional)
Windsurf limitations: No environment variable interpolation, global config only

4.3 KiB Raw Permalink Blame History