github-repo-summarizer

An MCP server that turns any public GitHub repository into a PDF report containing a codebase summary, the most recent commits, and suggested improvements — generated locally by an Ollama model.

What it does

The server exposes a single MCP tool:

summarize_github_repo(repo_url: str, output_dir: str = ".") -> str

Given a GitHub URL (e.g. https://github.com/owner/repo, owner/repo shorthand, or a git@github.com:owner/repo.git SSH URL), it:

1. Fetches repository metadata, the latest 25 commits, and the recursive file tree from the public GitHub API.

2. Picks a representative set of source files (up to 25 files, each ≤ 40 KB, total ≤ 400 KB), prioritising entry points and manifests (README, pyproject.toml, package.json, Dockerfile, etc.) and skipping noise (node_modules, dist, lockfiles, snapshot folders).

3. Sends that corpus to a local Ollama model in two passes — one for the codebase summary, one for improvement suggestions.

4. Renders a PDF (via ReportLab) and returns the absolute path.

The PDF contains

Related MCP server: MCP GitHub Reader

Requirements

• Python ≥ 3.11

• uv for dependency management

• Ollama running locally with at least one model pulled

• An MCP-aware client (e.g. Claude Desktop)

Installation

# 1. Clone or copy this folder
cd github-repo-summarizer

# 2. Install dependencies into a project-local .venv
uv sync

# 3. Configure environment
cp .env.example .env
# then edit .env to taste (see "Configuration" below)

# 4. Pull at least one Ollama model
ollama pull llama3.2          # small, fast
# or
ollama pull qwen2.5-coder:7b  # better for code analysis, ~4.7 GB

Make sure the Ollama server is running:

ollama serve          # in a terminal
# or just launch the Ollama.app — it starts the server automatically

Configuration

All settings come from environment variables, which can live in a .env file next to main.py (loaded automatically at startup).

Example .env:

OLLAMA_MODEL=qwen2.5-coder:7b
OLLAMA_HOST=http://localhost:11434
OLLAMA_NUM_CTX=32768

Choosing a model

Local LLMs vary widely in code-comprehension quality. Suggestions:

• llama3.2 — 3 B parameters, fast, decent general summaries.

• llama3.1:8b — bigger, better narrative quality.

• qwen2.5-coder:7b — recommended for code-heavy repos; trained for code.

• codellama:13b — older but solid for code review-style output.

Make sure the model's native context window is ≥ OLLAMA_NUM_CTX; otherwise the corpus will be silently truncated.

Using it with Claude Desktop

Add the server to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) — adjust the absolute paths to wherever you cloned the project:

{
  "mcpServers": {
    "github-repo-summarizer": {
      "command": "/absolute/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/github-repo-summarizer",
        "--frozen",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/absolute/path/to/github-repo-summarizer/main.py"
      ]
    }
  }
}

Notes:

• Use the absolute path to uv (which uv). Claude Desktop is a GUI app and doesn't inherit your shell's PATH.

• --directory must point at the project directory, not the script itself. uv chdirs into it.

• Fully quit Claude Desktop (⌘Q on macOS) and reopen it after editing config. Just closing the window won't reload MCP servers.

Once connected, ask Claude to use it:

Use github-repo-summarizer to summarize https://github.com/anthropics/anthropic-sdk-python and save the PDF to my Desktop.

Claude will call summarize_github_repo(repo_url=..., output_dir=...) and return the path to the generated PDF.

Using it from any other MCP client

The server speaks MCP over stdio. Any client that can launch a subprocess and exchange JSON-RPC over stdin/stdout will work. The launch command is:

uv run --directory /path/to/github-repo-summarizer --frozen \
       --with mcp[cli] mcp run /path/to/github-repo-summarizer/main.py

For quick local testing:

uv run python main.py

…and pipe an MCP initialize request to stdin to confirm it responds.

Output

PDFs are written to <output_dir>/<owner>-<repo>-summary.pdf. output_dir defaults to the current working directory of the server process (which, when launched by Claude Desktop, may not be where you expect — pass an explicit path when invoking the tool).

Limitations

• Public repos only. Private repos would need authenticated GitHub access; this server doesn't ship that.

• File budget. The server reads up to 25 files (≤ 40 KB each, ≤ 400 KB total). Very large monorepos will be sampled, not exhaustively analysed.

• LLM quality is bounded by the model. A 3 B parameter model will produce shallower summaries than an 8 B+ model. Pick accordingly.

• No streaming. PDFs are produced after both LLM calls complete; expect tens of seconds to a couple of minutes per repo, dominated by the model's generation speed.

• PDF only. No HTML/Markdown output mode (yet).

Troubleshooting

Server shows "failed" in Claude Desktop developer settings. Check ~/Library/Logs/Claude/mcp-server-github-repo-summarizer.log for the real error. The two most common causes:

• --directory value missing or pointing at a file → uv exits with Not a directory. Fix the path in claude_desktop_config.json.

• uv not found → use the absolute path to uv in command.

Could not connect to Ollama at http://localhost:11434. Run ollama serve (or open Ollama.app).

Ollama model 'X' is not pulled. Run ollama pull X.

Truncated or empty summary. The corpus exceeded the model's context window. Lower OLLAMA_NUM_CTX only hurts; instead, switch to a model with a larger native context, or shrink MAX_TOTAL_BYTES in main.py.

Project layout

github-repo-summarizer/
├── main.py            # MCP server + GitHub/Ollama/PDF logic
├── pyproject.toml     # Project metadata and dependencies
├── .env               # Local config (gitignored)
├── .env.example       # Template
└── README.md

License

Not specified. Add one before redistributing.