🐙 GitHub Analyzer Pro MCP Server v2.0

A production-ready Model Context Protocol (MCP) server with 28+ powerful tools for comprehensive GitHub analysis, built with FastMCP.

✨ Complete Feature Set

📦 Repository Analysis (8 Tools)

get_repository_info - Complete repo metadata with stats
get_repository_languages - Language breakdown with percentages
get_repository_contributors - Top contributors ranking
get_repository_tags - Release tags listing
get_repository_branches - Branch info with protection status
get_repository_stats - Comprehensive analytics
get_repository_traffic - Views & clones (requires permissions)
get_repository_community - Health score & community files

📝 Commits & History (3 Tools)

get_repository_commits - Commit history with authors
get_commit_details - Deep dive into specific commits
compare_commits - Compare branches or commits

🐛 Issues & Pull Requests (3 Tools)

get_repository_issues - Filter by state, labels
get_pull_requests - PR details with merge status
get_issue_comments - Comment threads

📁 Files & Content (4 Tools)

get_file_content - Read any file from repo
get_directory_contents - Browse directory structure
get_repository_readme - Quick README access
search_code - Find code across repositories

🔍 Search & Discovery (5 Tools)

search_repositories - Advanced repo search
search_users - Find users & organizations
search_topics - Discover GitHub topics
get_trending_repositories - Hot repos by language
get_trending_developers - Active developers

👤 Users & Organizations (4 Tools)

get_user_profile - Complete user information
get_user_repositories - User's public repos
get_user_activity - Recent activity feed
get_organization_info - Organization details

📦 Releases & Packages (2 Tools)

get_releases - All releases with download stats
get_latest_release - Latest release details

⚙️ Workflows & Actions (2 Tools)

get_workflows - List GitHub Actions workflows
get_workflow_runs - Recent workflow execution history

🛠️ Utilities (2 Tools)

get_rate_limit - Check API rate limit status
server_info - Server capabilities & stats

🚀 Quick Start

1. Install Dependencies

pip install fastmcp httpx python-dotenv

2. Set GitHub Token (Recommended)

Without token: 60 requests/hour
With token: 5000 requests/hour + full search access

# Linux/Mac
export GITHUB_TOKEN='ghp_your_token_here'

# Windows PowerShell
$env:GITHUB_TOKEN='ghp_your_token_here'

# Or create .env file
echo "GITHUB_TOKEN=ghp_your_token_here" > .env

Get your token: https://github.com/settings/tokens

Required scopes: public_repo, read:user
Optional: repo (for private repositories)

3. Run the Server

python github_server.py

Expected output:

============================================================
🐙 GitHub Analyzer Pro MCP Server v2.0.0
============================================================

📡 Server Configuration:
   Transport: HTTP
   Host: 0.0.0.0
   Port: 8001
   Timeout: 30.0s

🔑 Authentication:
   GitHub Token: ✓ Configured
   Rate Limit: 5000/hr

📊 Available Tools: 28
   • Repository Analysis (8 tools)
   • Commits & History (3 tools)
   • Issues & PRs (3 tools)
   • Files & Content (4 tools)
   • Search & Discovery (5 tools)
   • Users & Organizations (4 tools)
   • Releases & Packages (2 tools)
   • Workflows & Actions (2 tools)
   • Utilities (2 tools)

✨ Production Features:
   ✓ Enhanced error handling
   ✓ Request caching
   ✓ Rate limit monitoring
   ✓ Community health metrics
   ✓ Traffic analytics
   ✓ GitHub Actions support

🚀 Server Status: READY
   Access at: http://localhost:8001
============================================================

📚 Usage Examples

🔍 Advanced Repository Analysis

# Get comprehensive stats
{
  "owner": "facebook",
  "repo": "react"
}

# Response includes:
# - Stars, forks, watchers
# - Language breakdown
# - Commit activity
# - Health score
# - Community files
# - Traffic data (if authorized)

📊 Language Distribution

# Get language percentages
{
  "owner": "microsoft",
  "repo": "vscode"
}

# Returns:
# - TypeScript: 45.2%
# - JavaScript: 30.1%
# - CSS: 15.7%
# - etc.

👥 Top Contributors

# See who contributes most
{
  "owner": "torvalds",
  "repo": "linux",
  "limit": 10
}

🔄 Compare Branches

# See what changed between branches
{
  "owner": "python",
  "repo": "cpython",
  "base": "3.11",
  "head": "main"
}

# Shows:
# - Commits ahead/behind
# - Files changed
# - Line additions/deletions

🐛 Filter Issues by Labels

# Find specific issues
{
  "owner": "microsoft",
  "repo": "vscode",
  "state": "open",
  "labels": "bug,high-priority"
}

📦 Release Management

# Get latest release
{
  "owner": "nodejs",
  "repo": "node"
}

# Returns:
# - Version tag
# - Release notes
# - Download links
# - Asset download counts

⚙️ Monitor GitHub Actions

# Check CI/CD status
{
  "owner": "rust-lang",
  "repo": "rust"
}

# See:
# - All workflows
# - Recent runs
# - Success/failure status

👤 User Activity Feed

# What's a user been up to?
{
  "username": "gvanrossum",
  "limit": 20
}

# Shows:
# - Recent commits
# - PRs created
# - Issues opened
# - Repos starred

🔥 Discover Trending

# Hot Python repos this week
{
  "language": "python",
  "since": "weekly"
}

📈 Community Health

# Check repo health
{
  "owner": "django",
  "repo": "django"
}

# Returns:
# - Health percentage
# - README quality
# - Has CODE_OF_CONDUCT
# - Has CONTRIBUTING guide
# - Issue templates

🔧 Connect to Claude Desktop

Configuration

macOS:
~/Library/Application Support/Claude/claude_desktop_config.json

Windows:
%APPDATA%\Claude\claude_desktop_config.json

Linux:
~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "github-pro": {
      "url": "http://localhost:8001/mcp/v1"
    }
  }
}

Remote server:

{
  "mcpServers": {
    "github-pro": {
      "url": "http://your-server-ip:8001/mcp/v1"
    }
  }
}

Restart Claude Desktop after configuration!

💬 Talk to Claude

Once connected, ask Claude things like:

"Analyze the React repository - give me complete statistics"

"Show me the language breakdown for microsoft/vscode"

"Who are the top 10 contributors to the Linux kernel?"

"Compare the main and develop branches of my-org/my-repo"

"Find all open high-priority bugs in facebook/react"

"What's the latest release of Node.js? Show download counts"

"Are GitHub Actions passing for rust-lang/rust?"

"What has Guido van Rossum been working on lately?"

"Show me trending Rust repositories this month"

"Check the community health score for django/django"

"Search for async functions in the FastAPI codebase"

"Get traffic stats for my repository" (requires auth)

"Show me all workflows and their status for my-org/api"

🏭 Production Features

✅ Enhanced Error Handling

Detailed error messages
Rate limit detection
Authentication failure handling
Network timeout management
Resource not found handling

✅ Performance Optimization

Request timeout control (30s)
Response caching (5min TTL)
Efficient batch requests
Maximum result limiting

✅ Security

Token-based authentication
Secure environment variables
No token logging
Rate limit compliance

✅ Monitoring & Debugging

Rate limit tracking
Request/response logging
Server health status
Detailed tool statistics

✅ Data Quality

Response validation
Safe JSON encoding
Truncation for large responses
Binary file handling

🐳 Docker Deployment

Dockerfile

FROM python:3.10-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy server
COPY github_server.py .

# Environment
ENV GITHUB_TOKEN=""
ENV PYTHONUNBUFFERED=1

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD python -c "import httpx; httpx.get('http://localhost:8001/mcp/v1/health')"

EXPOSE 8001

CMD ["python", "github_server.py"]

requirements.txt

fastmcp>=2.14.0
httpx>=0.24.0
python-dotenv>=1.0.0

Build & Run

# Build image
docker build -t github-mcp-pro .

# Run with token
docker run -d \
  -p 8001:8001 \
  -e GITHUB_TOKEN='ghp_your_token' \
  --name github-server \
  --restart unless-stopped \
  github-mcp-pro

