GitHub MCP Server Setup Guide for Claude Code (2025)

The Complete Tutorial: Connect Claude Code to GitHub and automate repository management, issue tracking, pull requests, CI/CD workflows, and code security—all through natural language.

⚡ Quick Start (60 Seconds)

Just want to get started fast?

claude mcp add github --transport http https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

That's it! Now test it in Claude Code.

📖 Continue below for detailed setup, 90+ tools reference, and troubleshooting →

What is GitHub MCP Server?
Prerequisites
Installation Methods
Authentication Setup
Configuration for Claude Code
Available Toolsets (20 Categories)
Complete Tools Reference
Real-World Examples
Advanced Configuration
Troubleshooting Guide
Security Best Practices
FAQ

What is GitHub MCP Server?

The GitHub MCP Server is an official integration maintained by GitHub that enables AI assistants like Claude Code to interact with GitHub's platform through natural language commands. It's built on the Model Context Protocol (MCP), providing a standardized way for AI tools to perform GitHub operations.

Key Capabilities

| Category | What You Can Do | |----------|-----------------| | Repository Management | Create repos, manage branches, push files, view commits | | Issue Tracking | Create, update, search, and manage issues and sub-issues | | Pull Requests | Create PRs, request reviews, merge, manage branches | | CI/CD Automation | Monitor workflows, view run logs, manage Actions | | Code Security | Scan for vulnerabilities, manage Dependabot alerts | | Team Collaboration | Manage notifications, discussions, projects |

Why Use GitHub MCP with Claude Code?

90+ Tools: Access comprehensive GitHub functionality through conversation
Official Support: Maintained by GitHub with regular updates
Secure: OAuth and PAT authentication with granular permissions
Flexible: Remote (zero-install) or local deployment options

Prerequisites

Before starting, ensure you have:

| Requirement | Details | |-------------|---------| | Claude Code | Latest version with MCP support (Download) | | GitHub Account | With access to repositories you want to manage | | Personal Access Token | Or OAuth authentication for remote server | | Node.js | v18+ (for local npm installation) | | Docker | Optional, for containerized local server |

Installation Methods

Choose the method that best fits your needs:

| Method | Best For | Requires | |--------|----------|----------| | Remote Server | Quick setup, cloud-based | GitHub OAuth or PAT | | Local (npm) | Custom configuration, offline | Node.js, PAT | | Local (Docker) | Isolated environment, enterprise | Docker, PAT |

Method 1: Remote Server (Recommended)

The easiest way to get started—no local installation required. GitHub hosts the MCP server at https://api.githubcopilot.com/mcp/.

Step 1: Add Remote Server to Claude Code

claude mcp add github --transport http https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

Step 2: Verify Connection

claude mcp list

You should see github listed as an active server.

For GitHub Enterprise Cloud

If you use GitHub Enterprise Cloud with data residency:

claude mcp add github --transport http https://copilot-api.YOURSUBDOMAIN.ghe.com/mcp/ --header "Authorization: Bearer YOUR_TOKEN"

Method 2: Local Server with npm

For more control and customization, run the server locally.

Step 1: Generate Personal Access Token

Go to GitHub Settings → Developer settings → Personal access tokens
Click "Generate new token (classic)"
Select these scopes:
- repo - Full control of private repositories
- read:org - Read org and team membership
- read:packages - Read packages (for Docker image)
- read:user - Read user profile data
Copy and save the token securely

Step 2: Add to Claude Code

Windows (PowerShell):

claude mcp add github --transport stdio -- cmd /c npx -y @anthropic-ai/github-mcp-server

macOS/Linux:

claude mcp add github --transport stdio -- npx -y @anthropic-ai/github-mcp-server

Step 3: Set Environment Variable

Add your token to the configuration:

claude mcp add github --transport stdio --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxx -- npx -y @anthropic-ai/github-mcp-server

Or set it globally in your shell profile:

Windows (PowerShell profile):

$env:GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxxxxxxxxxxx"

macOS/Linux (.bashrc or .zshrc):

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxx"

Method 3: Local Server with Docker

For isolated, containerized deployment:

Step 1: Pull the Docker Image

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

Step 2: Configure Claude Code

Create or edit your MCP configuration file:

Configuration file locations:

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

Add this configuration:

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

