License

Skip to content

You signed in with another tab or window. Reload
to refresh your session. You signed out in another tab or window. Reload
to refresh your session. You switched accounts on another tab or window. Reload
to refresh your session. Dismiss alert

cyanheads / github-mcp-server Public

• Notifications
  You must be signed in to change notification settings

• Fork 1

• Star 2

A Model Context Protocol (MCP) server built in TypeScript that integrates with GitHub's API, enabling AI assistants to manage repositories, issues, pull requests, and code while providing a structured interface for LLM agents to perform GitHub operations.

License

Apache-2.0 license

2 stars
1 fork
Branches
Tags
Activity

Star

Notifications
You must be signed in to change notification settings

cyanheads/github-mcp-server

main

Branches
Tags

Go to file

Code

Folders and files

| Name | | Name | Last commit message | Last commit date |
| --- | --- | --- | --- |
| Latest commit
-------------

History
-------

7 Commits

| | |
| .github/workflows | | .github/workflows | | |
| docs | | docs | | |
| scripts | | scripts | | |
| src | | src | | |
| .env.example | | .env.example | | |
| .gitignore | | .gitignore | | |
| LICENSE | | LICENSE | | |
| README.md | | README.md | | |
| package-lock.json | | package-lock.json | | |
| package.json | | package.json | | |
| tsconfig.json | | tsconfig.json | | |
| View all files | | |

Repository files navigation

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:

Click to expand Mermaid diagram

Loading

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:

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

2. Install dependencies:

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

   shell npm run build

5. Start the server:

   shell 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

Built with the Model Context Protocol

About

A Model Context Protocol (MCP) server built in TypeScript that integrates with GitHub's API, enabling AI assistants to manage repositories, issues, pull requests, and code while providing a structured interface for LLM agents to perform GitHub operations.

Topics

github
typescript
version-control
mcp
ai-assistant
llm
llm-agent
model-context-protocol
modelcontextprotocol

Resources

Readme

License

Apache-2.0 license

Activity

Stars

2 stars

Watchers

1 watching

Forks

1 fork

Report repository

Releases

1 tags

Packages 0

No packages published

Languages

• TypeScript 83.3%

• JavaScript 16.7%

You can’t perform that action at this time.