GitHub

by cyanheads

3 stars
Not rated
GitHub

About

Integrates with GitHub's API to enable repository management, code manipulation, issue tracking, and pull request handling for streamlined development workflows.

Details

Author
cyanheads
Repository
cyanheads/github-mcp-server
GitHub stars
3
License
Apache License 2.0
Categories
Productivity, Developer Tools, Design, File Management, AI, Infrastructure, Communication, Frontend

Jump to

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name GitHub
    Command (node, npx, python, etc.) node
    Arguments
    • Argument 1 /path/to/github-mcp-server/build/index.js
    Environment
    • LOG_LEVEL info
    • SERVER_NAME github-mcp-server
    • GITHUB_TOKEN your_github_personal_access_token

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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 |

get_repository

Get detailed information about a specific repository. Parameters: owner, repo

list_repositories

List repositories for the authenticated user. Parameters: type (optional), sort (optional)

create_repository

Create a new GitHub repository. Parameters: name, description (optional), private (optional)

list_branches

List branches in a repository. Parameters: owner, repo, protected (optional), per_page (optional)

create_branch

Create a new branch. Parameters: owner, repo, branch, sha

delete_branch

Delete a branch. Parameters: owner, repo, branch

create_issue

Create a new issue in a repository. Parameters: owner, repo, title, body (optional), labels (optional)

list_issues

List issues in a repository. Parameters: owner, repo, state (optional), labels (optional)

create_pull_request

Create a new pull request. Parameters: owner, repo, title, head, base, body (optional)

merge_pull_request

Merge a pull request. Parameters: owner, repo, pull_number, commit_title (optional), commit_message (optional), merge_method (optional)

update_pull_request

Update an existing pull request. Parameters: owner, repo, pull_number, title (optional), body (optional), state (optional), base (optional), maintainer_can_modify (optional)

list_pull_requests

List pull requests in a repository. Parameters: owner, repo, state (optional), head (optional), base (optional), sort (optional), direction (optional)

update_file

Create or update a file in a repository. Parameters: owner, repo, path, message, content, sha (optional), branch (optional)

create_release

Create a new release. Parameters: owner, repo, tag_name, name (optional), body (optional), draft (optional), prerelease (optional)

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

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

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

GitHub MCP Server

TypeScript
Model Context Protocol
[Version]()
License
[Status]()
GitHub

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:

<details>
<summary>Click to expand Mermaid diagram</summary>

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

</details>

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:

| 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 repository<br>Parameters: owner, repo |
| list_repositories | List repositories for the authenticated user<br>Parameters: type (optional), sort (optional) |
| create_repository | Create a new GitHub repository<br>Parameters: name, description (optional), private (optional) |

Branch Management Tools

| Tool | Description |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| list_branches | List branches in a repository<br>Parameters: owner, repo, protected (optional), per_page (optional) |
| create_branch | Create a new branch<br>Parameters: owner, repo, branch, sha |
| delete_branch | Delete a branch<br>Parameters: owner, repo, branch |

Issue Management Tools

| Tool | Description |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| create_issue | Create a new issue in a repository<br>Parameters: owner, repo, title, body (optional), labels (optional) |
| list_issues | List issues in a repository<br>Parameters: owner, repo, state (optional), labels (optional) |

Pull Request Management Tools

| Tool | Description |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| create_pull_request | Create a new pull request<br>Parameters: owner, repo, title, head, base, body (optional) |
| merge_pull_request | Merge a pull request<br>Parameters: owner, repo, pull_number, commit_title (optional), commit_message (optional), merge_method (optional) |
| update_pull_request | Update an existing pull request<br>Parameters: owner, repo, pull_number, title (optional), body (optional), state (optional), base (optional), maintainer_can_modify (optional) |
| list_pull_requests | List pull requests in a repository<br>Parameters: 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 repository<br>Parameters: owner, repo, path, message, content, sha (optional), branch (optional) |

Release Management Tools

| Tool | Description |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| create_release | Create a new release<br>Parameters: 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.

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

---

<div align="center">
Built with the Model Context Protocol
</div>

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Git

A Model Context Protocol (MCP) server that provides tools for LLMs to read, search, and manipulate Git repositories. It enables automated repository…

88.1k
Developer Tools

Context 7

Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.

58.7k
Developer Tools