GitHub MCP Server

A Model Context Protocol (MCP) server that connects Claude to your GitHub repositories. Query repos, review PRs, manage issues, search code, and automate GitHub workflows—all from Claude.

Features

Included Tools

• list_repos — List your repositories with metadata (stars, language, etc.)
• read_file — Read files from any repo (source code, docs, configs)
• list_prs — Fetch pull requests with filtering (open/closed/all)
• get_pr — Get PR details including full diff for code review
• list_issues — Search and filter issues by state, labels, etc.
• create_issue — File new issues programmatically
• add_pr_comment — Add review comments to pull requests
• search_code — Search code across repos using GitHub search syntax
• get_repo_info — Fetch repo metadata (description, stars, topics, etc.)

Quick Start

1. Set Up Authentication

Create a GitHub Personal Access Token:

1. Go to github.com/settings/personal-access-tokens
2. Click Generate new token → Generate new token (fine-grained)
3. Name it claude-mcp
4. Under Repository access, select All repositories or specific repos
5. Under Permissions, grant:
   • Contents: Read-only
   • Issues: Read & write (if you want to create issues)
   • Pull requests: Read & write (if you want to comment on PRs)
6. Click Generate token and copy it

2. Install Dependencies

cd /Users/maywu/Projects/github-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Set Your GitHub Token

cp .env.example .env
# Edit .env and paste your token:
# GITHUB_TOKEN=ghp_xxxxx

Or set it directly:

export GITHUB_TOKEN="your_github_pat_here"

4. Connect to Claude Code

# From the project root:
claude mcp add --env GITHUB_TOKEN="your_github_pat_here" \
  --transport stdio github \
  -- python server.py

Verify it connected:

claude mcp list

You should see: ✓ github — 9 tools

Usage

Once connected, you can ask Claude to:

List my repositories

Review PR #456 and suggest improvements for anthropic/claude-code

Create an issue for the bug we just found in my-repo

Find all instances of TODO comments in my codebase

Read the CONTRIBUTING.md from owner/repo

List all open issues labeled 'bug' and 'critical' in my-org/my-repo

Local Development & Testing

Run the server directly (for debugging)

export GITHUB_TOKEN="your_token"
python server.py

You should see:

INFO:mcp.server:Started MCP server

If there are errors, you'll see them here.

Test a tool manually

Once connected to Claude Code, run:

claude

Then in the session:

Use the github server to list my repos and show me the 5 most recently updated ones

Claude will call the list_repos tool and display results.

Common Issues

"Error: GITHUB_TOKEN environment variable not set"

• Make sure your token is exported: echo $GITHUB_TOKEN
• If using Claude, pass it with --env: claude mcp add --env GITHUB_TOKEN="token" ...

"Error: Unauthorized (401)"

• Your token may have expired or insufficient permissions
• Generate a new token at github.com/settings/personal-access-tokens
• Check that the token has Contents and Issues scopes enabled

"Timeout connecting to server"

• The server may be crashing on startup. Run it directly to see errors: python server.py
• Try increasing the timeout: MCP_TIMEOUT=60000 claude

Architecture

Server Structure

server.py
├── list_tools()          — Define all available tools
├── call_tool()           — Route tool calls to handlers
└── _<tool_name>()        — Handler for each tool (async)

Adding New Tools

To add a new GitHub operation:

1. Add the tool definition in list_tools():

Tool(
    name="my_new_tool",
    description="What this tool does",
    inputSchema={
        "type": "object",
        "properties": {...},
        "required": [...]
    }
)

2. Add a handler function:

async def _my_new_tool(arguments: dict) -> list[ToolResult]:
    # Your implementation here
    return [ToolResult(content=[TextContent(text="result")])]

3. Add a route in call_tool():

elif name == "my_new_tool":
    return await _my_new_tool(arguments)

GitHub API Limits

• Authenticated requests: 5,000/hour
• Unauthenticated: 60/hour

This server always uses your token, so you get the 5,000/hour limit.

Security

• Never commit your .env file or tokens to version control
• Use fine-grained personal access tokens (not classic tokens)
• Scope tokens to minimal required permissions
• Rotate tokens regularly
• If a token is leaked, revoke it immediately at github.com/settings/personal-access-tokens

Troubleshooting

Check server status

claude mcp list

Should show:

github (stdio)
  ✓ Connected
  9 tools available

View server logs

If running in Claude Code, check the MCP logs:

claude mcp logs github

Test the API directly

curl -H "Authorization: Bearer $GITHUB_TOKEN" \
  https://api.github.com/user/repos

Next Steps

• Share with teammates: Commit .env.example and server.py to a project repo, have teammates set their own GITHUB_TOKEN
• Deploy as a service: Run on a server and use --transport http instead of stdio
• Add more tools: Extend with webhooks, actions, releases, discussions, etc.
• Integrate with workflows: Build Claude-assisted code review, release notes generation, or issue triage

Resources

• MCP Documentation
• GitHub API Docs
• Claude Code MCP Setup