Authentication Setup

Personal Access Token (PAT)

The most common authentication method:

Navigate to GitHub Settings
- Go to github.com/settings/tokens
Create New Token
- Click "Generate new token (classic)"
- Give it a descriptive name: Claude Code MCP Integration
Select Required Scopes

| Scope | Purpose | Required? | |-------|---------|-----------| | repo | Repository access (read/write) | Yes | | read:org | Organization membership | Yes | | read:packages | Docker image access | Yes | | read:user | User profile data | Recommended | | workflow | GitHub Actions management | If using Actions | | gist | Gist operations | If using Gists |

Set Expiration
- Choose 90 days or custom expiration
- Set a reminder to rotate before expiration

Fine-Grained Personal Access Token (Recommended)

For enhanced security with granular permissions:

Go to github.com/settings/tokens?type=beta
Click "Generate new token"
Select specific repositories or "All repositories"
Choose only the permissions you need:
- Contents: Read and write
- Issues: Read and write
- Pull requests: Read and write
- Metadata: Read-only

Configuration for Claude Code

Using the CLI (Recommended)

# Add with environment variable
claude mcp add github --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  -- npx -y @anthropic-ai/github-mcp-server

# Verify configuration
claude mcp get github

# Check status in Claude Code
/mcp

Using Configuration Files

Project-Specific Configuration (.mcp.json)

Create .mcp.json in your project root (can be committed to version control):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

User-Level Configuration (~/.claude.json)

For personal settings across all projects:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Windows-Specific Configuration

Windows requires the cmd /c wrapper for npx commands:

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@anthropic-ai/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Available Toolsets (20 Categories)

The GitHub MCP Server organizes 90+ tools into 20 toolsets. Enable only what you need for optimal performance.

Default Toolsets

These are enabled automatically if you don't specify any configuration:

| Toolset | Description | |---------|-------------| | context | Current user and GitHub context information | | repos | Repository operations (files, branches, commits) | | issues | Issue creation, updates, and management | | pull_requests | PR creation, reviews, and merging | | users | User profile and information tools |

All Available Toolsets

| Toolset | Description | Tools | |---------|-------------|-------| | context | User and GitHub context | 2 | | repos | Repository management | 16 | | git | Low-level Git operations | 5 | | issues | Issue tracking | 9 | | pull_requests | Pull request operations | 10 | | users | User information | 3 | | orgs | Organization management | 4 | | actions | CI/CD workflows | 8 | | code_security | Code scanning alerts | 4 | | secret_protection | Secret scanning | 3 | | dependabot | Dependency updates | 3 | | notifications | Notification management | 4 | | discussions | GitHub Discussions | 5 | | gists | Gist operations | 4 | | security_advisories | Security advisories | 3 | | projects | GitHub Projects | 6 | | stargazers | Star management | 2 | | labels | Label management | 4 | | experiments | Experimental features | Varies | | dynamic | Runtime tool discovery | 3 |

Configuring Toolsets

Via CLI:

claude mcp add github --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  --env GITHUB_TOOLSETS=repos,issues,pull_requests,actions \
  -- npx -y @anthropic-ai/github-mcp-server

Via Configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server", "--toolsets", "repos,issues,pull_requests"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Complete Tools Reference

Repository Tools (`repos` toolset)

| Tool | Description | |------|-------------| | get_file_contents | Get contents of a file or directory | | create_or_update_file | Create or update a single file | | push_files | Push multiple files in a single commit | | delete_file | Delete a file from repository | | create_repository | Create a new repository | | fork_repository | Fork a repository to your account | | create_branch | Create a new branch | | list_branches | List all branches | | get_commit | Get details for a specific commit | | list_commits | List commits on a branch | | list_tags | List git tags | | get_tag | Get details about a tag | | list_releases | List repository releases | | get_latest_release | Get the latest release | | get_release_by_tag | Get release by tag name | | list_starred_repositories | List your starred repos |

Issue Tools (`issues` toolset)

| Tool | Description | |------|-------------| | issue_read | Get issue details, comments, sub-issues, labels | | issue_write | Create or update issues | | list_issues | List issues with pagination | | search_issues | Search issues using GitHub syntax | | add_issue_comment | Add comment to issue or PR | | sub_issue_write | Add, remove, or reprioritize sub-issues | | list_issue_types | List supported issue types | | assign_copilot_to_issue | Assign Copilot to an issue | | assign_coding_agent_prompt | Assign GitHub Coding Agent |

