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.

Overview
- Architecture & Components
Features
Installation
- Prerequisites
- Setup
Configuration
Project Structure
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:

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

Clone the repository:
git clone https://github.com/cyanheads/github-mcp-server.git cd github-mcp-server
Install dependencies:
npm install
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
Build the project:
npm run build
Start the server:
node build/index.js

Configuration

The server can be configured through environment variables:

Environment Variable	Description	Default
`GITHUB_TOKEN`	GitHub personal access token (required)	-
`LOG_LEVEL`	Logging level (debug, info, warn, error, fatal)	info
`SERVER_NAME`	MCP server name	github-mcp-server
`SERVER_VERSION`	MCP server version	0.1.0
`API_TIMEOUT_MS`	Timeout for API calls in milliseconds	10000
`RATE_LIMITING_ENABLED`	Whether rate limiting is enabled	true
`RATE_LIMITING_MIN_REMAINING`	Minimum remaining requests before throttling	100
`RATE_LIMITING_RESET_BUFFER_MS`	Time buffer to add to rate limit reset time	5000

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

Tool	Description
`get_repository`	Get detailed information about a specific repositoryParameters: `owner`, `repo`
`list_repositories`	List repositories for the authenticated userParameters: `type` (optional), `sort` (optional)
`create_repository`	Create a new GitHub repositoryParameters: `name`, `description` (optional), `private` (optional)

Branch Management Tools

Tool	Description
`list_branches`	List branches in a repositoryParameters: `owner`, `repo`, `protected` (optional), `per_page` (optional)
`create_branch`	Create a new branchParameters: `owner`, `repo`, `branch`, `sha`
`delete_branch`	Delete a branchParameters: `owner`, `repo`, `branch`

Issue Management Tools

Tool	Description
`create_issue`	Create a new issue in a repositoryParameters: `owner`, `repo`, `title`, `body` (optional), `labels` (optional)
`list_issues`	List issues in a repositoryParameters: `owner`, `repo`, `state` (optional), `labels` (optional)

Pull Request Management Tools

Tool	Description
`create_pull_request`	Create a new pull requestParameters: `owner`, `repo`, `title`, `head`, `base`, `body` (optional)
`merge_pull_request`	Merge a pull requestParameters: `owner`, `repo`, `pull_number`, `commit_title` (optional), `commit_message` (optional), `merge_method` (optional)
`update_pull_request`	Update an existing pull requestParameters: `owner`, `repo`, `pull_number`, `title` (optional), `body` (optional), `state` (optional), `base` (optional), `maintainer_can_modify` (optional)
`list_pull_requests`	List pull requests in a repositoryParameters: `owner`, `repo`, `state` (optional), `head` (optional), `base` (optional), `sort` (optional), `direction` (optional)

File Management Tools

Tool	Description
`update_file`	Create or update a file in a repositoryParameters: `owner`, `repo`, `path`, `message`, `content`, `sha` (optional), `branch` (optional)

Release Management Tools

Tool	Description
`create_release`	Create a new releaseParameters: `owner`, `repo`, `tag_name`, `name` (optional), `body` (optional), `draft` (optional), `prerelease` (optional)

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.

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

License

Apache License 2.0

GitHub MCP Server

Integrations

GitHub MCP Server

Table of Contents

Overview

Architecture & Components

Features

Repository Management

Branch Management

Issue Management

Pull Request Management

File Management

Release Management

Installation

Prerequisites

Setup

Configuration

MCP Client Settings

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