# Repo Recap — GitHub MCP Server for Claude

> Ask Claude about any GitHub repository in plain English — it answers using real live data.

[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-FastMCP-purple)](https://modelcontextprotocol.io)
---

## What is this?

**Repo Recap** is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that bridges Claude to the GitHub API. Instead of clicking through dozens of GitHub pages, you simply ask Claude a question:

> *"What happened in `vercel/next.js` this week?"*
> *"Draft release notes for `facebook/react` from the last 30 days."*
> *"Which issues in `microsoft/vscode` need the most attention?"*

Claude calls this server, fetches the data, and hands you a clean, readable answer.

---

## Features

| Ask Claude… | Tool called |
|---|---|
| "Recap `owner/repo` from the last week" | `list_recent_activity` |
| "Draft release notes for `owner/repo`" | `summarize_pull_requests` |
| "What open issues need attention?" | `triage_issues` |
| "How healthy is `owner/repo`?" | `get_repo_health` |

**Also includes:**
- A **resource** — read any repo's README directly inside Claude
- A **prompt** — one-click weekly digest template

---

## How it works

```
You (in Claude)  ──►  Claude  ──►  repo-recap server  ──►  GitHub API
                         │                                      │
   clean summary  ◄──────┴──────  tidied-up data  ◄────────────┘
```

Claude never talks to GitHub directly. This server is the bridge: it holds your GitHub token securely, calls the API, and converts raw JSON into readable summaries.

---

## Prerequisites

- Python **3.10+**
- A [GitHub personal access token](https://github.com/settings/tokens?type=beta) (read-only is enough)
- [Claude Desktop](https://claude.ai/download) (to connect the server to Claude)

---

## Setup

### 1. Clone the repo

```bash
git clone https://github.com/YOUR_USERNAME/repo-recap.git
cd repo-recap
```

### 2. Install dependencies

```bash
pip install -r requirements.txt
```

> Tip: use a virtual environment — `python -m venv .venv && source .venv/bin/activate` (Mac/Linux) or `.venv\Scripts\activate` (Windows)

### 3. Create your `.env` file

```bash
cp .env.example .env
```

Open `.env` and paste your GitHub token:

```
GITHUB_TOKEN=github_pat_your_real_token_here
```

**How to get a token:**
GitHub → Settings → Developer settings → **Fine-grained personal access tokens** → New token.
Set it to read-only. Required permissions: **Contents**, **Issues**, **Pull requests**, **Metadata**.

### 4. Test without Claude (optional but recommended)

```bash
mcp dev server.py
```

This opens the **MCP Inspector** in your browser — you can click-test every tool before connecting to Claude.

### 5. Connect to Claude Desktop

Find your Claude Desktop config file:
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add this block (adjust the path to where you cloned the repo):

```json
{
  "mcpServers": {
    "repo-recap": {
      "command": "python",
      "args": ["C:/FULL/PATH/TO/repo-recap/server.py"]
    }
  }
}
```

Restart Claude Desktop. A small hammer icon will appear — the tools are live.

---

## Usage examples

**Weekly recap**
> "Give me a recap of `torvalds/linux` from the last 7 days."

**Release notes**
> "Summarize pull requests in `astral-sh/uv` from the last month and write release notes."

**Issue triage**
> "What are the top 10 open issues in `django/django` sorted by discussion?"

**Health check**
> "How healthy is `supabase/supabase` — stars, open PRs, last release?"

**Read a README**
> "Show me the README for `anthropics/anthropic-sdk-python`."

---

## Project structure

```
repo-recap/
├── server.py          # MCP server — all tools, resource, and prompt live here
├── requirements.txt   # Python dependencies
├── .env.example       # Token template (safe to commit)
├── .env               # Your real token (never committed)
└── .gitignore
```

---

## Built with

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io) — open standard for connecting tools to AI
- [FastMCP](https://github.com/jlowin/fastmcp) — ergonomic MCP server framework
- [PyGithub](https://pygithub.readthedocs.io) — GitHub API Python client
- [python-dotenv](https://pypi.org/project/python-dotenv/) — safe `.env` loading

---

## Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.

1. Fork the repo
2. Create a feature branch (`git checkout -b feature/my-feature`)
3. Commit your changes (`git commit -m 'Add my feature'`)
4. Push to the branch (`git push origin feature/my-feature`)
5. Open a pull request