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

$3

``bash

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
`

$3

Create a .env file:
`bash
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GITHUB_TARGET_USER=your-username

OR

GITHUB_TARGET_ORG=your-org-name
`

Then run without arguments:
`bash
npx github-mcp-scoped-server
`

🔧 LibreChat Configuration

Add to your LibreChat librechat.yaml:

`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

$3

- 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

$3

- 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

$3

- 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

$3

- 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 ✍️

$3

- 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 ✍️

$3

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

$3

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

$3

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

$3

- list_discussions - List repository discussions

$3

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

$3

- 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:

$3

- 🚀 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

$3

- 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

`bash

Clone and setup

git clone
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

$3

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

$3

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

$3

`bash

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:

$3

`
{
"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 --per_page (current: 20, max: 100)
`

$3

- 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
`

$3

- 🔍 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:

$3

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

$3

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

$3

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

🚨 Troubleshooting

$3

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

$3

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

📋 Examples

$3

`bash

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"
`

$3

`bash

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"
`

$3

`bash

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
`

$3

`bash

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
`

$3

`bash

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
`

$3

`bash

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"
`

$3

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

`bash

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