Pull Request Tools (`pull_requests` toolset)

| Tool | Description | |------|-------------| | pull_request_read | Get PR details and diff | | create_pull_request | Create a new pull request | | update_pull_request | Update PR title, body, state | | list_pull_requests | List PRs with filters | | search_pull_requests | Search PRs using GitHub syntax | | merge_pull_request | Merge a pull request | | update_pull_request_branch | Update PR branch from base | | pull_request_review_write | Create, submit, delete reviews | | add_comment_to_pending_review | Add comment to pending review | | request_copilot_review | Request Copilot code review |

Actions Tools (`actions` toolset)

| Tool | Description | |------|-------------| | list_workflows | List repository workflows | | get_workflow | Get workflow details | | list_workflow_runs | List workflow runs | | get_workflow_run | Get run details and status | | get_workflow_run_logs | Download run logs | | trigger_workflow | Trigger workflow dispatch | | cancel_workflow_run | Cancel a running workflow | | rerun_workflow | Re-run a failed workflow |

Code Security Tools (`code_security` toolset)

| Tool | Description | |------|-------------| | list_code_scanning_alerts | List code scanning alerts | | get_code_scanning_alert | Get alert details | | update_code_scanning_alert | Update alert status | | list_secret_scanning_alerts | List exposed secrets |

Real-World Examples

Example 1: Daily Development Workflow

You: "Show me all open PRs assigned to me that need review"

Claude: I'll search for pull requests assigned to you that are awaiting review...
[Uses search_pull_requests tool]

Found 3 PRs awaiting your review:
1. #142 - Add user authentication (feature/auth)
2. #138 - Fix memory leak in cache service (bugfix/cache)
3. #135 - Update dependencies (chore/deps)

Would you like me to show details for any of these?

Example 2: Issue Triage

You: "Create an issue for the login bug we discussed, label it as high priority, and assign it to the security team"

Claude: I'll create the issue with the appropriate labels and assignment...
[Uses issue_write tool]

Created issue #156: "Login Session Vulnerability"
- Labels: bug, high-priority, security
- Assigned to: @security-team
- Milestone: v2.1.0

Would you like me to add more details or link related issues?

Example 3: CI/CD Monitoring

You: "Why did the latest build fail on main?"

Claude: Let me check the workflow runs for the main branch...
[Uses list_workflow_runs and get_workflow_run_logs tools]

The CI workflow failed on commit abc1234:
- Step: "Run tests"
- Error: Test 'user.auth.test.js' failed
- Line 45: Expected status 200, got 401

The test is expecting successful authentication but receiving unauthorized.
Would you like me to show the related code changes?

Example 4: Repository Management

You: "Create a new branch called 'feature/payments' from main, add a starter file for the payment service, and create a draft PR"

Claude: I'll set that up for you...
[Uses create_branch, create_or_update_file, create_pull_request tools]

Done! Here's what I created:
1. Branch: feature/payments (from main)
2. File: src/services/payment-service.ts (basic structure)
3. Draft PR #157: "Add payment service foundation"

The PR is ready for you to continue development.

Example 5: Security Audit

You: "Are there any open Dependabot alerts or code scanning issues I should address?"

Claude: Let me check your security status...
[Uses list_code_scanning_alerts, list_dependabot_alerts tools]

Security Summary:
- 2 Dependabot alerts (1 critical, 1 moderate)
  - Critical: lodash < 4.17.21 (prototype pollution)
  - Moderate: axios < 1.6.0 (SSRF vulnerability)
- 1 Code scanning alert
  - SQL injection risk in src/db/queries.ts:42

Would you like me to create issues for tracking these or show remediation steps?

Advanced Configuration

Read-Only Mode

Disable all write operations for safety:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server", "--read-only"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Or via environment variable:

GITHUB_READ_ONLY=true

Lockdown Mode

Restrict access to public repositories based on user permissions:

claude mcp add github --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  --env GITHUB_LOCKDOWN_MODE=true \
  -- npx -y @anthropic-ai/github-mcp-server

Dynamic Toolsets (Local Server Only)

