GitHub MCP Server Guide

Prerequisites

Step 1: Create a GitHub Personal Access Token

First, generate an access token to allow the MCP server to access GitHub on your behalf:

1. Go to github.com/settings/tokens
2. Click "Generate new token" → "Generate new token (classic)"
3. Name it (e.g., "Claude MCP")
4. Set expiration (recommend: 90 days for security)
5. Select scopes:
   • ✓ repo (full repository access)
   • ✓ read:org (read organization data)
   • ✓ user (read user profile data)
   • ✓ project (if you use GitHub Projects)
6. Click "Generate token"
7. Copy the token (starts with ghp_) — you won't see it again

Step 2: Install the GitHub MCP Server

Add the GitHub MCP server to your Claude Desktop configuration:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Replace ghp_your_token_here with your actual GitHub token from Step 1.

Step 3: Restart Claude Desktop

Close and reopen Claude Desktop completely (Cmd+Q on Mac, then reopen). The GitHub server should now be loaded.

Step 4: Try It Out

Test your GitHub integration with these example queries:

Available Tools & Capabilities

Repository Management

• Create repositories: New public or private repos
• Fork repositories: Fork any public repo you have access to
• Search repositories: Find repos by name, description, topics
• Get repository info: Stars, forks, description, topics

File Operations

• Read file contents: Get any file from any branch
• Create or update files: Commit changes directly via API
• Search code: Find code snippets across all repos

Issues & Pull Requests

• Create issues: Add new issues with labels and assignees
• Update issues: Change title, description, state, labels
• Create pull requests: Open PRs from any branch
• Comment on PRs: Add review comments
• List issues and PRs: Filter by state, labels, assignee

Branches & Commits

• Create branches: New branches from any commit
• List branches: See all branches in a repo
• Get commit history: View commit log with messages and authors

Real-World Use Cases

1. Automated Issue Creation from Bugs

Found a bug in conversation? Create a GitHub issue instantly:

"I found a bug where the login form doesn't validate email addresses. Create a GitHub issue in my repo myapp/frontend with this bug report, label it 'bug' and 'priority-high'"

2. Code Review Assistant

Let Claude review code and suggest improvements:

"Read the file src/auth/login.ts from my repo and suggest security improvements"

3. Pull Request Summaries

Get AI-generated summaries of PRs:

"List all open pull requests in username/repo and summarize what each one does"

4. Cross-Repo Code Search

Find code patterns across all your repositories:

"Search all my repos for functions that make database queries"

5. Documentation Generation

Create or update README files:

"Read the package.json and src/ directory from my repo, then generate a comprehensive README.md with installation instructions, usage examples, and API documentation"

6. Release Note Generation

Generate release notes from commits:

"Get the commit history for username/repo since the last release tag and generate release notes categorized by features, fixes, and breaking changes"

Advanced Workflows

Automated Code Fixes

Claude can read code, identify issues, and commit fixes:

"Read the tests in tests/auth.test.ts. All are failing because the API endpoint changed from /login to /auth/login. Update the test file to fix this."

Branch Management

Create feature branches with initial commits:

"Create a new branch called 'feature/dark-mode' in username/repo and add an initial commit with a new file src/theme/darkMode.ts containing a basic dark mode implementation"

Dependency Updates

Update dependencies and create PRs:

"Read the package.json from username/repo, update React from 18.2.0 to 19.0.0, and create a pull request with the changes"

Security Best Practices

• Use token expiration: Set tokens to expire in 30-90 days, not "never"
• Minimum necessary scopes: Only grant the permissions you need
• Rotate tokens regularly: Generate new tokens periodically
• Review access logs: Check GitHub's security log for unexpected activity
• Never commit tokens: Keep claude_desktop_config.json out of version control
• Use organization tokens: For org repos, consider creating a bot account with limited permissions

Troubleshooting

Server Not Appearing

• Verify JSON syntax in claude_desktop_config.json
• Ensure token is correct (starts with ghp_)
• Restart Claude Desktop completely (Cmd+Q, not just close window)
• Check Claude logs at ~/Library/Logs/Claude/mcp*.log

"Authentication Failed"

• Verify your token hasn't expired
• Check that required scopes (repo, user) are enabled
• Regenerate the token if necessary

"Permission Denied"

• Verify you have access to the repository (check on GitHub web)
• For private repos, ensure repo scope is granted
• For organization repos, check that your token has org access

Changes Not Appearing

• File updates may take a few seconds to reflect on GitHub web
• Check that you're looking at the correct branch
• Verify the commit was created (check commit history)

Limitations

• File size: GitHub API has a 1 MB limit for file contents via API
• Rate limits: 5,000 requests/hour for authenticated users (usually not an issue)
• Large repos: Listing all files in very large repos may be slow
• No Git GUI features: Merge conflict resolution requires manual intervention

Combining with Other MCP Servers

The GitHub server works great alongside other MCP servers:

What's Next?

Explore more MCP servers to extend your workflow: