# OpenCollab MCP **Find your next open source contribution from your AI chat.** [![PyPI version](https://img.shields.io/pypi/v/opencollab-mcp.svg?color=blue)](https://pypi.org/project/opencollab-mcp/) [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/) [![CI](https://github.com/prakhar1605/Opencollab-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/prakhar1605/Opencollab-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) 6 focused tools. Works with Claude Desktop, Cursor, VS Code, or any MCP-compatible client.
--- ## What it does You ask your AI assistant something like: > *"My GitHub is `@octocat`. Find me a good first issue I can actually pick up — make sure nobody's already working on it."* OpenCollab gives the AI 6 tools that read the GitHub API. The AI uses them to: 1. **Find** issues matched to your skills. 2. **Evaluate** whether the repo is worth your time. 3. **Verify** the issue isn't already claimed. 4. **Plan** the PR with full context. That's the whole loop: **find → evaluate → verify → plan**. OpenCollab does not generate text. Your AI client does the thinking; OpenCollab just gives it clean, real-time GitHub data. > **v0.6.0 — relaunched lean.** Previous versions exposed 22 tools. Most went unused, and big tool lists hurt LLM routing. This release ships the 6 that earn their keep. The full 22-tool version is preserved on the [`v1-full`](https://github.com/prakhar1605/Opencollab-mcp/tree/v1-full) branch. --- ## Quick start ### Step 1 — Get a GitHub token Go to [github.com/settings/tokens](https://github.com/settings/tokens) → **Generate new token (classic)** → tick `public_repo` → copy the token (it starts with `ghp_`). ### Step 2 — Add it to your AI client
Claude Desktop (recommended) Open your config file: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Paste this (replace `your_token_here` with the token from Step 1): ```json { "mcpServers": { "opencollab": { "command": "uvx", "args": ["opencollab-mcp"], "env": { "GITHUB_TOKEN": "your_token_here" } } } } ``` Restart Claude Desktop. You're done. > Requires [`uv`](https://docs.astral.sh/uv/) (`brew install uv` on macOS, `pipx install uv` elsewhere). `uvx` will pull `opencollab-mcp` from PyPI on first launch.
Cursor / VS Code Same JSON as above, but in your client's MCP config file (`.cursor/mcp.json` for Cursor).
Plain pip (no uv) ```bash pip install opencollab-mcp ``` Then in your client config, change `command` to the binary that pip put on your PATH: ```json { "mcpServers": { "opencollab": { "command": "opencollab-mcp", "env": { "GITHUB_TOKEN": "your_token_here" } } } } ``` Note: if you switch Python versions or virtualenvs, the `opencollab-mcp` binary may disappear and you'll need to `pip install` again. `uvx` avoids this.
Docker (for remote / streamable-HTTP setups) ```bash docker build -t opencollab-mcp . docker run -e GITHUB_TOKEN=ghp_xxx -p 8000:8000 opencollab-mcp ``` The container runs as a non-root user with `TRANSPORT=streamable-http` on port 8000.
### Step 3 — Try it Open your AI client and ask: > *"My GitHub username is ``. Find me a good first issue I can pick up."* If the AI runs `opencollab_match_me` and comes back with a list, you're set. --- ## What you can ask These are real things the AI can answer once OpenCollab is connected: - *"My GitHub is `@octocat` — find me a good first issue."* - *"Find me a Python good-first-issue."* - *"How healthy is `pandas-dev/pandas`? Is it worth contributing to?"* - *"What's the impact tier of contributing to `tensorflow/tensorflow`?"* - *"Is issue #123 in `facebook/react` still available, or has someone claimed it?"* - *"Plan a PR for issue #456 in `owner/repo` — pull all the context the AI needs."* The AI picks which tools to call based on what you ask. --- ## The 6 tools
Discovery — find issues to work on | Tool | What it does | |---|---| | `opencollab_match_me` | Reads your GitHub profile, detects your top language, returns 10 matching good-first-issues — all in one call. | | `opencollab_find_issues` | Up to 15 recent issues for a given language, with beginner (`good first issue`) and intermediate (`help wanted`) difficulty filters. |
Evaluation — score a repo before you invest time | Tool | What it does | |---|---| | `opencollab_repo_health` | 0–100 contributor-friendliness score: activity, PR merge rate, community files, forks. | | `opencollab_impact_estimator` | Impact tier (LOW → MASSIVE) based on stars + reach, plus a draft resume line. |
Issue intelligence — verify and plan a specific issue | Tool | What it does | |---|---| | `opencollab_check_issue_availability` | Is the issue still open? Assigned? Already has a PR? Checks the timeline so you don't waste a weekend. | | `opencollab_generate_pr_plan` | Bundles the issue body, comments, CONTRIBUTING.md, and repo layout for the AI to plan a fix. |
--- ## How it works ``` You ask Claude → Claude picks tools → OpenCollab hits GitHub API → JSON back to Claude → Claude answers in plain English ``` A few design choices worth knowing: - **No AI inference on our end.** OpenCollab is a thin wrapper over the GitHub REST API. Your AI client (Claude / Cursor / etc.) does all the reasoning. Cost to run OpenCollab: $0. - **Runs locally by default.** Stdio transport — no servers, no telemetry. Your token never leaves your machine. - **5-minute in-memory cache.** Repeat lookups in the same conversation don't re-hit GitHub. Helps stay under rate limits. - **Parallel API calls.** The heavy tools (`match_me`, `repo_health`, `generate_pr_plan`) fan out their GitHub requests with `asyncio.gather`, so they're noticeably faster than sequential. - **Pydantic-validated inputs.** Every tool input is a Pydantic model with `extra="forbid"`. Catches stray fields from LLM-generated tool calls before any logic runs. --- ## Authentication & rate limits OpenCollab needs a GitHub token for two reasons: 1. **Higher rate limit.** Authenticated requests get 5,000/hour vs 60/hour unauthenticated. 2. **Some endpoints need auth.** A few tools (`/timeline`, etc.) may not work without it. Scopes needed: just `public_repo`. OpenCollab never writes anything — it's all reads. --- ## Develop ```bash git clone https://github.com/prakhar1605/Opencollab-mcp.git cd Opencollab-mcp pip install -e ".[dev]" export GITHUB_TOKEN="ghp_xxx" # Run the server (stdio mode, for piping into MCP clients) python -m opencollab_mcp # Run the test suite pytest -v # Lint ruff check src tests # Inspect interactively in the MCP Inspector npx @modelcontextprotocol/inspector python -m opencollab_mcp ``` ### Project layout ``` src/opencollab_mcp/ ├── server.py # entry point, transport selection (stdio / streamable-http) ├── github_client.py # cached httpx wrapper, friendly error mapping ├── helpers.py # date math, base64 decode, issue-number parser ├── models.py # Pydantic input models ├── constants.py # scoring thresholds & magic numbers └── tools/ ├── discovery.py # 2 tools — finding issues ├── evaluation.py # 2 tools — scoring a repo └── issues.py # 2 tools — verifying & planning an issue tests/ # pytest suite ``` ### Contributing Issues and PRs are welcome. The codebase is small (~1000 lines) and intentionally easy to read. Every scoring threshold lives in `constants.py` so tuning is a one-line change. New tools follow the same pattern: a function in `tools/.py`, a Pydantic input model in `models.py`, and a test in `tests/test_tools.py`. The `main` branch is protected — please open a PR rather than pushing directly. CI runs on Python 3.10, 3.11, and 3.12. --- ## Roadmap Already shipped (v0.6.0): - 6 focused tools across discovery, evaluation, and issue intelligence - PyPI release (`pip install opencollab-mcp` / `uvx opencollab-mcp`) - 5-minute in-memory cache + parallel API calls - pytest suite on Python 3.10/3.11/3.12 in CI - Stdio (local) and streamable-HTTP (remote) transports - Branch protection + required CI checks on `main` Open ideas: - `first_pr_generator` — chain `match_me` + `check_issue_availability` + `generate_pr_plan` into one prompt - `track_my_prs` — list your open PRs with staleness nudges - `skill_gap` — compare your skills to a repo's tech stack and tell you what to learn If any of these sound interesting, [open an issue](https://github.com/prakhar1605/Opencollab-mcp/issues/new) — that's the fastest path in. --- ## Why only 6 tools? Earlier versions shipped 22. In practice: - LLMs route worse with crowded tool lists — they pick generic tools and miss the killer ones. - Most of the 22 overlapped (5 different "find issues" variants, 3 different "score this repo" variants). - The 6 that survive form a clean story: **find → evaluate → verify → plan**. The full 22-tool catalogue still lives on the [`v1-full`](https://github.com/prakhar1605/Opencollab-mcp/tree/v1-full) branch if you want it. --- ## License [MIT](LICENSE) — built by [Prakhar Pandey](https://github.com/prakhar1605), IIT Guwahati. If OpenCollab helps you land your first PR, a ⭐ on the repo would mean a lot.