Github Repo MCP server

github-repo-mcp

An MCP (Model Context Protocol) server that lets any AI agent — Claude Desktop, Claude Code, Cursor — reason about a public GitHub repository directly, instead of the human manually reading READMEs, commit logs, and issue trackers.

Why this exists

Evaluating an unfamiliar repo ("is this actively maintained? is this issue actually beginner-friendly? what changed recently?") is repetitive manual work every developer does. This server turns that into four callable tools any MCP-compatible agent can use.

Tools

Setup

npm install
cp .env.example .env
# Add a GitHub personal access token to .env — raises the rate limit from 60/hr to 5000/hr.
# No special scopes needed for public repo data: https://github.com/settings/tokens
#
# ask_repo also needs, both free tier:
#   VOYAGE_API_KEY  — https://dashboard.voyageai.com/ (API Keys -> Create new key)
#   QDRANT_URL, QDRANT_API_KEY — https://cloud.qdrant.io/ (create a free cluster)
npm run build

Running locally with Claude Desktop

Add this to your Claude Desktop MCP config (claudedesktopconfig.json):

{
  "mcpServers": {
    "github-repo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-repo-mcp/build/index.js"],
      "env": { "GITHUB_TOKEN": "your_token_here" }
    }
  }
}

Restart Claude Desktop, then try: "Use github-repo-mcp to check the health of facebook/react and find me a good first issue."

Architecture notes

formula (recency + issue triage + contributor diversity), not an LLM guess. This keeps the number reproducible; an LLM (in the calling agent) can narrate why on top of it.

• GitHub API, not scraping — clean, documented, generously rate-limited with a token.
• Deterministic scoring, generative explanation — getrepohealth's score is a fixed

often wrong. The tool checks body length, red-flag keywords (architecture, migration, security), and comment count to catch issues that are mislabeled, not just present them at face value.

• Mislabel detection in findgoodfirstissues** — real "good first issue" labels are

Demo

See docs/demo.md for a real (not mocked) protocol exchange against facebook/react, including the embeddings-based ask_repo retrieving the correct answer for a query that shares no words with the source text.

How ask_repo retrieval works

ask_repo started as keyword-window retrieval over the README (see git history) and was upgraded to embeddings-based RAG, implemented in src/rag.ts:

top 8 most-discussed issue threads (title + body, ~500-word chunks, 50-word overlap)

1. On first query for a repo, chunk README + docs/*.md (top-level, cap 15 files) +

points_count) — only the query itself gets embedded

1. Embed each chunk with Voyage AI (voyage-3.5-lite)
2. Store vectors in Qdrant Cloud, one collection per repo (repo__)
3. On every query: embed the question, cosine-similarity search top-5 chunks
4. Subsequent queries for the same repo skip re-indexing (checked via the collection's

Shortened. The full README is on GitHub.