Skip to content
BranchesTags

Repository files navigation

🔍 GitHub Talent Finder — MCP Server

An MCP (Model Context Protocol) server that lets AI assistants like Claude deeply explore GitHub — find talent, discover trending technologies, analyse repositories, compare developers, inspect CI/CD pipelines, and much more.

📁 Project Structure & File Guide

Every file in this project has a specific job. Here is what each one does and when it matters:

github-talent-finder-mcp/
├── mcp_server.py          ← Entry point. Registers all 9 tools into one MCP server.
├── requirements.txt       ← Python packages needed to run the server.
├── pyproject.toml         ← Project metadata for packaging and distribution.
├── .env.example           ← Template showing which environment variables are needed.
├── .env                   ← Your actual secrets (NOT committed to git).
├── .gitignore             ← Tells git which files to never upload (e.g. .env).
├── tools/
│   ├── talent.py          ← Search GitHub users by role/location. Find top repos by topic.
│   ├── trending.py        ← Discover which languages and topics are trending right now.
│   ├── repos.py           ← Deep-dive any repo. See commit history and who's contributing.
│   ├── users.py           ← Compare two GitHub profiles side-by-side.
│   ├── orgs.py            ← Explore company organisations (Google, OpenAI, Meta, etc).
│   └── devops.py          ← Browse issues, pull requests, and GitHub Actions workflows.
└── utils/
    └── github.py          ← Shared API client. All tools use this to talk to GitHub.

mcp_server.py — The Entry Point

What it does: This is the only file you ever run. It creates the FastMCP server and registers all 9 tools from the tools/ folder. It is intentionally kept small — around 20 lines — so it is easy to see everything the server offers at a glance.

How to use it:

python mcp_server.py

When to edit it: Only when you add a brand new tool module. You import the function and register it with mcp.tool().

utils/github.py — Shared GitHub API Client

What it does: Contains the shared HEADERS (including your GITHUB_TOKEN) and a gh_get() helper function that all tool modules use. This means the token and headers are set in exactly one place — if you need to update them, you only change one file.

When to edit it: If you want to add authentication scopes, change the API version, or add request retries/logging.

tools/talent.py — Find Developers & Projects

What it does: Provides two tools:

  • search_github_talent — Searches GitHub user bios for people with specific job roles, filtered by location.
  • search_github_projects — Finds the most-starred repositories for any topic or technology.

Example prompts to try with Claude:

"Find me 5 machine learning engineers based in India on GitHub."

"Search GitHub for the top 10 Python repositories about large language models."

"Who are some prominent React developers based in San Francisco?"

tools/trending.py — Trending Technologies

What it does: Analyses recently created repositories with high star counts to tell you which programming languages and topics are gaining momentum. Returns a ranked list of languages, hot topics, the trending repos themselves, and a one-line insight summary.

Example prompts to try with Claude:

"What programming languages are developers using the most this week on GitHub?"

"Which topics are trending on GitHub right now — give me the daily view."

"What are people building on GitHub this month? Show me the hottest technologies."

tools/repos.py — Repository Analysis & Commit Activity

What it does: Provides two tools:

  • analyze_repository — Full breakdown of any public repo: stars, forks, open issues, language breakdown, top 5 contributors, and the 5 most recent commits.
  • get_commit_activity — Shows recent commits, who is committing the most, and weekly activity statistics for any repo.

Example prompts to try with Claude:

"Give me a full analysis of the facebook/react repository."

"How active is the pytorch/pytorch repo? Show me recent commits and weekly stats."

"Who are the top contributors to the microsoft/vscode repository?"

"Analyse openai/whisper — I want to know the language breakdown and last commit dates."

tools/users.py — Compare GitHub Profiles

What it does: Fetches full profiles for two GitHub users and compares them side-by-side — followers, public repos, top languages they use, and their most-starred repositories. Returns a plain-English verdict on who leads in each category.

Example prompts to try with Claude:

"Compare torvalds and gvanrossum on GitHub — who is more active?"

"I want to compare two developers: yoheinakajima and karpathy. Which one has more followers and what languages do they use?"

"Compare the GitHub profiles of antirez and dhh."

tools/orgs.py — Explore GitHub Organisations

What it does: Fetches an organisation's profile, their top public repositories sorted by stars, the primary languages used across their repos, and a sample of their public members.

Example prompts to try with Claude:

"What open-source projects does OpenAI maintain on GitHub?"