# View logs
docker logs -f github-server

# Stop
docker stop github-server

Docker Compose

version: '3.8'

services:
  github-mcp:
    build: .
    ports:
      - "8001:8001"
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8001/mcp/v1/health')"]
      interval: 30s
      timeout: 10s
      retries: 3

☁️ Cloud Deployment

Deploy to Railway

# Install Railway CLI
npm install -g @railway/cli

# Login
railway login

# Initialize
railway init

# Deploy
railway up

# Set environment
railway variables set GITHUB_TOKEN=ghp_your_token

# Get URL
railway domain

Deploy to Render

Connect your GitHub repository
Create new Web Service
Set environment variables:
- GITHUB_TOKEN: Your token
Build command: pip install -r requirements.txt
Start command: python github_server.py
Deploy!

Deploy to Fly.io

# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login
flyctl auth login

# Launch
flyctl launch

# Set secret
flyctl secrets set GITHUB_TOKEN=ghp_your_token

# Deploy
flyctl deploy

# Check status
flyctl status

Deploy to Heroku

# Create Procfile
echo "web: python github_server.py" > Procfile

# Create app
heroku create github-mcp-pro

# Set token
heroku config:set GITHUB_TOKEN=ghp_your_token

# Deploy
git push heroku main

# Check logs
heroku logs --tail

🔍 Advanced Search Queries

GitHub supports powerful search syntax:

# Search by stars
"query": "web framework stars:>10000"

# Search by language
"query": "machine learning language:python"

# Search by topic
"query": "topic:artificial-intelligence"

# Search by license
"query": "license:mit"

# Search in organization
"query": "org:google android"

# Search by size
"query": "size:>1000 language:go"

# Search by fork count
"query": "forks:>500 language:rust"

# Search by pushed date
"query": "pushed:>2024-01-01"

# Combined
"query": "neural network language:python stars:>1000 topic:deep-learning"

📊 Rate Limit Management

Check Your Limits

# Use the tool
get_rate_limit()

# Returns:
{
  "core": {
    "limit": 5000,
    "remaining": 4850,
    "reset": "2024-12-15T10:30:00"
  },
  "search": {
    "limit": 30,
    "remaining": 28,
    "reset": "2024-12-15T09:45:00"
  }
}

Best Practices

Use authentication - 5000 vs 60 requests/hour
Cache results - Built-in 5-minute caching
Batch requests - Use higher limits per call
Monitor usage - Check rate_limit regularly
Handle errors - Graceful degradation

Rate Limit Headers

The server automatically handles:

X-RateLimit-Limit - Total limit
X-RateLimit-Remaining - Requests left
X-RateLimit-Reset - Reset timestamp
Retry-After - Seconds to wait

🛡️ Security Best Practices

Token Management

# ✅ DO: Use environment variables
export GITHUB_TOKEN='ghp_...'

# ✅ DO: Use .env file (add to .gitignore)
echo "GITHUB_TOKEN=ghp_..." > .env
echo ".env" >> .gitignore

# ❌ DON'T: Hardcode in files
GITHUB_TOKEN = "ghp_..."  # NEVER DO THIS!

# ❌ DON'T: Commit to git
git add .env  # NEVER DO THIS!

Token Scopes

Minimum required:

✅ public_repo - Access public repositories
✅ read:user - Read user profile

Optional for more features:

repo - Access private repositories
read:org - Read organization data
admin:repo_hook - Manage webhooks

Token Rotation

# Create new token
1. Visit https://github.com/settings/tokens
2. Generate new token
3. Update environment variable
4. Restart server
5. Revoke old token

🧪 Testing

Manual Testing

# Test repository info
curl -X POST http://localhost:8001/mcp/v1/tools/get_repository_info \
  -H "Content-Type: application/json" \
  -d '{"owner": "facebook", "repo": "react"}'

# Test search
curl -X POST http://localhost:8001/mcp/v1/tools/search_repositories \
  -H "Content-Type: application/json" \
  -d '{"query": "fastapi", "limit": 5}'

