A Model Context Protocol (MCP) server that provides tools for interacting with the GitHub API. This server allows LLM agents manage GitHub repositories, issues, pull requests, branches, files, and releases through a standardized interface.

• Overview
  • Architecture & Components
• Features
  • Repository Management
  • Branch Management
  • Issue Management
  • Pull Request Management
  • File Management
  • Release Management
• Installation
  • Prerequisites
  • Setup
• Configuration
• Project Structure
• Tools
  • Repository Management Tools
  • Branch Management Tools
  • Issue Management Tools
  • Pull Request Management Tools
  • File Management Tools
  • Release Management Tools
• Development
  • Project Structure
  • Scripts
• Error Handling
• Contributing
• License

github-mcp-server implements the Model Context Protocol (MCP), enabling standardized communication between LLMs and external systems through:

• Clients: Claude Desktop, IDEs, and other MCP-compatible clients
• Servers: Tools and resources for project management and collaboration
• LLM Agents: AI models that leverage the ability to perform GitHub operations programmatically.

It acts as a bridge between AI models and the GitHub API, offering a set of well-defined tools that follow consistent patterns and handle authentication, validation, error handling, and rate limiting.

Key capabilities:

• GitHub API Integration: Secure and seamless integration with GitHub's REST API
• Comprehensive GitHub Features: Complete management of repos, branches, issues, PRs, and more
• Atomic Feature Architecture: Well-organized modular code structure for maintainability
• Input Validation: Robust validation with Zod schemas for all operations
• Error Handling: Consistent error categorization and reporting
• Rate Limiting: Built-in GitHub API rate limit handling
• Performance Focus: Optimized operations and response formatting

Core system architecture:

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation"]
        Rate["Rate Limiting"]

        MCP --> Val --> Rate
    end

    subgraph Features["Feature Modules"]
        direction LR
        Repo["Repository Management"]
        Branch["Branch Management"]
        Issue["Issue Management"]
        PR["Pull Request Management"]
        File["File Management"]
        Release["Release Management"]

        Repo <--> Branch
        Repo <--> Issue
        Repo <--> PR
        Repo <--> File
        Branch <--> PR
    end

    subgraph Services["Services Layer"]
        direction LR
        GitHub["GitHub Service"]
        Mapper["Response Mapper"]
        RateLimiter["Rate Limiter"]

        GitHub <--> RateLimiter
        GitHub <--> Mapper
    end

    Rate --> Repo
    Rate --> Branch
    Rate --> Issue
    Rate --> PR
    Rate --> File
    Rate --> Release

    Repo --> GitHub
    Branch --> GitHub
    Issue --> GitHub
    PR --> GitHub
    File --> GitHub
    Release --> GitHub

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    classDef api fill:#3182ce,stroke:#90cdf4,stroke-width:2px,rx:3,color:#fff
    classDef features fill:#319795,stroke:#81e6d9,stroke-width:2px,rx:3,color:#fff
    classDef services fill:#2f855a,stroke:#9ae6b4,stroke-width:2px,rx:3,color:#fff

    class API,Features,Services layer
    class MCP,Val,Rate api
    class Repo,Branch,Issue,PR,File,Release features
    class GitHub,Mapper,RateLimiter services

Core Components:

• MCP Protocol Layer: Handles communication with AI assistants
• Validation Layer: Ensures data integrity through schema validation
• GitHub Service: Core integration with GitHub REST API
• Rate Limiter: Prevents API rate limit exhaustion
• Feature Modules: Domain-specific GitHub operations
• Error Handling: Comprehensive error handling and logging system

• Create, List, Get: Create new repositories, list user repositories, and get detailed repository information
• Validation & Configuration: Validate repository settings and manage configuration options

• Create, Delete, List: Complete branch lifecycle management with secure validation
• Protected Branch Support: Filtering and operations for protected branches

• Create & List: Create detailed issues with labels and list issues with filtering options
• Status Tracking: Filter by issue state (open, closed, all)

• Create, Update, Merge, List: Full pull request lifecycle management
• Review & Comment Integration: Add reviews and comments to pull requests
• Merge Options: Support for different merge strategies (merge, squash, rebase)

• Create & Update Files: Add and modify repository content with commit messages
• Base64 Encoding Support: Handle both text and binary file content

• Create Releases: Create tagged releases with customizable options
• Draft & Prerelease Support: Support for draft and prerelease workflows

• Node.js (v16 or newer)
• A GitHub personal access token with appropriate permissions

1. Clone the repository:

   git clone https://github.com/cyanheads/github-mcp-server.git
   cd github-mcp-server

2. Install dependencies:

   npm install

3. Create a .env file in the project root with your GitHub token:

   GITHUB_TOKEN=your_github_personal_access_token
   LOG_LEVEL=info
   SERVER_NAME=github-mcp-server
   

4. Build the project:

   npm run build

5. Start the server:

   node build/index.js

The server can be configured through environment variables:

Add to your MCP client settings:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "LOG_LEVEL": "info",
        "SERVER_NAME": "github-mcp-server"
      }
    }
  }
}

This project follows an atomic feature-oriented architecture pattern:

/src
  /configuration             // Application configuration
  /dependencyInjection       // Tool registry and DI container
  /features                  // Feature modules organized by domain
    /repositoryManagement
      /resources             // Read operations
      /modifications         // Write operations
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // External service integrations
    /githubAccess            // GitHub API client and utilities
  /types                     // Core type definitions
  /utilities                 // Helper functions and utilities

Each feature domain is split into:

• Resources: Read operations that don't modify data
• Modifications: Write operations that create, update, or delete data

Each operation is contained in its own directory with:

• Operation implementation file
• Type definitions file
• Export index file

GitHub MCP Server provides a comprehensive suite of tools for interacting with GitHub:

The project follows strict naming conventions and directory structure:

• File naming: action.entity.type.ts (e.g., create.repository.operation.ts)
• Each module has a clearly defined purpose
• Types are co-located with their implementation
• All exports are centralized through index files

• npm run build - Build the project
• npm run watch - Watch for changes and rebuild
• npm run inspector - Run the MCP inspector tool
• npm run clean - Clean build artifacts
• npm run rebuild - Clean and rebuild the project
• npm run tree - Generate a directory tree representation

The server implements a comprehensive error handling strategy:

• Standardized Error Objects: Consistent error format with categorization
• Input Validation: Pre-validation using Zod schemas
• Rate Limiting Protection: Automatic handling of GitHub API rate limits
• Error Categories:
  • Network errors (connectivity issues)
  • Authentication errors (token problems)
  • Validation errors (invalid input)
  • GitHub API errors (API-specific issues)
  • System errors (unexpected failures)
• Detailed Logging: Structured logging for all operations and errors

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Apache License 2.0