How to Integrate the GitHub MCP Server with Claude Desktop: Complete Setup Guide

To integrate the GitHub MCP Server with Claude Desktop, configure a Docker-based connector in your claude_desktop_config.json file with your GitHub Personal Access Token, then restart Claude Desktop to activate the integration.

The GitHub MCP (Model Context Protocol) Server is an open-source Go service that translates MCP method calls into GitHub API requests. When you integrate this MCP server with Claude Desktop, you enable Claude to interact directly with GitHub repositories, issues, pull requests, and actions through a local Docker container or binary.

Understanding the MCP Server Architecture

Before you integrate the MCP server with Claude Desktop, it helps to understand how the components interact. The server acts as a bridge between Claude's natural language interface and GitHub's REST and GraphQL APIs.

Core Components

Component	Responsibility	Key Source
Server entry-point (RunStdioServer)	Creates context, parses configuration, builds tool inventory, and starts the MCP server with logging and token scope resolution.	internal/ghmcp/server.go#L21-L67
GitHub client factory (createGitHubClients)	Builds REST, GraphQL, raw-content, and repo-access cache clients using the provided token and transport wrappers.	internal/ghmcp/server.go#L39-L102
Tool inventory (github.NewInventory)	Registers every supported tool (issues, pull-requests, actions, etc.) that drives which RPC methods are exposed.	pkg/github/server.go#L31-L54
Middleware (addUserAgentsMiddleware)	Injects a custom User-Agent header identifying the MCP version and Claude client for telemetry and rate-limit handling.	internal/ghmcp/server.go#L37-L70

Architecture Flow

Claude Desktop (Connector) ──► HTTP/stdio request (MCP) ──► github-mcp-server (Go)
   │                                                         │
   │   ←─ JSON RPC response (tool results) ←─────────────────│
   │
   └──→ GitHub APIs (REST/GraphQL) via client factory (Bearer token)

The UserAgentTransport in [pkg/http/transport/user_agent.go](https://github.com/github/github-mcp-server/blob/main/pkg/http/transport/user_agent.go) ensures GitHub sees requests as coming from "github-mcp-server/… (Claude-Desktop/… )".

Prerequisites for Claude Desktop Integration

To successfully integrate the MCP server with Claude Desktop, you need:

1. Claude Desktop installed (latest version recommended)
2. Docker installed and running (for containerized deployment)
3. A GitHub Personal Access Token (PAT) with appropriate scopes:
   • repo scope for private repositories
   • read:org for organization-level operations (optional)
   • workflow for Actions-related tools (optional)

Step-by-Step Integration Guide

Step 1: Create a GitHub Personal Access Token

Generate a classic PAT or fine-grained token with the repo scope. Store it securely in your environment:

export GITHUB_PAT="ghp_your_token_here"

Step 2: Configure Claude Desktop

Edit your Claude Desktop configuration file at the appropriate path for your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following mcpServers configuration block:

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

Replace YOUR_GITHUB_PAT with your actual token, or use "${GITHUB_PAT}" if your shell substitutes environment variables.

Step 3: Alternative CLI-Based Configuration

Instead of manually editing JSON, use the Claude CLI to add the server:

# Using an environment variable stored in .env

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=$(grep GITHUB_PAT .env | cut -d '=' -f2) \
  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

This command writes the same configuration block to your user-scoped config file automatically.

Step 4: Verify the Integration

Restart Claude Desktop to load the new connector. Then validate the setup using the Claude CLI:

# List all configured MCP servers

claude mcp list

# Show details of the GitHub MCP server

claude mcp get github

If the integration is successful, claude mcp get github returns JSON metadata including the server version, enabled toolsets, and feature flags.

How the Integration Works Under the Hood

When you integrate the MCP server with Claude Desktop, several key mechanisms ensure secure and efficient communication:

1. Middleware Injection: The addUserAgentsMiddleware function in internal/ghmcp/server.go intercepts outgoing requests and injects a custom User-Agent header that identifies the request as originating from Claude Desktop.

2. Transport Layer: The UserAgentTransport struct in pkg/http/transport/user_agent.go wraps the standard HTTP transport to ensure consistent header injection across REST, GraphQL, and raw content clients.

3. Client Factory: The createGitHubClients function initializes multiple GitHub API clients (REST, GraphQL, and cache) using the Bearer token authentication transport, ensuring all API calls are properly authenticated.

Troubleshooting Common Issues

If you encounter problems when you integrate the MCP server with Claude Desktop:

• Check the logs: Claude Desktop logs are located at ~/Library/Logs/Claude/ (macOS), %APPDATA%\Claude\logs\ (Windows), or ~/.config/Claude/logs/ (Linux).
• Verify Docker is running: The containerized server requires an active Docker daemon.
• Validate token scopes: Ensure your PAT has the repo scope for private repositories.
• Check JSON syntax: Use a JSON validator to ensure your claude_desktop_config.json is properly formatted.

Summary

• Integrate the MCP server with Claude Desktop by adding a Docker-based connector configuration to your claude_desktop_config.json file.
• The server architecture uses RunStdioServer in internal/ghmcp/server.go to bootstrap the connection and createGitHubClients to handle GitHub API authentication.
• You can configure the integration manually via JSON or use the claude mcp add CLI command to automate the setup.
• Verify the integration using claude mcp list and claude mcp get github to ensure the server is properly registered and accessible.

Frequently Asked Questions

What is the GitHub MCP Server?

The GitHub MCP Server is an open-source Go-based service hosted at github/github-mcp-server that implements the Model Context Protocol (MCP). It translates MCP method calls from AI assistants like Claude into GitHub API requests, enabling natural language interaction with repositories, issues, pull requests, and GitHub Actions.

Do I need Docker to run the GitHub MCP Server with Claude Desktop?

While Docker is the recommended and most straightforward method to integrate the MCP server with Claude Desktop, it is not strictly required. The server can also run as a compiled binary. However, the Docker approach is preferred because it handles dependencies automatically and is the primary method documented in docs/installation-guides/install-claude.md.

Where is the Claude Desktop configuration file located?

The location of claude_desktop_config.json depends on your operating system. On macOS, it is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, find it at %APPDATA%\Claude\claude_desktop_config.json. On Linux, the path is ~/.config/Claude/claude_desktop_config.json.

How do I verify that the GitHub MCP Server is working correctly?

After you integrate the MCP server with Claude Desktop, verify the installation by running claude mcp list in your terminal, which should display github in the list of configured servers. Then run claude mcp get github to retrieve detailed metadata about the server, including its version, enabled toolsets, and connection status. If these commands return valid JSON data, your integration is functioning correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}