# 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**:
   ```bash
   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):
   ```bash
   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**:
   ```bash
   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:
   ```bash
   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**:
   ```bash
   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)

```bash
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.