How to Set Up GitHub MCP Server with Claude Desktop

What You’ll Get

After this setup, you’ll ask Claude to handle GitHub tasks without leaving your conversation:

• “List my recent GitHub notifications and prioritize the urgent ones”
• “Show me open PRs in the cybernauten repo that haven’t been reviewed in 3 days”
• “Create an issue in my repo for tracking this bug we just discussed”

No browser tabs. No context switching. Claude talks directly to GitHub’s API through the GitHub MCP Server.

We run this server in our daily workflow at Cybernauten for managing the cybernauten repository. The PR automation alone saves us the mental overhead of constantly checking GitHub in the browser. Here’s what we’ve learned after weeks of daily use.

Prerequisites

You need four things:

1. Docker Desktop installed and running

   • macOS/Windows: Docker Desktop
   • Linux: Docker CE (sudo apt install docker.io on Ubuntu)
   • Minimum version: Docker 24.0 (check with docker --version)

2. GitHub Personal Access Token (PAT)

   • Classic or fine-grained token
   • Minimum scopes: repo, read:org, read:packages
   • We’ll create this in the next section

3. Claude Desktop installed

   • Download from claude.ai
   • Important: If you installed Claude from Microsoft Store (Windows), you’ll hit sandbox errors. Uninstall and download the standard version from the website instead.

4. Config file access

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • You can also access this via Claude → Settings → Developers → Edit Config

Platform notes: M1/M2 Macs are fully supported via Docker’s ARM64 image. Windows users need WSL2 enabled (Settings → App features → Windows Subsystem for Linux).

Method 1: Docker (Recommended)

This is the only method that works with Claude Desktop. The remote OAuth-based server you might see mentioned elsewhere doesn’t work with Claude Desktop — it’s for VS Code only.

Step 1: Create a GitHub Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens.

Click “Generate new token (classic)” or “Fine-grained tokens” (recommended).

Name: “Claude Desktop MCP” Expiration: 90 days (we rotate quarterly for security)

Select these scopes:

• repo — full repository access (read/write)
• read:org — read organization team info
• read:packages — for Docker image operations

Click Generate token. Copy the token immediately — GitHub only shows it once.

Security reminder: This token has broad access. Store it securely. Don’t commit it to git. We’ll cover token rotation in the Security section.

Step 2: Verify Docker is Running

Before editing config files, make sure Docker is active.

macOS:

# Open Docker Desktop from Applications
# Wait for "Docker Desktop is running" notification

# Verify in terminal
docker ps

Windows:

# Start Docker Desktop from system tray
# Wait for status notification

# Verify in PowerShell
docker ps

Linux:

# Start Docker daemon
sudo systemctl start docker

# Verify
docker ps

If docker ps returns an error, Docker isn’t running. Fix that before continuing.

Step 3: Pull the GitHub MCP Server Image

Test that Docker can reach GitHub’s container registry:

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

You should see:

Pulling from github/github-mcp-server
latest: Pulling from github/github-mcp-server
...
Status: Downloaded newer image for ghcr.io/github/github-mcp-server:latest

If this fails, check your internet connection or corporate firewall settings.

Step 4: Edit Your Claude Desktop Config

Open the config file in a text editor:

macOS:

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Add this configuration block (replace ghp_XXXXXXXXXXXXXXXXXXX with your actual token):

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_XXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

JSON syntax check:

• Use double quotes, not single quotes
• No trailing commas after the last field
• If you have other MCP servers configured, add a comma after the previous server’s closing brace

Save the file.

Step 5: Restart Claude Desktop

Close Claude completely. Don’t just close the window — fully quit the app:

• macOS: Cmd+Q or Claude → Quit Claude
• Windows: Right-click system tray icon → Quit
• Linux: Close all windows and kill the process if needed

Wait a few seconds, then reopen Claude Desktop.

Step 6: Verify Connection

Open Claude Desktop and check Settings → Developers → Model Context Protocol.

You should see:

github — Connected

If you see “Failed” or “Disconnected” instead, jump to the Troubleshooting section.

Method 2: Remote Server (VS Code Only)

The GitHub MCP Server has a remote OAuth-based endpoint at https://api.githubcopilot.com/mcp/, but this doesn’t work with Claude Desktop.

If you use VS Code with the Claude extension:

• You can use the remote server URL
• It handles OAuth automatically (no PAT needed)
• Requires VS Code 1.101+ or compatible IDE

For everyone else using Claude Desktop, stick with Method 1 (Docker).

