GitHub MCP Server: Complete Integration Guide for Claude Code

The GitHub MCP server connects Claude Code directly to GitHub's platform, giving your AI agent the ability to browse repositories, manage issues and pull requests, analyze code, and automate workflows—all through natural language commands.

This guide covers everything from setup to advanced workflows with GitHub's official MCP server.

How to set up the GitHub MCP server, configure the right permissions, and use it effectively for repository management, PR workflows, and code analysis.

Why Connect Claude Code to GitHub?

With the GitHub MCP server, Claude Code becomes a powerful GitHub assistant:

Repository browsing — Explore code, understand project structure, analyze commits
Issue management — Create, update, triage, and close issues
Pull request workflows — Review PRs, add comments, merge changes
CI/CD intelligence — Monitor GitHub Actions, analyze build failures
Code search — Find functions, patterns, and symbols across repositories
Security analysis — Review Dependabot alerts and security findings

Instead of context-switching between your terminal and browser, you work conversationally.

---

Prerequisites

Before starting, ensure you have:

Claude Code installed and configured
GitHub account with repositories you want to access
Personal Access Token (PAT) with appropriate scopes
Docker installed (optional, for containerized setup)

---

Part 1: Creating a GitHub Personal Access Token

The MCP server uses a Personal Access Token (PAT) to authenticate with GitHub.

Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Fine-grained tokens (recommended) or Tokens (classic).

Click Generate new token. Give it a descriptive name like "Claude Code MCP".

Choose an appropriate expiration. For development work, 90 days is reasonable. You can always regenerate.

Grant permissions based on your use case:

For read-only access:

- repo (read) — Access repository contents

- read:org — Read organization membership

For full access:

- repo — Full repository access

- read:org — Read organization data

- workflow — Update GitHub Actions workflows

- write:discussion — Write discussions

Copy the token immediately—you won't see it again. Store it securely (not in version control).

Fine-Grained vs Classic Tokens

| Token Type | Pros | Cons |

|------------|------|------|

| Fine-grained | Precise permissions, repository-specific | More complex setup |

| Classic | Simpler, broader access | Less granular control |

For most users, fine-grained tokens offer better security with more precise permission control.

Your PAT grants access to your GitHub account. Never commit tokens to version control. Use environment variables.

---

Part 2: Installing the GitHub MCP Server

There are several ways to add the GitHub MCP server to Claude Code.

Method 1: CLI Installation (Recommended)

The simplest approach using Claude Code's built-in MCP management:

``bash


claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here -- npx -y @anthropic-ai/mcp-proxy ghcr.io/github/github-mcp-server


Or using the official Docker image:

bash
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server


Method 2: Remote HTTP Server
Connect to GitHub's hosted MCP endpoint:

bash
claude mcp add --transport http github https://api.githubcopilot.com/mcp \
  -H "Authorization: Bearer ghp_your_token_here"


Method 3: JSON Configuration

Add directly to your MCP configuration file (~/.claude/mcp.json or .claude/mcp.json):

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": "ghp_your_token_here"
      }
    }
  }
}


Method 4: Environment Variable (Recommended for Security)
Store your token in an environment variable:

bash
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"


Then configure without inline token:

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


---
Part 3: Verifying Your Setup
After installation, verify the server is working:

bash
List configured MCP servers
claude mcp list
Get details about the GitHub server
claude mcp get github


Restart Claude Code for changes to take effect, then test with a simple query:


List the repositories in my account


---
Part 4: Available Tools
The GitHub MCP server provides comprehensive tools across several categories:
Repository Tools
| Tool | Description |
|------|-------------|

| get_repository | Get repository details and metadata |

| list_repositories | List repos for a user or organization |

| search_code | Search code across repositories |

| get_file_contents | Read files from a repository |

| list_commits | View commit history |

| get_commit | Get specific commit details |


Issue Tools
| Tool | Description |
|------|-------------|

| list_issues | List issues in a repository |

| get_issue | Get specific issue details |

| create_issue | Create a new issue |

| update_issue | Update an existing issue |

| add_issue_comment | Comment on an issue |

| search_issues | Search issues across repos |


Pull Request Tools
| Tool | Description |
|------|-------------|

| list_pull_requests | List PRs in a repository |

| get_pull_request | Get PR details with diff |

| create_pull_request | Create a new PR |

| merge_pull_request | Merge a PR |

| add_pr_comment | Comment on a PR |

| search_pull_requests | Search PRs across repos |


Actions Tools
| Tool | Description |
|------|-------------|

| list_workflows | List GitHub Actions workflows |

| get_workflow_run | Get workflow run details |

| list_workflow_runs | List recent workflow runs |


---
Part 5: Practical Workflows
Repository Exploration


Tell me about the structure of the facebook/react repository.
What are the main directories and their purposes?


Find all TypeScript files in my project that import from '@tanstack/react-query'


Issue Management


List all open bugs in my-org/my-project labeled as 'high-priority'


Create an issue in my-project titled "Add dark mode support" with a detailed description of the feature requirements


Add a comment to issue #42 summarizing the investigation findings


Pull Request Workflows


Show me all open PRs in my-project that need review


Review PR #123 and summarize the changes, potential issues, and suggested improvements


Merge PR #456 using squash merge


Code Search


Search for all usages of the deprecated 'componentWillMount' in my organization's repositories