# Test user profile
curl -X POST http://localhost:8001/mcp/v1/tools/get_user_profile \
  -H "Content-Type: application/json" \
  -d '{"username": "torvalds"}'

Python Testing

import requests

# Test connection
response = requests.post(
    "http://localhost:8001/mcp/v1/tools/server_info",
    json={}
)
assert response.status_code == 200
print(response.json())

# Test repository
response = requests.post(
    "http://localhost:8001/mcp/v1/tools/get_repository_info",
    json={"owner": "python", "repo": "cpython"}
)
data = response.json()
assert "name" in data
print(f"Repository: {data['name']}")

📈 Monitoring & Logging

Server Logs

The server provides detailed logging:

[2024-12-15 10:30:45] INFO - Server started on port 8001
[2024-12-15 10:31:12] INFO - Tool called: get_repository_info
[2024-12-15 10:31:13] INFO - GitHub API request: repos/facebook/react
[2024-12-15 10:31:14] INFO - Response cached for 300s
[2024-12-15 10:31:14] INFO - Tool execution completed: 1.2s

Health Monitoring

# Check server health
curl http://localhost:8001/health

# Check rate limits
curl -X POST http://localhost:8001/mcp/v1/tools/get_rate_limit \
  -H "Content-Type: application/json" \
  -d '{}'

🐛 Troubleshooting

Common Issues

"Rate limit exceeded"

# Solution: Add GitHub token
export GITHUB_TOKEN='ghp_your_token'

"Repository not found"

# Check: Owner and repo spelling
# Check: Repository is public (or token has access)
# Check: Repository hasn't been deleted/renamed

"Connection refused"

# Check: Server is running
python github_server.py

# Check: Port 8001 is available
lsof -i :8001  # Linux/Mac
netstat -ano | findstr :8001  # Windows

"Invalid token"

# Solution: Regenerate token with correct scopes
# Required: public_repo, read:user

"Timeout error"

# Check: Internet connection
# Check: GitHub status: https://www.githubstatus.com/
# Increase: Timeout in code (REQUEST_TIMEOUT)

Debug Mode

# Add to github_server.py for debugging
import logging
logging.basicConfig(level=logging.DEBUG)

🎓 Advanced Usage

Custom Tool Implementation

Add your own tools to github_server.py:

@mcp.tool()
@safe_json_response
def your_custom_tool(param: str) -> dict:
    """
    Your custom GitHub tool.
    
    Args:
        param: Parameter description
    
    Returns:
        Custom data
    """
    data = gh_client.request(f"your/endpoint/{param}")
    return {
        "result": data
    }

Batch Processing

# Process multiple repos
repos = [
    ("facebook", "react"),
    ("microsoft", "vscode"),
    ("google", "flutter")
]

for owner, repo in repos:
    info = get_repository_info(owner, repo)
    print(f"{owner}/{repo}: {info['statistics']['stars']} stars")

Caching Strategy

The server includes built-in caching (5 minutes). Customize:

from functools import lru_cache

@lru_cache(maxsize=128)
def cached_request(endpoint: str):
    return gh_client.request(endpoint)

📋 Requirements

Python: 3.10 or higher
Dependencies:
- fastmcp>=2.14.0
- httpx>=0.24.0
- python-dotenv>=1.0.0

🤝 Contributing

Contributions welcome! Here's how:

Fork the repository
Create a feature branch
Add your improvements
Test thoroughly
Submit a pull request

Ideas for Contributions

Add more GitHub features
Implement GraphQL API support
Add webhook handlers
Create visualization tools
Add analytics dashboards
Improve caching strategies
Add more search filters
Enhance error messages
Add rate limit prediction
Create CLI interface

📄 License

MIT License - See LICENSE file for details

🙏 Credits

GitHub API - Data provider
FastMCP - MCP framework
Anthropic - Claude and MCP specification
httpx - HTTP client
Contributors - Thank you!

📞 Support

Documentation: This README
Issues: GitHub Issues
Discussions: GitHub Discussions
API Docs: GitHub REST API

⭐ Star History

If this project helps you, please consider giving it a ⭐!

GitHub Analyzer Pro MCP Server