GitHub Repo Recommender (MCP)

A local MCP server that helps Claude recommend specific GitHub issues and repos worth contributing to, based on your stack and interests rather than a generic trending list. It runs on your machine and plugs into Claude Desktop.

Ask Claude "what should I look at this week?" and it searches GitHub with these tools, reads the results, and picks a shortlist, each with a one-line reason it fits you. Claude does the ranking itself in the conversation; the server supplies the data.

What it does

Your profile, recommendation history, repos seen, health snapshots and shortlists are stored in a local DuckDB file (state.duckdb). The profile starts from the blurb in your config.yaml and is then updated through Claude via update_interests. It is also exposed to Claude as the profile://interests resource.

Related MCP server: ship-it-mcp

Setup

1. Clone and install

git clone https://github.com/infinitevoid1793/repo-recommender-mcp.git
cd repo-recommender-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Python 3.11 or newer is required. To work on the project, install the dev extras instead and run the checks:

pip install -e ".[dev]"
pytest          # 88 offline tests, no token needed
ruff check .

2. Create a GitHub token (read-only, dedicated to this tool)

1. On GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens

2. Generate a new token and name it something identifiable (e.g. repo-recommender-mcp)

3. Set an expiration (90 days is a reasonable default; renew when it lapses)

4. Under Repository access, choose Public repositories (read-only)

5. Under Permissions, grant read-only access to Issues and Metadata only

6. Generate and copy the token immediately; GitHub shows it once

3. Configure

cp config.example.yaml config.yaml
cp .env.example .env

• config.yaml: your seed repos (optional) and an initial profile blurb (stack, interests, goals).

• .env: your token, as GITHUB_TOKEN=....

Both files are gitignored and never committed.

4. Point Claude Desktop at it

Open Claude Desktop's config (Settings → Developer → Edit Config) and add an entry under mcpServers:

{
  "mcpServers": {
    "repo-recommender": {
      "command": "/absolute/path/to/repo-recommender-mcp/.venv/bin/repo-recommender"
    }
  }
}

The token isn't needed here; the server loads it from .env. To print the path:

echo "$(pwd)/.venv/bin/repo-recommender"

5. Restart Claude Desktop

Quit and reopen the app fully, then check the tools icon in the chat input. You should see twelve tools: search_issues, search_repos, get_repo_context, get_issue_activity, get_repo_health, get_issue_detail, get_file_content, get_pr_feasibility, record_recommendation, update_interests, save_shortlist, get_shortlists.

Using it

In a new chat, ask something like "what should I look at this week?" For a niche domain, Claude can run a research pass: check get_shortlists for the topic, search_repos to find active repos, get_repo_health on the candidates, then save_shortlist with the best ~10. Later, ask it to refresh a saved list. It can also call search_issues scoped to shortlisted repos to find concrete issues, then get_issue_detail to read the issue in full, get_pr_feasibility to check nobody has already opened a PR for it, and get_file_content to read the code it points at before recommending it. It uses get_repo_context and get_issue_activity on promising candidates and scores fit against your saved profile. Ask it to call record_recommendation on what it surfaces so those issues don't return, and tell it your priorities have changed to have it call update_interests.

Notes

• GitHub's search endpoint is rate-limited (about 30 requests per minute, even with a token), so this isn't built for high-frequency polling. search_repos pauses between its per-topic queries for this reason.

• Delete state.duckdb to start fresh (this also erases saved shortlists and health history); it is recreated and reseeded from config.yaml on the next run.

• Changes to config.yaml, .env, or the code take effect after restarting Claude Desktop.

• Version history is in CHANGELOG.md.

• Code lives in src/repo_recommender/, with the tools grouped into tools/discovery.py, tools/inspection.py and tools/state.py. Tests are in tests/ and run without a token or network access.

• CI (.github/workflows/ci.yml) lints and tests on Python 3.11–3.13, then builds the wheel and sdist and attaches them to the run as artifacts.

License

MIT. See LICENSE.