GitHub MCP Server

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.

Table of Contents

• 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

Overview

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

Architecture & Components

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

Features

Repository Management

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

Branch Management

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

Issue Management

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

Pull Request Management

• 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)

File Management

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

Release Management

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

Installation

Prerequisites

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

Setup

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
   

Configuration

The server can be configured through environment variables:

MCP Client Settings

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

Project Structure

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

Tools

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

Repository Management Tools

Branch Management Tools

Issue Management Tools

Pull Request Management Tools

File Management Tools

Release Management Tools

Development

Project Structure

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

Scripts

• 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

Error Handling

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

Contributing

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

License

Apache License 2.0