The OAuth limitation exists because Claude Desktop doesn’t implement OAuth redirect handling. GitHub is working on expanding OAuth support, but as of March 2026, PAT is required for Claude Desktop.

Testing Your Setup

Now that the server is connected, test it with real prompts.

Test 1: List Recent Notifications

In Claude, type:

What are my recent GitHub notifications?

Claude should respond with a list of your unread and participating notifications, showing repository names and issue/PR titles.

If Claude says it doesn’t have GitHub access, the server isn’t connected. Revisit Step 6.

Test 2: Show Open Pull Requests

Show me the 5 most recent pull requests in my repositories

Expected response: A list of PRs with titles, repository names, and status (open/draft/merged).

If Claude says “no open PRs” when you know there are some, check your PAT scopes. The token might not have repo access.

Test 3: Create an Issue (Write Access Test)

Pick a test repository you own:

Create an issue in the [your-username]/[repo-name] repository with title "Test Issue from Claude" and description "This tests the GitHub MCP Server setup"

Claude should confirm issue creation and provide a link to the new issue on GitHub.

If Claude responds with “I don’t have permission to create issues,” your PAT token lacks write access. Regenerate the token with repo scope (not just read-only).

Test 4: Check Available Tools

Ask Claude:

What GitHub tools do I have access to through the MCP server?

Claude will list available tools based on your token’s scopes. If the list is very short (only read operations), your PAT might be missing scopes.

As of January 2026, the GitHub MCP Server automatically detects your token’s scopes and hides tools you don’t have permission for. This prevents error spam when you accidentally try to use a tool your token can’t access.

Common Issues & Troubleshooting

”docker: command not found”

Docker isn’t installed or isn’t in your PATH.

Solution:

• macOS: Install Docker Desktop
• Windows: Install Docker Desktop for Windows
• Linux: sudo apt install docker.io (Ubuntu) or equivalent

Verify installation: docker --version should return a version number (24.0 or higher).

”Cannot connect to Docker daemon”

Docker is installed but not running.

Solution:

• macOS: Open Applications → Docker, wait for “Docker is running” notification
• Windows: Click Docker Desktop icon in system tray, wait for status message
• Linux: sudo systemctl start docker

Verify: docker ps should succeed without errors.

”MCP server ‘github’ failed to connect”

This is the most common issue. Multiple causes.

Checklist:

1. Verify JSON syntax

   • Open config in VS Code or a JSON validator
   • Look for trailing commas, single quotes, or missing brackets
   • Common mistake: "GITHUB_PERSONAL_ACCESS_TOKEN": 'token' — use double quotes

2. Check token validity

   • Go to GitHub Settings → Personal access tokens
   • Confirm the token hasn’t expired
   • Token should start with ghp_ (classic) or github_pat_ (fine-grained)

3. Test Docker image pull

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

   If this fails, Docker can’t reach GitHub Container Registry. Check internet/firewall.

4. Restart everything

   • Close Claude completely (Cmd+Q or right-click → Quit)
   • Close Docker Desktop
   • Restart Docker Desktop first, wait 10 seconds
   • Restart Claude Desktop

5. Check file path

   • macOS: Must be ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: Must be %APPDATA%\Claude\claude_desktop_config.json
   • Don’t edit a copy in the wrong location

”GitHub API rate limit exceeded”

You’ve made too many API calls in the past hour. GitHub limits authenticated requests to 5,000/hour.

Solution:

• Wait ~1 hour for the limit to reset
• Optimize queries: use filters instead of listing everything (--state:open, --repo:specific-repo)
• Check current usage: Ask Claude “How many GitHub API calls have I made?”

Cybernauten note: We’ve never hit rate limits in daily use. You’d need to be doing very large batch operations (listing thousands of items) to hit 5,000 requests/hour.

”Docker Desktop is not running” (but it is)

Windows-specific issue with WSL2. Docker Desktop reports as running, but MCP gateway can’t connect.

Workaround:

• Open PowerShell as admin
• Run docker ps to force Docker daemon to fully initialize
• Then start Claude Desktop

Alternative: Run Claude Desktop on native Windows (not inside WSL2), or use Claude Code CLI instead of Claude Desktop.

This is a known issue as of March 2026. Docker and Anthropic are working on a fix.

”Tools not loading” or empty tools list

Your token lacks necessary scopes, or the server isn’t detecting them.

Solution:

1. Ask Claude: “What tools do I have available in the GitHub MCP Server?”

   • If the list is very short (only a few read operations), scopes are missing

2. Check your PAT scopes at GitHub Settings → Personal access tokens

   • Confirm repo, read:org, read:packages are checked
   • For fine-grained tokens, confirm repositories are selected

