GitHub MCP Server for Windsurf: Setup & Config

What you can do with GitHub in Windsurf

Give agents GitHub-native repository context and issue, review, workflow, and security operations.

• Explore repositories, files, and commit history through an assistant.
• Triage issues and manage pull request workflows.
• Coordinate discussions, notifications, and team project work.

Before you start: GitHub in Windsurf

• Docker installed and running for local container execution
• An MCP-compatible host
• GitHub authentication and appropriate account permissions

The command uses the README's local PAT-based Docker example. The remote URL uses HTTP and supports OAuth where the host implements it, or PAT authentication. Grant only the permissions required for your tasks.

GitHub Windsurf configuration

1. Choose Windsurf configuration scope

   For GitHub MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add GitHub MCP Server to Windsurf

   Use the github-mcp-server entry below in mcpServers. Keep GitHub MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check GitHub MCP Server in Windsurf

   GitHub MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<your GitHub personal access token with appropriate permissions>"
      }
    }
  }
}

Troubleshooting GitHub in Windsurf

• Check docker and a running Docker engine on the machine running Windsurf's MCP integration for GitHub MCP Server; refresh MCP and inspect Cascade's tools.
• Check GITHUB_PERSONAL_ACCESS_TOKEN for GitHub MCP Server; do not bypass a Windsurf permission error with a broad administrator token.
• GitHub MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: OAuth support and configuration vary by MCP host.
• Known limitation: GitHub Enterprise Server cannot use the hosted remote service.
• Known limitation: Individual tool names are not stated in the supplied README excerpt.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions