GitHub MCP Scoped Server

A Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to GitHub repositories, issues, pull requests, and more - scoped to a specific user or organization.

🚀 Features

• 🎯 User/Organization Scoped: Focus on specific GitHub user or organization
• ⚡ Ultra-Fast Data Retrieval: Optimized GraphQL and REST API usage for maximum performance
• 📊 Comprehensive Repository Analytics: Get commit counts, contributor stats, language analysis with efficient APIs
• 🔍 Bulk Repository Analysis: Analyze and rank all repositories by commits, stars, forks, activity
• 📈 Advanced Repository Statistics: Contributors, languages, traffic, releases, branches, tags
• 🔄 Repository Comparison: Compare multiple repositories across various metrics
• 📚 Complete API Coverage: Repositories, Issues, Pull Requests, Actions, Security, Notifications, Discussions, Gists
• 🧠 Intelligent Pagination: Smart response limiting with auto-fetching guidance for AI agents
• 📝 Data Citations: Every response includes API endpoint, timestamp, and source context
• ✍️ Write Operations: Create/update issues, create/merge pull requests, manage repositories
• 🚀 NPX Ready: Install and run instantly with npx
• 🐳 Docker Support: Deploy as a container
• 🤖 LibreChat Compatible: Works seamlessly with LibreChat and other MCP clients
• ⚡ Rate Limit Optimization: Smart API usage with rate limit monitoring and recommendations

📦 Installation & Usage

Quick Start with NPX

# Install and run (replace with your credentials)
npx github-mcp-scoped-server --token YOUR_GITHUB_TOKEN --user YOUR_USERNAME

# For organizations
npx github-mcp-scoped-server --token YOUR_GITHUB_TOKEN --org YOUR_ORG_NAME

# With debug logging
npx github-mcp-scoped-server --token YOUR_TOKEN --user YOUR_USER --debug

Environment Variables

Create a .env file:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_TARGET_USER=your-username
# OR
GITHUB_TARGET_ORG=your-org-name

Then run without arguments:

npx github-mcp-scoped-server

🔧 LibreChat Configuration

Add to your LibreChat librechat.yaml:

mcpServers:
  github:
    command: "npx"
    args: 
      - "-y"
      - "github-mcp-scoped-server"
    env:
      GITHUB_TOKEN: "ghp_your_token_here"
      GITHUB_TARGET_USER: "your-username"
    chatMenu: true
    startup: true
    timeout: 60000
    initTimeout: 30000
    serverInstructions: |
      Enhanced GitHub MCP server with ultra-fast repository analytics and comprehensive GitHub access.
      
      KEY FEATURES FOR AI AGENTS:
      - ⚡ Ultra-fast repository analytics (50x-100x faster than traditional methods)
      - 📊 Bulk repository analysis: analyze_all_repositories for finding top repos
      - 📈 Repository comparison: compare_repositories for head-to-head analysis  
      - 🎯 Comprehensive statistics: get_repository_statistics with all metrics
      
      AGENT GUIDANCE:
      - Use analyze_all_repositories to answer "which repo has most X" questions
      - Use get_repository_statistics for detailed single-repo analysis
      - Use compare_repositories for comparing multiple repositories
      - Responses limited to 20 items by default to prevent overflow
      - Look for "🤖 AGENT NOTE" messages for auto-fetching instructions
      - Continue fetching pages until results.length < per_page
      - Use --per_page 50-100 for efficient bulk operations

🛠️ Available Tools

🏠 Context & Authentication

• get_me - Get authenticated user information and GitHub context
• get_target_info - Get information about the target user/organization
• get_rate_limit - Monitor GitHub API rate limits with optimization recommendations
• get_user_teams - Get teams for authenticated user (organizations)
• get_user_permissions - Check permissions and access levels

📂 Repository Management

• list_repositories - List user/org repositories with intelligent pagination
• get_repository - Get detailed repository information
• search_repositories - Search repositories with advanced GitHub search syntax
• list_branches - List repository branches
• get_file_content - Read file contents with binary detection
• list_commits - List repository commits with pagination
• get_commit - Get detailed commit information with diff support
• search_code - Search code within repositories
• list_tags - List repository tags
• list_releases - List repository releases
• get_latest_release - Get latest repository release

📊 Advanced Repository Analytics

• get_repository_statistics - ⚡ Fast comprehensive repo stats (commits, contributors, issues, PRs, languages, traffic)
• analyze_all_repositories - 🔥 Bulk analysis of all repositories with ranking by any metric
• compare_repositories - 📈 Head-to-head comparison of multiple repositories across metrics
• Supported Metrics: commits, contributors, stars, forks, issues, pull_requests, releases, branches, tags, languages, watchers
• Efficient APIs: Uses GraphQL and optimized REST endpoints for fastest data retrieval

🐛 Issues

• list_issues - List issues in repo or across all repos
• get_issue - Get specific issue details
• create_issue - Create new issue ✍️
• update_issue - Update existing issue ✍️

🔄 Pull Requests

• list_pull_requests - List pull requests
• get_pull_request - Get PR details
• create_pull_request - Create new PR ✍️
• get_pull_request_files - Get files changed in PR
• merge_pull_request - Merge pull request ✍️

⚡ GitHub Actions

• list_workflow_runs - List workflow runs
• get_workflow_run - Get specific run details
• list_workflow_jobs - List jobs in a workflow run

🔒 Security & Compliance

• list_code_scanning_alerts - Code scanning results
• list_secret_scanning_alerts - Secret scanning results
• list_dependabot_alerts - Dependabot security alerts

🔔 Notifications

• list_notifications - List GitHub notifications
• mark_notification_read - Mark notification as read

💬 Discussions

• list_discussions - List repository discussions

📝 Gists

• list_user_gists - List user's gists
• get_gist - Get specific gist
• create_gist - Create new gist ✍️

👥 Users & Organizations

• get_user_followers - List user followers
• get_user_following - List users being followed
• list_org_members - List organization members (org scope)
• list_org_teams - List organization teams (org scope)

🏆 Official GitHub MCP Server Compatibility

This implementation follows the same patterns as the official GitHub MCP Server with these enhancements:

✨ Enhanced Features:

• 🚀 Performance Optimized: 50x-100x faster repository analytics
• 📊 Bulk Analysis: Analyze all repositories at once
• 📈 Advanced Statistics: Comprehensive metrics with efficient API usage
• 🎯 AI Agent Optimized: Responses designed for AI comprehension
• 🔍 Repository Comparison: Head-to-head repository analysis

📚 Complete Toolset Coverage:

• Context Tools: User authentication and permissions
• Repository Tools: Complete CRUD operations with advanced analytics
• Issues & PRs: Full lifecycle management
• Actions & CI/CD: Workflow monitoring and management
• Security: Code scanning, secret scanning, Dependabot alerts
• Notifications: GitHub notification management
• Discussions: Repository discussions access
• Gists: Personal code snippets management
• Users & Organizations: Team and membership management

🔑 GitHub Token Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate new token (classic) with these scopes:
   • repo (Full repository access)
   • read:org (Read organization data)
   • read:user (Read user profile data)
   • notifications (Access notifications)
   • gist (Create/read/update/delete gists)
   • workflow (GitHub Actions access)
   • security_events (Security alerts access)

🐳 Docker Deployment

# Clone and setup
git clone <your-repo>
cd github-mcp-scoped-server

# Create environment file
cp .env.example .env
# Edit .env with your credentials

# Deploy with Docker Compose
docker-compose up -d

# Or build and run manually
npm run docker:build
docker run --env-file .env github-mcp-scoped-server:latest --token $GITHUB_TOKEN --user $GITHUB_USER

⚡ Performance & Efficiency Optimizations

🚀 Ultra-Fast Repository Analytics

Our repository statistics tools use the most efficient GitHub API methods:

• GraphQL Queries: Single request for multiple data points (commits, issues, PRs, releases)
• Compare API: Get commit counts instantly without pagination (vs 100+ API calls for large repos)
• Contributors API: Aggregate commit statistics efficiently
• Smart Method Selection: Automatically chooses fastest available method

📈 Speed Comparison

Traditional Approach (paginating through commits):

• Large repo with 10,000 commits = 100+ API calls
• Rate limited and slow
• High API usage

Our Optimized Approach:

• Same repo = 1-2 API calls using GraphQL/Compare API
• 50x-100x faster
• Minimal rate limit impact

🎯 API Method Intelligence

# This uses optimized GraphQL (1 API call)
get_repository_statistics --repo large-project --metrics commits,issues,pull_requests

# This uses efficient bulk analysis (1-2 calls per repo)
analyze_all_repositories --sort_by commits --metrics basic,commits

📊 Intelligent Pagination

The server automatically limits responses to 20 items to prevent AI model overflow, while providing intelligent guidance:

Example Response:

{
  "repositories": [
    // ... 20 repositories
  ]
}

📊 Showing 20 results (page 1).
🔄 Likely more results available. Try: list_repositories --page 2
🤖 AGENT NOTE: Continue fetching pages until you get fewer results than per_page limit.
📄 Parameters: --page <number> --per_page <number> (current: 20, max: 100)

For AI Agents:

• Automatic Detection: Agents can detect when more pages exist
• Efficient Fetching: Use --per_page 50-100 for bulk operations
• Stop Condition: Stop when results.length < per_page
• Safety Limits: Maximum 100 items per page, 50 pages total

📚 Data Citations & Transparency

Every response includes detailed source information:

📚 DATA SOURCE:
🔗 API Endpoint: GET /users/codevakure/repos
👤 Target: user/codevakure
⏰ Retrieved: 2025-09-21T15:45:32.123Z
📝 Context: Repository list for user codevakure

Benefits:

• 🔍 Transparency: See exactly which GitHub API was called
• 🕒 Data Freshness: Timestamp shows when data was retrieved
• 📍 Source Context: Clear indication of target and resource
• 🔗 Verification: Users can check the API endpoint directly
• 🤖 AI Trust: Agents understand data sources and reliability

✍️ Write Operations

The server supports GitHub write operations with proper authentication:

Create Issue:

create_issue --repo my-repo --title "Bug report" --body "Description" --labels bug,urgent

Create Pull Request:

create_pull_request --repo my-repo --title "Feature X" --head feature-branch --base main --body "PR description"

Merge Pull Request:

merge_pull_request --repo my-repo --pull_number 123 --merge_method squash

🚨 Troubleshooting

Common Issues:

1. "Cannot access GitHub user"

   • Check token validity and permissions
   • Ensure token has required scopes
   • Verify username/org name is correct

2. "Input is too long for model"

   • Use pagination parameters: --page 1 --per_page 20
   • Server automatically limits to 20 items by default

3. Connection timeout

   • Increase timeout in MCP client configuration
   • Check network connectivity to GitHub API

Debug Mode:

npx github-mcp-scoped-server --token YOUR_TOKEN --user YOUR_USER --debug

📋 Examples

🚀 Quick Repository Insights:

# Find repository with most commits (answers: "Which repo has the highest commits?")
analyze_all_repositories --sort_by commits --top_n 5

# Get comprehensive stats for a specific repository
get_repository_statistics --repo my-project --metrics all

# Compare repositories head-to-head
compare_repositories --repos "repo1,repo2,repo3" --metrics "commits,stars,contributors"

📊 Advanced Repository Analytics:

# Find most active repositories by commits
analyze_all_repositories --sort_by commits --metrics "commits,contributors" --top_n 10

# Find repositories with most stars
analyze_all_repositories --sort_by stars --include_empty false --min_threshold 10

# Get detailed repository statistics including traffic data
get_repository_statistics --repo my-project --metrics "commits,contributors,issues,pull_requests,languages,traffic"

# Compare development activity across projects
compare_repositories --repos "frontend,backend,mobile" --metrics "commits,contributors,pull_requests,releases"

🔍 Repository Discovery:

# List repositories with intelligent pagination
list_repositories --per_page 50

# Search for repositories
search_repositories --query "language:typescript stars:>100" --sort stars --order desc

# Get specific repository details
get_repository --repo my-project

# Search code across repositories
search_code --query "function handleAuth" --per_page 30

Issue Management:

# List open issues
list_issues --repo my-project --state open

# Create new issue
create_issue --repo my-project --title "Feature request" --body "Add dark mode support"

# Update issue
update_issue --repo my-project --issue_number 42 --state closed

🔄 Pull Request Workflow:

# List open PRs
list_pull_requests --repo my-project --state open

# Get PR details and files
get_pull_request --repo my-project --pull_number 15
get_pull_request_files --repo my-project --pull_number 15

# Merge PR
merge_pull_request --repo my-project --pull_number 15 --merge_method squash

⚡ Performance Optimization:

# Check current rate limits and get optimization recommendations
get_rate_limit

# Use efficient bulk operations
analyze_all_repositories --metrics "basic,commits" --sort_by updated

# Get repository stats with specific metrics only (faster)
get_repository_statistics --repo my-project --metrics "commits,contributors,stars"

🎯 AI Agent Optimization:

The tools are specifically designed for AI agents with intelligent responses:

# AI Agent: "Which repository has the most commits?"
analyze_all_repositories --sort_by commits --top_n 1
# Returns: Winner with commit count and comprehensive comparison

# AI Agent: "Compare these three repositories"
compare_repositories --repos "repo1,repo2,repo3"
# Returns: Side-by-side comparison with insights and recommendations

# AI Agent: "Get detailed stats for this repository"
get_repository_statistics --repo target-repo --metrics all
# Returns: Complete repository analytics dashboard

🔗 Links

• NPM Package: https://www.npmjs.com/package/github-mcp-scoped-server
• GitHub Repository: https://github.com/github/github-mcp-server
• MCP Protocol: https://modelcontextprotocol.io/
• LibreChat: https://librechat.ai/

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Made with ❤️ for the AI community