GitHub Portfolio Intelligence MCP Server

A custom MCP server that gives Claude deep analysis superpowers over GitHub repositories.

What It Does

Expose 5 MCP tools so Claude can answer questions like:

• "Analyze this repo's code quality and tell me what's missing for production readiness"
• "Which contributor is most active and what areas do they own?"
• "What are the most common bug patterns from the last 30 issues?"
• "Generate a technical README for this repo based on the actual code"
• "Compare these two repos and tell me which is better architected"

Tools

Tool	Description
get_repo_summary	Stars, forks, languages, topics, last commit date
get_recent_commits	Last N commits with author, message, files changed
get_open_issues	Open issues with labels, comment count, age
get_contributors	Contributor stats, commit counts, top files per person
analyze_code_quality	Pulls key files, optional LLM analysis, structured quality report

Prerequisites

• Python 3.12+
• uv package manager
• GitHub Personal Access Token (create one here)
• Groq API key (optional, free tier — enables LLM-powered code quality analysis via Groq Console)

Setup

1. Install dependencies

cd "C:\Users\TAHA\GitHub Portfolio Intelligence Server"
uv sync

2. Configure environment

copy .env.example .env

Edit .env and set your tokens:

GITHUB_TOKEN=ghp_your_token_here
GROQ_API_KEY=gsk_your_key_here

GitHub token scopes: public_repo for public repos, repo for private repos.

3. Test locally

Quick check (verify imports and dependencies):

uv run python -c "import server; print('Server modules OK')"

Interactive testing (opens MCP Inspector in your browser):

uv run mcp dev server.py

Direct run (how Claude Desktop launches it):

uv run python server.py

The server uses stdio transport — it waits silently for JSON-RPC messages from an MCP client. If you press Enter in the terminal, you may see harmless Invalid JSON errors (that's just a blank line hitting stdin). Do not type into the terminal; use MCP Inspector or Claude Desktop instead.

Claude Desktop Integration

Config file location (Windows)

Standard install:

%APPDATA%\Claude\claude_desktop_config.json

MSIX / Windows Store install (config may be ignored if you edit the wrong path):

%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

Open Claude Desktop → Settings → Developer → Edit Config to find the correct file.

Add the server

Merge this into your claude_desktop_config.json (see claude_desktop_config.example.json):

{
  "mcpServers": {
    "github-intelligence": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\TAHA\\GitHub Portfolio Intelligence Server",
        "run",
        "server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

Windows tips:

• Use absolute paths for --directory
• If Claude Desktop can't find uv, use the full path: C:\\Users\\TAHA\\.local\\bin\\uv.exe
• Env vars in the config env block are required — Claude Desktop subprocesses don't read .env
• Fully quit Claude Desktop (tray icon → Quit) after saving config

Verify

After restarting Claude Desktop, you should see github-intelligence in the MCP tools list. Try:

"Use get_repo_summary on microsoft/vscode"

Error Handling

All tools return structured error objects instead of crashing:

Error	Response
Rate limited	{"error": "rate_limited", "reset_at": "..."}
Not found / private	{"error": "not_found", "message": "..."}
Bad token	{"error": "auth_failed", "message": "..."}
Timeout	{"error": "timeout", "message": "..."}

Project Structure

├── server.py                        # FastMCP entry point + 5 tools
├── github_client.py                 # Async GitHub API client
├── claude_desktop_config.example.json
├── .env.example
├── pyproject.toml
└── README.md

License

MIT