Skip to main content
Glama
OpenCollab MCP

OpenCollab MCP

by prakhar1605

OpenCollab MCP

Find your next open source contribution from your AI chat.

PyPI version Python 3.10+ CI License: MIT

6 focused tools. Works with Claude Desktop, Cursor, VS Code, or any MCP-compatible client.

Changelog · Contributing


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 branch.


Related MCP server: contrib-radar

Quick start

Step 1 — Get a GitHub token

Go to 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

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):

{
  "mcpServers": {
    "opencollab": {
      "command": "uvx",
      "args": ["opencollab-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Restart Claude Desktop. You're done.

Requires uv (brew install uv on macOS, pipx install uv elsewhere). uvx will pull opencollab-mcp from PyPI on first launch.

Use the same JSON as above in your Cursor MCP config file (.cursor/mcp.json).

Create or open .vscode/mcp.json in your workspace and add:

{
  "servers": {
    "opencollab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["opencollab-mcp"],
      "env": {
        "GITHUB_TOKEN": "${input:github-token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "github-token",
      "description": "GitHub Personal Access Token",
      "password": true
    }
  ]
}

When prompted by VS Code, enter your GitHub token.

Run this in your terminal (replace ghp_your_token_here with the token from Step 1):

claude mcp add opencollab -e GITHUB_TOKEN=ghp_your_token_here -- uvx opencollab-mcp

Check it's connected:

claude mcp list

Or run /mcp inside a Claude Code session.

pip install opencollab-mcp

Then in your client config, change command to the binary that pip put on your PATH:

{
  "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 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. For an SSE client, use -e TRANSPORT=sse; both remote transports bind to 0.0.0.0 and accept PORT (default 8000). GET /health returns JSON {"status": "ok", "version": "<installed version>"}; the image's HEALTHCHECK probes it on the configured PORT. Using Docker Compose

Create a .env file from the example:

cp .env.example .env

Open .env and replace the placeholder with your GitHub token. Do not commit .env.

Start the service:

docker compose up --build -d

Check the service health:

curl http://localhost:8000/health

To stop the service:

docker compose down

Step 3 — Try it

Open your AI client and ask:

"My GitHub username is <your-username>. 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

Tool

What it does

opencollab_match_me

Reads your GitHub profile, detects your top languages, returns up to 10 matching unassigned issues (adjustable with limit, 1–30) — beginner ("good first issue", "good-first-issue", "beginner", "first-timers-only") or intermediate ("help wanted", "help-wanted", "intermediate") via difficulty — all in one call.

opencollab_find_issues

Up to 15 unassigned issues (adjustable with limit, 1–30) created within max_age_days (default 90, range 1–365) for up to 3 comma-separated languages, with beginner ("good first issue", "good-first-issue", "beginner", "first-timers-only") and intermediate ("help wanted", "help-wanted", "intermediate") difficulty filters. Supports sorting via sort (newest [default], recently_updated, or least_discussed). Optional scope narrows the search to an organization/user (owner) or a single repository (owner/name). Optional exclude_repos omits up to 10 owner/name repositories (default empty). Each issue includes updated_days_ago (days since last activity; null if missing or unparseable).

Both discovery tools exclude issues labelled wontfix, won't fix, duplicate, or invalid, including common hyphen/underscore variants. Custom label names may still require checking with opencollab_check_issue_availability.

opencollab_match_me scans up to 100 most recently pushed public repositories, excluding forks from language analysis. If the scan is incomplete, its response includes repos_analyzed (the raw number returned, including forks), repos_total and a note explaining the limit. These fields are omitted for a complete scan; the separate Python fallback note still appears when no language is detected.

Tool

What it does

opencollab_repo_health

0–100 contributor-friendliness score: activity, PR merge rate, community files, forks. Archived repos get an "Archived — read-only" verdict; community_profile_available says whether community-file data could be read. score_breakdown lists the points earned by each factor, and capped flags when their raw total exceeded HEALTH_MAX_SCORE (the breakdown stays uncapped; health_score is capped).

opencollab_impact_estimator

Impact tier (LOW → MASSIVE) based on stars + reach, plus a draft resume line.

Tool

What it does

opencollab_check_issue_availability

Is the issue still open? Assigned? Already has an open or merged closing PR? Uses GraphQL closedByPullRequestsReferences when authenticated (falling back to closing-keyword matching across paginated REST timeline pages), separates plain mentions into mentioned_in_prs, and reports linked_prs_checked, linked_prs_source, and timeline_truncated when the timeline cap is reached.

opencollab_generate_pr_plan

Bundles the issue body, comments, CONTRIBUTING.md, PR template preview (null when unavailable), and repo layout for the AI to plan a fix. Returns an error for pull request numbers.


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

The server uses GITHUB_TOKEN when non-empty, otherwise it falls back to GH_TOKEN (also used by the GitHub CLI). Surrounding whitespace is stripped from either value; when neither provides a token, requests are unauthenticated.

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.


Troubleshooting

Check your setup with --check

opencollab-mcp --check

This verifies your GitHub token, scopes and rate limit without starting the server, then exits (0 when everything works, 1 otherwise). Run it first when a tool returns an authentication or rate-limit error. It prints which token variable is in use (GITHUB_TOKEN, GH_TOKEN, or none) but never prints the token itself.

Which version am I running?

opencollab-mcp --version   # or: opencollab-mcp -V

Include this output when you report a bug. If the flag isn't recognised, you're on an older release; upgrade (see the next item).

uvx keeps running an old version

uvx caches packages, so it can keep using a stale copy. Force the newest release with either:

uvx --refresh opencollab-mcp
uvx opencollab-mcp@latest

In an MCP client config, use "args": ["--refresh", "opencollab-mcp"] (or "opencollab-mcp@latest").

Rate-limit errors

Symptom: a tool returns

Error: GitHub API rate limit exceeded. Resets in ~N minutes. Set GITHUB_TOKEN for a 5,000 requests/hour limit.

Fix: set GITHUB_TOKEN (see Authentication & rate limits). Without a token you get 60 requests/hour; with one, 5,000. If the token is already set, restart your MCP client so it picks up the environment variable.

Behind a proxy / custom certificates

HTTPX respects HTTPS_PROXY for HTTPS requests, NO_PROXY for hosts that bypass the proxy, and SSL_CERT_FILE or SSL_CERT_DIR for custom CA certificates. If both certificate variables are set, HTTPX uses SSL_CERT_FILE. REQUESTS_CA_BUNDLE is not used by HTTPX. See the HTTPX environment variables docs.

For example, add the settings you need to Claude Desktop's config:

{
  "mcpServers": {
    "opencollab": {
      "command": "uvx",
      "args": ["opencollab-mcp"],
      "env": {
        "GITHUB_TOKEN": "your_token_here",
        "HTTPS_PROXY": "http://proxy.example.com:8080",
        "NO_PROXY": "localhost,127.0.0.1",
        "SSL_CERT_FILE": "/path/to/ca-bundle.pem",
        "SSL_CERT_DIR": "/path/to/certificates"
      }
    }
  }
}

Replace the example values, omit settings you don't need, and restart Claude Desktop. To test the same proxy and CA bundle in a terminal first:

export HTTPS_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
export SSL_CERT_FILE="/path/to/ca-bundle.pem"
export SSL_CERT_DIR="/path/to/certificates"
curl --cacert "$SSL_CERT_FILE" https://api.github.com/rate_limit

In Windows PowerShell:

$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1"
$env:SSL_CERT_FILE = "C:\path\to\ca-bundle.pem"
$env:SSL_CERT_DIR = "C:\path\to\certificates"
curl.exe --cacert $env:SSL_CERT_FILE https://api.github.com/rate_limit

If using only SSL_CERT_DIR, use --capath with that directory instead of --cacert (subject to your curl TLS backend's support).

Docker container shows "unhealthy"

The health check calls /health on PORT inside the container. Check that:

  1. PORT matches the port you publish. If you set -e PORT=9000, publish -p 9000:9000.

  2. /health responds:

    curl localhost:8000/health   # expected output: {"status": "ok", "version": "<installed version>"}
  3. The container is running in HTTP mode (TRANSPORT=streamable-http, the image default). In stdio mode there is no /health endpoint.

Where are the logs?

Logs go to stderr (stdout is reserved for the MCP protocol in stdio mode). For more detail, set OPENCOLLAB_LOG_LEVEL:

OPENCOLLAB_LOG_LEVEL=DEBUG opencollab-mcp

Valid levels: DEBUG, INFO (default), WARNING, ERROR, CRITICAL. In Docker, read them with docker logs <container>. Most MCP clients also keep a per-server log; check your client's MCP log viewer.


Develop

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 / HTTP / SSE)
├── 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/<category>.py, a Pydantic input model in models.py, and a test in tests/test_tools.py.

Please read the Code of Conduct before contributing.

When reporting bugs or submitting issues, please include the version of opencollab-mcp you are running (especially when using uvx caches):

opencollab-mcp --version

(or opencollab-mcp -V)

The main branch is protected — please open a PR rather than pushing directly. CI runs on Python 3.10, 3.11, 3.12, and 3.13.


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/3.13 in CI

  • Stdio (local) and streamable-HTTP (remote) transports

  • Branch protection + required CI checks on main

Merged since v0.6.1 (see the Changelog):

See the Changelog for features and changes merged since v0.6.1.

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 — 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 branch if you want it.


Contributors

New to open source? Start with an open good first issue.


License

MIT — built by Prakhar Pandey, IIT Guwahati.

If OpenCollab helps you land your first PR, a ⭐ on the repo would mean a lot.

Available Tools

22 tools
opencollab_analyze_profileA
Read-onlyIdempotent

Analyze a GitHub user's profile to extract skills, languages, contribution patterns, and interests.

Returns a structured skill profile including top languages, starred topics, contribution frequency, and repository highlights.

Inputs: params (required). Returns: result

opencollab_check_issue_availabilityA
Read-onlyIdempotent

Check if a GitHub issue is still available — no one has claimed it or opened a PR for it.

Checks assignees and linked pull requests to determine availability.

Inputs: params (required). Returns: result

opencollab_compare_reposA
Read-onlyIdempotent

Compare two GitHub repositories side-by-side for contributor-friendliness.

Returns stars, PR merge rate, activity, and a recommendation on which to contribute to.

Inputs: params (required). Returns: result

opencollab_contribution_readinessA
Read-onlyIdempotent

Check how easy it is to set up and contribute to a repository.

Looks for Dockerfile, CI configs, documentation, contributing guide, and issue/PR templates. Returns a readiness checklist with difficulty rating.

Inputs: params (required). Returns: result

opencollab_contributor_leaderboardA
Read-onlyIdempotent

Get the top contributors of a repository with their commit counts and profiles.

Returns the top 10 contributors ranked by number of commits.

Inputs: params (required). Returns: result

opencollab_dependency_checkA
Read-onlyIdempotent

Inspect a repo's tech stack by reading its dependency files.

Checks package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, and Gemfile to show what libraries and frameworks the project uses.

Inputs: params (required). Returns: result

opencollab_find_issuesA
Read-onlyIdempotent

Find beginner-friendly open-source issues labelled 'good first issue' for a given programming language.

Returns up to 15 recently created issues from public repos.

Inputs: params (required). Returns: result

opencollab_find_mentor_reposB
Read-onlyIdempotent

Find repositories that actively mentor newcomers.

Searches for repos with mentorship labels, extensive contributing guides, and programs like GSoC, Outreachy, or Hacktoberfest.

Inputs: params (required). Returns: result

opencollab_first_timer_scoreA
Read-onlyIdempotent

Rate how ready a GitHub user is for open source contributions.

Scores profile completeness, coding activity, language diversity, and gives personalized tips on what to improve before contributing.

Inputs: params (required). Returns: result

opencollab_generate_pr_planA
Read-onlyIdempotent

Gather full context about a GitHub issue so the AI can draft a PR plan.

Fetches issue body, comments, labels, contributing guidelines, and repo directory structure for comprehensive PR planning.

Inputs: params (required). Returns: result

opencollab_impact_estimatorB
Read-onlyIdempotent

Estimate the impact of contributing to a specific repository.

Produces an impact tier (MASSIVE/HIGH/MEDIUM/LOW) and a suggested resume line.

Inputs: params (required). Returns: result

opencollab_issue_complexityA
Read-onlyIdempotent

Estimate the complexity of a specific GitHub issue.

Analyzes issue body length, number of comments, labels, linked PRs, and discussion depth to produce a complexity rating.

Inputs: params (required). Returns: result

opencollab_label_explorerA
Read-onlyIdempotent

List all labels in a repository with their descriptions and open issue counts.

Helps contributors discover which labels mark beginner-friendly issues, bugs, features, documentation tasks, and more.

Inputs: params (required). Returns: result

opencollab_match_meA
Read-onlyIdempotent

All-in-one: analyze a GitHub profile and instantly find issues matched to that user's top skills.

Detects the user's primary language and returns 10 matching good-first-issues.

Inputs: params (required). Returns: result

opencollab_recent_prsA
Read-onlyIdempotent

Show recently merged pull requests in a repository.

Helps contributors see what kind of PRs get accepted, how fast they're merged, and who the active reviewers are.

Inputs: params (required). Returns: result

opencollab_repo_activity_pulseA
Read-onlyIdempotent

Get an activity pulse for a repo over the last 30 days.

Shows commit frequency, issue open/close rate, PR activity, and whether the project is gaining or losing momentum.

Inputs: params (required). Returns: result

opencollab_repo_healthA
Read-onlyIdempotent

Score a repository's health and contributor-friendliness (0-100).

Checks activity recency, community size, PR merge patterns, open issues, and whether the repo has essential contributor files.

Inputs: params (required). Returns: result

opencollab_repo_languagesA
Read-onlyIdempotent

Get a detailed language breakdown for a repository.

Shows percentage of each programming language used in the codebase. Helps you decide if you have the right skills before contributing.

Inputs: params (required). Returns: result

opencollab_similar_reposA
Read-onlyIdempotent

Find repositories similar to a given one based on topics and language.

If you like contributing to repo X, this finds other repos in the same domain that are also welcoming to contributors.

Inputs: params (required). Returns: result

opencollab_stale_issue_finderA
Read-onlyIdempotent

Find old, unclaimed issues in a repo that no one is working on — hidden easy wins.

Returns issues older than 30 days with no assignees.

Inputs: params (required). Returns: result

opencollab_weekend_issuesA
Read-onlyIdempotent

Find small, quick issues perfect for a weekend or 1-2 hour contribution.

Searches for issues labelled documentation, typo, test, chore, or other low-effort tags in addition to good-first-issue.

Inputs: params (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools have distinct purposes, but some overlap exists. For example, 'opencollab_find_issues' and 'opencollab_weekend_issues' both find issues, with the latter focusing on quick tasks, which could cause confusion. Similarly, 'opencollab_repo_health' and 'opencollab_contribution_readiness' both assess repository friendliness, though from slightly different angles. Descriptions help clarify, but boundaries are not always sharp.

    Naming Consistency5/5

    All tool names follow a consistent 'opencollab_verb_noun' pattern with snake_case, making them predictable and easy to parse. The verb choices are descriptive and aligned with the tool's function, such as 'analyze_profile', 'check_issue_availability', and 'generate_pr_plan'. This uniformity enhances usability and reduces cognitive load.

    Tool Count3/5

    With 22 tools, the count feels heavy for the open-source contribution domain. While the tools cover various aspects, some could be consolidated (e.g., multiple issue-finding tools) to reduce complexity. It's borderline excessive, potentially overwhelming for agents, but not extreme.

    Completeness5/5

    The tool set provides comprehensive coverage for open-source contribution workflows, from profile analysis and issue discovery to PR planning and impact estimation. It includes all necessary operations like finding issues, assessing repositories, and matching users, with no obvious gaps. The domain is well-covered with tools that support end-to-end contribution processes.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Guides AI agents through open-source contribution workflows, from finding issues to submitting PRs, while keeping decision-making and coding with the human contributor.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to evaluate real OSS contribution opportunities by scoring issues on availability, competing PRs, staleness, and maintainer sentiment, including live feasibility checks for any repository.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables developers to discover and evaluate contribution opportunities in public GitHub repositories through structured analysis of issues, code, and repository metadata.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Zero-dependency open-source contribution companion: repo rules and AI policy radar, evidence-backed issue briefs, pre-submit checks, and review coaching.
      9
      39 PyPI
      14
      MIT