🐙 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)
⚙️ Workflows & Actions (2 Tools)
🛠️ Utilities (2 Tools)
🚀 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
3. Run the Server
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
✅ Security
✅ Monitoring & Debugging
Rate limit tracking
Request/response logging
Server health status
Detailed tool statistics
✅ Data Quality
🐳 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:
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
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:
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
⭐ Star History
If this project helps you, please consider giving it a ⭐!
