github-mcp-server

A minimal, read-only MCP server exposing your GitHub repos to Claude Code (or any MCP-compatible client) over stdio.

Tools it exposes

• list_repos(owner?, include_forks?, limit?) - list your repos (or another owner's public repos)
• get_repo_info(owner, repo) - metadata for one repo
• list_directory(owner, repo, path?, ref?) - browse a repo's file tree
• read_file(owner, repo, path, ref?, max_bytes?) - read a text file's contents
• get_readme(owner, repo, ref?) - fetch a repo's README
• search_code(query, owner?, repo?, limit?) - search code (optionally scoped to your repos)
• list_commits(owner, repo, path?, limit?) - recent commit history

Everything is read-only - no write, create, or delete endpoints are exposed.

Setup

1. Create a GitHub Personal Access Token (fine-grained, recommended): GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token.

   • Repository access: select the repos you want Claude to read (or "All repositories")
   • Permissions: Contents: Read-only, Metadata: Read-only (add Code search: Read-only if you want search_code to work)

2. Install dependencies:

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

3. Set the token (don't hardcode it in the script or commit it anywhere):

   export GITHUB_TOKEN=github_pat_xxxxxxxxxxxx
   

   For persistence, add that line to your ~/.zshrc / ~/.bashrc, or use a .env file with a tool like direnv - just make sure it's gitignored.

4. Register the server with Claude Code CLI:

   claude mcp add github-repos -- python3 /absolute/path/to/github-mcp-server/server.py
   

   (If you used a venv, point at the venv's python: /absolute/path/to/github-mcp-server/.venv/bin/python3)

   Since the server reads GITHUB_TOKEN from its environment, either export it in the shell you run claude from, or pass it explicitly:

   claude mcp add github-repos --env GITHUB_TOKEN=github_pat_xxxxxxxxxxxx -- python3 /absolute/path/to/github-mcp-server/server.py
   

5. Verify it's connected:

   claude mcp list
   

   You should see github-repos listed as connected. Then in a Claude Code session you can ask things like "list my repos" or "read the README of my flight-delay-prediction repo" and Claude will call these tools.

Local smoke test (without a client)

python3 -c "
import os
os.environ['GITHUB_TOKEN'] = 'github_pat_xxx'
from server import list_repos
print(list_repos())
"

Notes / next steps

• Rate limits: authenticated requests get 5,000/hour from GitHub's REST API, fine for interactive use.
• If you later want write access (opening issues, commenting on PRs), add new @mcp.tool() functions using requests.post/patch - keep them separate and clearly named so it stays obvious which tools mutate GitHub state.
• If you want this reachable from claude.ai/Cowork (not just Claude Code CLI/VS Code), it needs to move from stdio transport to a hosted HTTP server with OAuth - a materially bigger step, only worth it if you need that reach.