Find implementations of rate limiting across our microservices


CI/CD Analysis


What's the status of the latest workflow runs in my-project?


The CI is failing on my PR. Check the workflow logs and tell me what's wrong.


---
Part 6: Advanced Configuration
Toolset Selection

Control which tools are available using the --tools flag:

bash
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_token \
  -e GITHUB_TOOLSETS="repos,issues,pull_requests" \
  -- docker run -i --rm ghcr.io/github/github-mcp-server


Available toolsets:

repos — Repository management

issues — Issue operations

pull_requests — PR workflows

actions — GitHub Actions

code_security — Security features

experiments — Experimental features


Read-Only Mode
For safer exploration without modification risk:

bash
docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server --read-only


This disables all write operations—only read tools are available.
Organization-Specific Access
When working with organization repositories, ensure your token has the necessary org permissions:

bash
For fine-grained tokens, select specific repositories
For classic tokens, ensure 'read:org' scope is included


---
Part 7: Combining with Other Tools
GitHub + CAS Workflow
Combine GitHub context with CAS for persistent memory:


Search GitHub for authentication patterns
Search for JWT authentication implementations in our backend repos
Store the findings in CAS
cas_remember: Found JWT auth pattern in auth-service/src/middleware/jwt.ts - uses RS256 with 24h expiry
Create a task based on findings
cas_task_create: Implement JWT auth following auth-service pattern


GitHub + Local Development
Use GitHub MCP alongside local file operations:


Find how error handling is done in our production API (GitHub)
Apply the same pattern to my local changes
Create a PR with the improvements


---
Part 8: Troubleshooting
Server Not Connecting
Symptom: GitHub tools don't appear in Claude Code
Solutions:

Verify token is valid: test with curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user


Check Docker is running (if using Docker method)
Restart Claude Code after configuration changes

Run claude mcp list to verify registration


Permission Denied
Symptom: "Resource not accessible" or 403 errors
Solutions:
Check token has required scopes for the operation
For organization repos, ensure org hasn't restricted PAT access
Try regenerating the token with broader permissions

Rate Limiting
Symptom: Requests fail with rate limit errors
Solutions:
Authenticated requests have higher limits (5000/hour vs 60/hour)
Verify authentication is working
Space out bulk operations
Consider using conditional requests with ETags

Docker Issues
Symptom: Docker container fails to start
Solutions:

Ensure Docker daemon is running

Check image is pulled: docker pull ghcr.io/github/github-mcp-server`
Verify environment variable is passed correctly
Check for conflicting container names

---

Part 9: Security Best Practices

title="Use Fine-Grained Tokens"

description="Grant only the permissions you need. Scope tokens to specific repositories when possible."

title="Environment Variables"

description="Never hardcode tokens. Use environment variables and secret management."

title="Read-Only for Exploration"

description="Use read-only mode when you're just browsing. Enable writes only when needed."

title="Regular Rotation"

description="Set token expiration and rotate regularly. Review permissions periodically."

Token Storage Recommendations

| Method | Security Level | Use Case |

|--------|---------------|----------|

| Environment variable | Good | Local development |

| Secret manager (1Password CLI, etc.) | Better | Shared machines |

| CI/CD secrets | Best | Automated workflows |

---

Part 10: Use Cases

For Individual Developers

Quick repository exploration without leaving the terminal
Automated issue creation from code comments
PR review assistance with AI insights
Cross-repo code search for patterns

For Teams

Standardized PR review workflows
Automated issue triage and labeling
CI/CD failure analysis and debugging
Documentation generation from code

For Maintainers

Community contribution management
Dependency update tracking
Security vulnerability monitoring
Release notes generation

---

Conclusion

The GitHub MCP server transforms Claude Code into a powerful GitHub assistant. From exploring unfamiliar codebases to managing complex PR workflows, you can do it all through natural language without leaving your terminal.

Combined with CAS for persistent memory and context, you get a complete development environment where your AI assistant understands both your code and your team's GitHub workflows.

Set up the GitHub MCP server today. Start with read-only mode to explore safely, then enable write access when you're comfortable with the workflow.

---

GitHub MCP Server: Complete Integration Guide for Claude Code

Why Connect Claude Code to GitHub?

Prerequisites

Part 1: Creating a GitHub Personal Access Token

Fine-Grained vs Classic Tokens

Part 2: Installing the GitHub MCP Server

Method 1: CLI Installation (Recommended)

Method 2: Remote HTTP Server

Method 3: JSON Configuration

Method 4: Environment Variable (Recommended for Security)

Part 3: Verifying Your Setup

List configured MCP servers

Get details about the GitHub server

Part 4: Available Tools

Repository Tools

Issue Tools

Pull Request Tools

Actions Tools

Part 5: Practical Workflows

Repository Exploration

Issue Management

Pull Request Workflows

Code Search

CI/CD Analysis

Part 6: Advanced Configuration

Toolset Selection

Read-Only Mode

Organization-Specific Access

For fine-grained tokens, select specific repositories

For classic tokens, ensure 'read:org' scope is included

Part 7: Combining with Other Tools

GitHub + CAS Workflow

Search GitHub for authentication patterns

Store the findings in CAS

Create a task based on findings

GitHub + Local Development

Part 8: Troubleshooting

Server Not Connecting

Permission Denied

Rate Limiting

Docker Issues