3. If unclear, regenerate the token with known scopes:

   • Create new token at GitHub
   • Select repo, read:org, read:packages
   • Copy the new token
   • Update GITHUB_PERSONAL_ACCESS_TOKEN in your config
   • Restart Claude

What You Can Do Now

Once the GitHub MCP Server is running, here are practical use cases we rely on at Cybernauten:

1. Daily PR Review Triage

Instead of manually checking GitHub every morning:

Summarize all open pull requests in the cybernauten repository.
Highlight any that have been open for more than 3 days without review.

Claude fetches PRs, calculates how long each has been open, and flags old ones for attention. We use this every morning to decide where to focus code review time.

2. Notification Management

GitHub notifications pile up fast. This prompt clears the noise:

Mark all notifications older than 7 days as read,
and list the important ones still pending.

Claude batch-processes old notifications and surfaces only what matters. We run this weekly.

3. Automated Security Response

When Dependabot finds vulnerabilities:

Check for critical Dependabot alerts and create an issue
for each one with a template for our team to fix.

Claude fetches security alerts, filters by severity, and creates structured issues. This turns a manual 20-minute task into a single prompt.

4. Issue Triage and Labeling

For repositories with many issues:

List all open issues labeled "bug" that haven't been updated in 30 days.
Add a "stale" label to each.

Claude automates housekeeping that would otherwise require clicking through dozens of issues.

5. Workflow Status Checks

When you’re waiting on CI/CD:

Show me the status of GitHub Actions runs for the last 3 commits in main.

Claude reports which workflows passed, which failed, and which are still running. No need to open the Actions tab.

---

For a complete list of what the GitHub MCP Server can do, see our GitHub MCP Server profile.

If you want to add more MCP servers to Claude Desktop, check out our guide to the best MCP servers for developers.

Security Notes

Token Management Best Practices

1. Never commit PAT to git Even private repos get breached. If you need to share config files, use environment variable substitution instead of hardcoding tokens.

2. Rotate tokens every 90 days Set a calendar reminder to regenerate the PAT quarterly:

   • Generate new token at GitHub
   • Update config file
   • Restart Claude
   • Delete old token from GitHub settings

3. Use fine-grained PATs over classic tokens Fine-grained tokens let you:

   • Restrict access to specific repositories
   • Set read-only permissions (no PR merge, no issue creation)
   • Use shorter expiration periods (30 days default)

4. Monitor token usage Check GitHub’s audit log for unexpected activity:

   • Go to GitHub Settings → Security & analysis → Token usage
   • Look for API calls from unfamiliar IPs

At Cybernauten, we use a fine-grained PAT restricted to the cybernauten/repo repository. We don’t use classic PATs (which grant access to all repos) for daily work.

Known Security Vulnerability (May 2025)

A security researcher found that attackers can exploit MCP by creating malicious GitHub issues containing prompt injection payloads. If you ask Claude to “summarize recent issues,” the attacker’s payload could trick Claude into executing unauthorized actions.

Mitigation:

• Use read-only tokens for daily queries (no repo write access)
• Restrict tokens to specific repositories (fine-grained PATs)
• Review AI-generated PR/issue actions carefully before confirming

See Invariant Labs’ writeup for technical details.

This vulnerability is inherent to LLM-driven tools that process untrusted text. No patch exists yet. Use the mitigation strategies above.

Advanced: Environment Variable Substitution

If you share your config file with team members (via git or documentation), hardcoding the PAT is risky.

Instead, reference an environment variable:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

Then set the environment variable before launching Claude:

macOS/Linux:

export GITHUB_PAT="ghp_XXXXXXXXXXXXXXXXXXX"
# Launch Claude Desktop from terminal
open -a "Claude"

Windows:

$env:GITHUB_PAT = "ghp_XXXXXXXXXXXXXXXXXXX"
# Launch Claude Desktop
Start-Process "Claude"

This keeps tokens out of version control. Add GITHUB_PAT to your .bashrc or .zshrc for persistence.

What’s Next

Now that GitHub is connected to Claude, consider adding other MCP servers:

• Filesystem MCP — let Claude read/write local files
• Brave Search MCP — web search inside Claude
• PostgreSQL MCP — query databases directly

See our MCP Server Directory for a curated list of production-ready servers.

If you’re building an AI-powered workflow, our Agentic Infrastructure Stack 2026 guide covers how MCP servers fit into larger systems.

---

Got stuck? Open an issue at github.com/github/github-mcp-server or reach out on GitHub Discussions. The maintainer team is responsive.