Enable runtime tool discovery and activation:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server", "--dynamic-toolsets"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

This enables three additional tools:

enable_toolset - Activate a toolset at runtime
list_available_toolsets - See all available toolsets
get_toolset_tools - List tools in a toolset

GitHub Enterprise Server

For self-hosted GitHub Enterprise:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/github-mcp-server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx",
        "GITHUB_HOST": "https://github.yourcompany.com"
      }
    }
  }
}

Specific Repository Access

Limit access to specific repositories:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "@anthropic-ai/github-mcp-server",
        "--tools", "get_file_contents,list_issues,create_pull_request"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    }
  }
}

Custom Timeout Configuration

Increase timeout for slow connections:

MCP_TIMEOUT=30000 claude

Increase Output Limits

For large repository operations:

MAX_MCP_OUTPUT_TOKENS=50000 claude

Troubleshooting Guide

Issue: Server Not Appearing

Symptoms: GitHub MCP server doesn't show in /mcp command

Solutions:

Restart Claude Code completely

# Close all Claude Code instances
claude mcp list  # Verify configuration exists

Verify JSON syntax
- Use a JSON validator on your config file
- Check for trailing commas or missing quotes
Check file paths are absolute
- Replace ~/ with full path on some systems
Review logs
- macOS: ~/Library/Logs/Claude/mcp.log
- Windows: %APPDATA%\Claude\logs\
- Linux: ~/.local/share/Claude/logs/

Issue: Authentication Failed

Symptoms: "Bad credentials" or "401 Unauthorized" errors

Solutions:

Verify token is valid

curl -H "Authorization: Bearer ghp_xxxx" https://api.github.com/user

Check token scopes
- Go to github.com/settings/tokens
- Verify required scopes are enabled
Token may be expired
- Check expiration date
- Regenerate if needed

Environment variable not set

echo $GITHUB_PERSONAL_ACCESS_TOKEN  # Should show your token

Issue: Windows ENOENT Error

Symptoms: "spawn npx ENOENT" or command not found

Solutions:

Use cmd wrapper

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@anthropic-ai/github-mcp-server"]
}

Use full path to npx
```
where.exe npx  # Find the full path
```
Install Node.js globally
- Ensure Node.js is in system PATH

Issue: Rate Limiting

Symptoms: "API rate limit exceeded" errors

Solutions:

Use authenticated requests
- Authenticated: 5,000 requests/hour
- Unauthenticated: 60 requests/hour

Check remaining rate limit

curl -H "Authorization: Bearer ghp_xxxx" https://api.github.com/rate_limit

Reduce toolsets
- Enable only needed toolsets to reduce API calls

Issue: Permission Denied for Repository

Symptoms: Can't access certain repositories

Solutions:

Check repository visibility
- Private repos require repo scope
Verify organization membership
- Need read:org for org repos
Check team permissions
- Ensure your account has repository access
SSO authorization
- For SAML SSO orgs, authorize the token

Issue: Timeout Errors

Symptoms: Operations timing out

Solutions:

Increase MCP timeout
```
MCP_TIMEOUT=60000 claude  # 60 seconds
```
Check network connectivity
```
ping api.github.com
```
Use local server
- If remote server is slow, try local installation

Security Best Practices

Token Management

| Practice | Implementation | |----------|----------------| | Use environment variables | Never hardcode tokens in config files | | Rotate regularly | Set 90-day expiration, rotate before | | Separate tokens per project | Use different tokens for different repos | | Use fine-grained PATs | Limit to specific repositories | | Never commit tokens | Add config files to .gitignore |

Minimal Permissions

Start with minimal permissions and add as needed:

# Read-only setup
claude mcp add github --transport stdio \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxx \
  --env GITHUB_READ_ONLY=true \
  --env GITHUB_TOOLSETS=repos,issues \
  -- npx -y @anthropic-ai/github-mcp-server

Audit Token Usage

Go to github.com/settings/tokens
Click on your token
Review "Last used" timestamp
Check which scopes were accessed

Environment Variable Security

Windows (PowerShell):

# Set for current session only
$env:GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxxx"

# Or use Windows Credential Manager

macOS/Linux:

# Use a secrets manager or encrypted file
# Never add tokens to .bashrc directly