"Explore the Google GitHub organisation — what are their most popular repos?"

"What programming languages does Meta primarily use across their GitHub repos?"

"Show me Microsoft's top 10 GitHub repositories by stars."

tools/devops.py — Issues, Pull Requests & CI/CD

What it does: Provides two tools:

  • get_repo_issues_and_prs — Lists open (or closed) issues and pull requests for any repo. Shows title, author, labels, comment count, and URL.
  • check_github_actions — Inspects a repo's GitHub Actions workflows, showing each workflow's name, active state, and the result of its most recent run (passed, failed, in progress).

Example prompts to try with Claude:

"What bugs are currently open in the microsoft/vscode repository?"

"Show me the most recent pull requests in the vercel/next.js repo."

"Does the facebook/react repository have CI/CD set up? Did the last build pass?"

"List all open issues in the django/django repo that have the 'bug' label."

requirements.txt — Python Dependencies

What it does: Lists the two packages needed: mcp[cli] (the MCP framework) and requests (for HTTP calls to GitHub). Run pip install -r requirements.txt once after cloning to install everything.

.env.example & .env — Environment Variables

What they do: .env.example is a safe template committed to git showing what variables are needed. .env is your actual file with real secrets — it is listed in .gitignore so it is never accidentally uploaded to GitHub.

Variables:

GITHUB_TOKEN=your_token_here

Without a token the server still works but GitHub rate-limits you to 10 requests/minute. With a token it is 30/minute.

.gitignore — Git Safety Net

What it does: Prevents sensitive or unnecessary files from ever being committed. Key entries: .env (your secrets), __pycache__/ (Python bytecode), .venv/ (virtual environment), dist/ and build/ (packaging artifacts).

🚀 Quickstart

# 1. Clone
git clone https://github.com/YOUR_USERNAME/github-talent-finder-mcp.git
cd github-talent-finder-mcp

# 2. Virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install
pip install -r requirements.txt

# 4. Configure token
cp .env.example .env
# Edit .env and paste your GitHub token

# 5. Run
python mcp_server.py

🔧 Connect to Claude Desktop

Add this block to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github-talent-finder": {
      "command": "python",
      "args": ["/absolute/path/to/github-talent-finder-mcp/mcp_server.py"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

Restart Claude Desktop after saving. All 9 tools will be available immediately.

🌐 Hosting & Deployment

This server supports two transport modes: stdio (default for local use) and sse (HTTP-based for remote hosting).

1. Hosted via SSE (HTTP)

To run the server as a web service (e.g., on a VPS or cloud provider):

# Run the server using the MCP CLI
mcp run mcp_server.py --transport sse

The server will now listen for HTTP connections on port 8000.

2. Hosted via Docker

To deploy using a container (recommended for production):

# Build the image
docker build -t github-mcp-server .

# Run the container (pass your token as an environment variable)
docker run -p 8000:8000 \
  -e GITHUB_TOKEN=your_token_here \
  github-mcp-server

🛠️ All 9 Tools at a Glance

Tool File Best Example Prompt
search_github_talent tools/talent.py "Find 5 MLOps engineers based in Germany."
search_github_projects tools/talent.py "Top 5 TypeScript repos for building CLI tools."
get_trending_technologies tools/trending.py "What tech is trending on GitHub this week?"
analyze_repository tools/repos.py "Full analysis of the langchain-ai/langchain repo."
get_commit_activity tools/repos.py "How active is huggingface/transformers this month?"
compare_github_users tools/users.py "Compare karpathy vs yoheinakajima on GitHub."
explore_github_organization tools/orgs.py "What repos does the Hugging Face org have?"
get_repo_issues_and_prs tools/devops.py "Open bugs in the ansible/ansible repository."
check_github_actions tools/devops.py "Is CI passing on the remix-run/remix repo?"

⚠️ Rate Limits

Auth Requests / Minute
No token 10
With GITHUB_TOKEN 30

🤝 Adding a New Tool

  1. Create a new file in tools/, e.g. tools/stars.py
  2. Write your function with a proper docstring (FastMCP uses it as the tool description)
  3. Import and register it in mcp_server.py:
from tools.stars import get_starred_repos
mcp.tool()(get_starred_repos)
  1. Restart the server — Claude will see the new tool automatically.

📄 License

MIT — free to use, modify, and share.

About

Plug this MCP server into Claude Desktop or Cursor so your AI can actively explore GitHub profiles, code activity, and developer rankings in real time.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages