github-mcp

quanticsoul4772/github-mcp

3.3

If you are the rightful owner of github-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A comprehensive Model Context Protocol (MCP) server for GitHub integration, enabling AI assistants to interact with GitHub repositories, issues, pull requests, actions, and more.

Tools
5
Resources
0
Prompts
0

GitHub MCP Server

A comprehensive Model Context Protocol (MCP) server for GitHub integration, enabling AI assistants to interact with GitHub repositories, issues, pull requests, actions, and more.

Features

This MCP server provides comprehensive GitHub integration with 100+ tools organized into specialized modules:

Repository Management

  • Browse and search repositories
  • Get file contents and directory listings
  • Create, update, and delete files
  • Manage branches, tags, and releases
  • Fork repositories
  • Search code across GitHub
  • Batch operations for efficiency

Issues & Pull Requests

  • List, create, and update issues
  • Manage issue comments and labels
  • Create and review pull requests
  • Merge pull requests with various strategies
  • Get PR diffs and files
  • Search issues and PRs
  • Automated PR review workflows

GitHub Actions

  • List and trigger workflows
  • Monitor workflow runs with real-time status
  • Get job logs and artifacts
  • Manage secrets and variables
  • Cancel and rerun workflows
  • Download and manage artifacts

Security & Compliance

  • Code scanning alerts and SARIF uploads
  • Secret scanning alerts and management
  • Dependabot vulnerability alerts
  • Security advisories and policy enforcement
  • Branch protection rules
  • Security settings management

Organizations & Users

  • Search users and organizations
  • Manage organization members and teams
  • List user repositories and activity
  • Follow/unfollow users
  • Update profiles
  • Team collaboration features

Notifications & Discussions

  • List and manage notifications
  • Watch/unwatch repositories
  • Create and participate in discussions
  • Manage discussion comments
  • Thread subscriptions

Performance Features

  • Smart Caching: LRU cache with TTL for API responses
  • Request Deduplication: Prevents duplicate concurrent API calls
  • Batch Operations: Process multiple items efficiently
  • Streaming Pagination: Memory-efficient handling of large datasets
  • Circuit Breaker: Prevents cascading failures
  • Rate Limit Management: Proactive rate limit tracking

GraphQL-Powered Features

  • GitHub Discussions: Full discussion management with GraphQL
  • Projects V2: Advanced project management and tracking
  • Repository Insights: Comprehensive repository analytics and statistics
  • Advanced Search: Enhanced search with nested data and relationships
  • Custom Field Queries: Efficient data fetching with field selection

Deployment

The GitHub MCP Server supports multiple deployment options:

Quick Start with Docker

# Clone the repository
git clone https://github.com/quanticsoul4772/github-mcp.git
cd github-mcp

# Set up environment
echo "GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here" > .env

# Run with Docker Compose
docker-compose up -d

Kubernetes Deployment

# Deploy to Kubernetes
kubectl apply -f k8s/

# Configure secrets
kubectl create secret generic github-mcp-secrets \
  --from-literal=GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here \
  -n github-mcp

Available Deployment Options

  • Docker: Production-ready containerized deployment
  • Kubernetes: Scalable orchestrated deployment with auto-scaling
  • Cloud Platforms: AWS EKS, Google GKE, Azure AKS
  • CI/CD: GitHub Actions for automated deployments
  • Monitoring: Prometheus metrics and health checks

For detailed deployment instructions, see .

Installation

Prerequisites

  • Node.js 18.0.0 or later
  • npm 8.0.0 or later
  • GitHub Personal Access Token with appropriate scopes
  1. Clone the repository:
git clone https://github.com/quanticsoul4772/github-mcp.git
cd github-mcp
  1. Install dependencies:
npm install
  1. Build the project:
npm run build
  1. Set up environment variables:
cp .env.example .env

Edit .env and add your GitHub Personal Access Token:

GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

Configuration

Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "--expose-gc",
        "--max-semi-space-size=64",
        "/Users/russellsmith/Projects/mcp-servers/github-mcp/build/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here",
        "NODE_OPTIONS": "--max-old-space-size=4096 --expose-gc --max-semi-space-size=64"
      },
      "type": "stdio"
    }
  }
}

Environment Variables

  • GITHUB_PERSONAL_ACCESS_TOKEN or GITHUB_TOKEN - Required: Your GitHub PAT
  • GITHUB_HOST or GITHUB_API_URL - Optional: Custom GitHub API endpoint (for GitHub Enterprise)
  • GITHUB_READ_ONLY - Optional: Set to 1 or true to enable read-only mode
  • GITHUB_TOOLSETS - Optional: Comma-separated list of toolsets to enable (default: all)
  • GITHUB_DYNAMIC_TOOLSETS - Optional: Set to 1 or true for dynamic toolset discovery

Available Toolsets

You can enable specific toolsets using the GITHUB_TOOLSETS environment variable:

  • context - User context tools (get_me)
  • repos - Repository management tools
  • issues - Issue management tools
  • pull_requests - Pull request tools
  • actions - GitHub Actions tools
  • code_security - Code scanning and security tools
  • users - User management tools
  • orgs - Organization tools
  • notifications - Notification management
  • discussions - Discussion tools (GraphQL-powered)
  • dependabot - Dependabot alerts and settings
  • secret_protection - Secret scanning tools
  • graphql_insights - Advanced repository insights via GraphQL
  • project_management - GitHub Projects V2 management via GraphQL
  • advanced_search - Enhanced search capabilities via GraphQL

Example: GITHUB_TOOLSETS="repos,issues,pull_requests"

To enable all toolsets: GITHUB_TOOLSETS="all"

Read-Only Mode

To run the server in read-only mode (prevents any write operations):

GITHUB_READ_ONLY=1 npm start

GraphQL Tools

This server includes powerful GraphQL-based tools that provide advanced functionality beyond REST APIs:

When to Use GraphQL vs REST

Use GraphQL Tools For:

  • GitHub Discussions (only available via GraphQL)
  • GitHub Projects V2 (GraphQL-only feature)
  • Complex repository insights and analytics
  • Advanced search with nested relationships
  • Efficient data fetching with custom field selection

Use REST Tools For:

  • Simple CRUD operations on issues, PRs, and files
  • GitHub Actions workflow management
  • Basic repository operations
  • When REST endpoints provide sufficient functionality

GraphQL Performance Benefits

  • Reduced API Calls: Fetch related data in single requests
  • Bandwidth Efficiency: Query only the fields you need
  • Advanced Features: Access to GraphQL-exclusive GitHub features
  • Real-time Capabilities: Better support for live data and subscriptions

GraphQL-Specific Configuration

# GraphQL toolsets
GITHUB_TOOLSETS="discussions,graphql_insights,project_management,advanced_search"

# GraphQL performance settings
GITHUB_ENABLE_GRAPHQL_CACHE=true
GITHUB_GRAPHQL_TIMEOUT=30000
GITHUB_GRAPHQL_MAX_COMPLEXITY=1000

For detailed GraphQL tools documentation, see .

Creating a GitHub Personal Access Token

  1. Go to GitHub Settings > Developer settings > Personal access tokens
  2. Click "Generate new token (classic)"
  3. Select the following scopes based on your needs:
    • repo - Full control of repositories
    • workflow - Update GitHub Action workflows
    • write:packages - Upload packages to GitHub Package Registry
    • delete:packages - Delete packages from GitHub Package Registry
    • admin:org - Full control of organizations
    • admin:public_key - Full control of public keys
    • admin:repo_hook - Full control of repository hooks
    • gist - Create gists
    • notifications - Access notifications
    • user - Update user profile
    • write:discussion - Write discussions
    • project - Full control of projects
    • delete_repo - Delete repositories

Tool Reference

For detailed information about all available tools and their parameters, see:

  • - Complete list of tools with examples
  • - Upgrading from previous versions
  • - Configuration for Claude Desktop

Quick Examples

// Get an issue
{
  "owner": "quanticsoul4772",
  "repo": "github-mcp",
  "issue_number": 42
}

// Search repositories
{
  "q": "language:typescript mcp",
  "sort": "stars",
  "order": "desc"
}

// Create a pull request
{
  "owner": "quanticsoul4772",
  "repo": "github-mcp",
  "title": "Feature: Add new functionality",
  "head": "feature-branch",
  "base": "main",
  "body": "Description of changes"
}

Usage

Once configured, the GitHub MCP server will be available in Claude Desktop. You can use natural language to interact with GitHub:

Example Commands

  • "List my recent pull requests"
  • "Show me the README file from owner/repo"
  • "Create an issue in my project repository"
  • "Search for TypeScript files containing 'async'"
  • "Get the status of my latest workflow run"
  • "Show me open Dependabot alerts"
  • "List discussions in the repository"

GraphQL-Powered Examples

  • "Get comprehensive repository insights and contributor statistics"
  • "Search for discussions across all my repositories"
  • "Show me Projects V2 boards and their items"
  • "Find code with advanced search including author and file context"
  • "Get detailed analytics on issue resolution patterns"

Development

Running in Development Mode

npm run dev

Building

npm run build

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test suites
npm run test:unit        # Unit tests only
npm run test:integration # Integration tests only
npm run test:performance # Performance tests

# Watch mode for development
npm run test:watch

Code Quality

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Formatting
npm run format
npm run format:check

# Full quality check
npm run quality:check

Security Scanning

# Security audit
npm run security:scan

# Secret detection
npm run security:secrets

Documentation

Getting Started

  • - Get running in 5 minutes
  • Installation Guide - Detailed setup instructions
  • - All configuration options

Development

  • - Testing strategy and instructions
  • - Guide for Claude Code development
  • - How to contribute

Reference

  • - Complete tool documentation
  • - Upgrading from previous versions
  • - Performance optimization
  • - Common issues and solutions

Advanced Topics

  • - GraphQL-specific features
  • - Production deployment
  • - Security best practices
  • - Code analysis agents

API Documentation

  • - Complete API documentation
  • - Usage examples and patterns

Resources

The server provides these MCP resources:

  • github://repositories - Browse your GitHub repositories
  • github://user - Get current authenticated user information

Prompts

The server includes helpful prompts for common workflows:

  • create_issue - Template for creating GitHub issues
  • review_pr - Template for reviewing pull requests

Security Considerations

  • Never commit your .env file - It contains sensitive tokens
  • Use minimal required scopes - Only grant the permissions you need
  • Rotate tokens regularly - Update your PAT periodically
  • Use read-only mode - When only browsing is needed
  • Store tokens securely - Use environment variables or secure key management

Troubleshooting

Common Issues

  1. Authentication Failed

    • Verify your GitHub token is valid
    • Check token has required scopes
    • Ensure token is not expired

  2. Rate Limiting

    • GitHub API has rate limits
    • Authenticated requests: 5,000 per hour
    • Consider caching or batching requests

  3. Permission Errors

    • Check repository permissions
    • Verify organization access
    • Some features require admin rights

  4. GraphQL Errors

    • Query Complexity: Reduce query complexity or add pagination
    • Discussions: Repository must have discussions enabled
    • Projects V2: Requires project scope and project access
    • Rate Limits: GraphQL has different rate limiting (5,000 points/hour)
    • Permissions: Some GraphQL features need specific scopes

What's New

See for recent updates and version history.

License

MIT - See file for details.

Contributing

Contributions are welcome! Please read our for details on our code of conduct and the process for submitting pull requests.

Support

Acknowledgments