Frequently Asked Questions

General Questions

Q: Is GitHub MCP Server free to use?

A: Yes, the GitHub MCP Server is free and open source (MIT license). You only need a GitHub account with appropriate access.

Q: Does it work with private repositories?

A: Yes, private repositories work with the repo scope enabled on your Personal Access Token.

Q: Can I use it with multiple GitHub accounts?

A: Yes, configure separate MCP servers with different names and tokens:

{
  "mcpServers": {
    "github-personal": { ... },
    "github-work": { ... }
  }
}

Technical Questions

Q: What's the API rate limit?

A: Authenticated requests: 5,000/hour. The MCP server uses your token for all requests.

Q: Can I use SSH keys instead of PAT?

A: No, the MCP server requires Personal Access Tokens or OAuth. SSH keys are for Git operations only.

Q: Does it support GitHub Actions secrets?

A: The server can trigger workflows but cannot read or modify repository secrets for security reasons.

Troubleshooting Questions

Q: Why are some tools not working?

A: Check that the required toolset is enabled. Some tools require specific toolsets (e.g., actions for workflow tools).

Q: Can I see what API calls are being made?

A: Enable debug logging:

DEBUG=mcp:* claude

Try These Integrations

Ready to expand your setup? Here are popular integrations that work great with GitHub MCP:

Use GitHub MCP with Claude Code - Direct integration guide
Use GitHub MCP with Cursor - IDE setup
Use GitHub MCP with Windsurf - Windsurf configuration
Use GitLab MCP with Claude Code - Alternative for GitLab users

Next Steps

Now that you have GitHub MCP server configured:

Explore more MCP servers: Browse the MCP Directory
Learn advanced patterns: MCP Server Troubleshooting Guide
Join the community: GitHub MCP Server Discussions

Resources

Last updated: December 4, 2025 | Found this helpful? Browse more MCP tutorials

GitHub MCP Server Setup Guide for Claude Code (2025)

⚡ Quick Start (60 Seconds)

Table of Contents

What is GitHub MCP Server?

Key Capabilities

Why Use GitHub MCP with Claude Code?

Prerequisites

Installation Methods

Method 1: Remote Server (Recommended)

Step 1: Add Remote Server to Claude Code

Step 2: Verify Connection

For GitHub Enterprise Cloud

Method 2: Local Server with npm

Step 1: Generate Personal Access Token

Step 2: Add to Claude Code

Step 3: Set Environment Variable

Method 3: Local Server with Docker

Step 1: Pull the Docker Image

Step 2: Configure Claude Code

Authentication Setup

Personal Access Token (PAT)

Fine-Grained Personal Access Token (Recommended)

Configuration for Claude Code

Using the CLI (Recommended)

Using Configuration Files

Project-Specific Configuration (.mcp.json)

User-Level Configuration (~/.claude.json)

Windows-Specific Configuration

Available Toolsets (20 Categories)

Default Toolsets

All Available Toolsets

Configuring Toolsets

Complete Tools Reference

Repository Tools (repos toolset)

Issue Tools (issues toolset)

Pull Request Tools (pull_requests toolset)

Actions Tools (actions toolset)

Code Security Tools (code_security toolset)

Real-World Examples

Example 1: Daily Development Workflow

Example 2: Issue Triage

Example 3: CI/CD Monitoring

Example 4: Repository Management

Example 5: Security Audit

Advanced Configuration

Read-Only Mode

Lockdown Mode

Dynamic Toolsets (Local Server Only)

GitHub Enterprise Server

Specific Repository Access

Custom Timeout Configuration

Increase Output Limits

Troubleshooting Guide

Issue: Server Not Appearing

Issue: Authentication Failed

Issue: Windows ENOENT Error

Issue: Rate Limiting

Issue: Permission Denied for Repository

Issue: Timeout Errors

Security Best Practices

Token Management

Minimal Permissions

Audit Token Usage

Environment Variable Security

Frequently Asked Questions

General Questions

Technical Questions

Troubleshooting Questions

Try These Integrations

Next Steps

Resources

Repository Tools (`repos` toolset)

Issue Tools (`issues` toolset)

Pull Request Tools (`pull_requests` toolset)

Actions Tools (`actions` toolset)

Code Security Tools (`code_security` toolset)