🐙 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 limitX-RateLimit-Remaining- Requests leftX-RateLimit-Reset- Reset timestampRetry-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 repositoriesread:org- Read organization dataadmin: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.0httpx>=0.24.0python-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 ⭐!