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

> Integrate the GitHub MCP Server with Claude Desktop easily. Follow our setup guide to configure your Docker connector and activate the integration for seamless workflow.

- Repository: [GitHub/github-mcp-server](https://github.com/github/github-mcp-server)
- Tags: how-to-guide
- Published: 2026-02-16

---

**To integrate the GitHub MCP Server with Claude Desktop, configure a Docker-based connector in your [`claude_desktop_config.json`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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)](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:

```bash
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:

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

```

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:

```bash

# 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:

```bash

# 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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/claude_desktop_config.json) file.
- The server architecture uses `RunStdioServer` in [`internal/ghmcp/server.go`](https://github.com/github/github-mcp-server/blob/main/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`](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md).

### Where is the Claude Desktop configuration file located?

The location of [`claude_desktop_config.json`](https://github.com/github/github-mcp-server/blob/main/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.