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"

Related MCP server: ship-it-mcp

Tools

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:

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