Skip to main content
Glama

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.

Related MCP server: GitHub MCP Server

Tools

Tool

What it does

get_repo_health

Deterministic 0–100 health score from commit recency, issue-triage ratio, and contributor count. Flags archived repos immediately.

summarize_recent_commits

Groups commits from the last N days by type (feature/fix/docs/refactor/chore) for a quick "what changed" view.

find_good_first_issues

Finds beginner-labeled issues, scores each for genuine clarity, and flags ones that look mislabeled (e.g. touches core architecture despite the "good first issue" tag).

ask_repo

Free-text Q&A over README + docs/*.md + top issue threads via embeddings-based semantic search (Voyage AI + Qdrant cosine similarity).

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 (claude_desktop_config.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

  • GitHub API, not scraping — clean, documented, generously rate-limited with a token.

  • Deterministic scoring, generative explanation — get_repo_health's score is a fixed 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.

  • Mislabel detection in find_good_first_issues — real "good first issue" labels are 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.

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:

  1. On first query for a repo, chunk README + docs/*.md (top-level, cap 15 files) + top 8 most-discussed issue threads (title + body, ~500-word chunks, 50-word overlap)

  2. Embed each chunk with Voyage AI (voyage-3.5-lite)

  3. Store vectors in Qdrant Cloud, one collection per repo (repo_<owner>_<name>)

  4. On every query: embed the question, cosine-similarity search top-5 chunks

  5. Subsequent queries for the same repo skip re-indexing (checked via the collection's points_count) — only the query itself gets embedded

Why embeddings over keyword matching: keyword overlap requires literal shared words — "how do I install React?" and a README section titled "Getting Started" share zero words and would never match. Embeddings place semantically similar text near each other in vector space regardless of exact wording, so retrieval survives paraphrasing and synonyms — the actual failure mode keyword search hits in practice.

Known simplifications (marked ponytail: in src/rag.ts), each with a stated upgrade path:

  • Issue threads index title+body only, not the full comment discussion (avoids one extra API call per issue) — fetch /issues/{n}/comments if answers need to reflect resolution discussion, not just the original report.

  • Chunk sizing uses word count as a token-count approximation, not a real tokenizer.

  • No staleness check — a repo indexed once stays indexed even if its docs change. Add a TTL or a pushed_at check against the stored index if content goes stale.

License

MIT

Available Tools

4 tools
ask_repoAsk RepoA

Answers a free-text question about a repo via embeddings-based semantic search over its README, docs/*.md, and top issue threads. Use this for questions the other structured tools can't answer directly, e.g. 'does this support TypeScript?' or 'how do I configure X?' Requires VOYAGE_API_KEY and QDRANT_URL/QDRANT_API_KEY to be set.

Inputs: repo (required), owner (required), query (required).

find_good_first_issuesFind Good First IssuesA

Finds open issues labeled for beginners/first-time contributors, then scores each for genuine clarity of scope and flags ones that look mislabeled (e.g. touches core architecture despite the 'good first issue' label).

Inputs: repo (required), owner (required).

get_repo_healthGet Repo HealthA

Computes a maintenance-health score (0-100) for a public GitHub repo from commit recency, issue-triage ratio, and contributor diversity. Use this before deciding whether to depend on or contribute to a repo.

Inputs: repo (required), owner (required).

summarize_recent_commitsSummarize Recent CommitsB

Fetches commits from the last N days and groups them by type (feature/fix/docs/refactor/chore) so an agent can describe what changed without reading raw commit logs.

Inputs: repo (required), owner (required), days.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool targets a clearly distinct purpose: health scoring, commit summarization, beginner-issue discovery, and semantic Q&A. There is no meaningful overlap—ask_repo explicitly serves as a fallback for questions the structured tools cannot answer.

    Naming Consistency5/5

    All tool names use lowercase snake_case and follow a predictable verb-first pattern: get_, summarize_, find_, ask_. The consistency makes it easy to infer each tool's action at a glance.

    Tool Count5/5

    Four tools is a well-scoped count for a focused repository-analysis server. Each tool covers a distinct aspect of evaluating or exploring a repo, and none feel redundant or missing from the apparent purpose.

    Completeness4/5

    The server covers the core repo-evaluation workflow well: health, recent changes, contribution entry points, and open-ended questions. Minor gaps exist, such as structured access to license, stars, or PR activity, but ask_repo can work around many of these.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers