GitHub MCP Gateway Service

This component functions as a Model Context Protocol (MCP) endpoint, designed to establish direct, secure communication channels with the GitHub REST and GraphQL APIs. It empowers automated execution of complex operations, deep repository introspection, and the deployment of AI-driven utilities tailored for the GitHub ecosystem.

Core Capabilities

• Orchestrating repetitive GitHub operational tasks and procedures.
• Performing deep data extraction and analytical assessment across GitHub code repositories.
• Constructing sophisticated, AI-driven utilities that interact intelligently with the GitHub infrastructure.

Prerequisites for Operation

1. Docker installation is mandatory for containerized service deployment.
2. Ensure the Docker daemon is actively running. The container image is publicly accessible; authentication issues might necessitate running docker logout ghcr.io.
3. A valid GitHub Personal Access Token (PAT) must be generated via GitHub settings.

The MCP gateway leverages various GitHub APIs; please grant the necessary scopes to your AI assistants responsibly. Refer to the official authentication documentation for token security details.

Deployment Instructions

Integration with VS Code

For rapid deployment, utilize the one-click badges at the document's apex. Upon completion, activate Agent mode via the Copilot Chat input area to commence service operation.

For manual configuration, embed the subsequent JSON block into your VS Code User Settings file (Ctrl + Shift + P, then Preferences: Open User Settings (JSON)).

{ "mcp": { "inputs": [ { "type": "promptString", "id": "github_token", "description": "GitHub Personal Access Token", "password": true } ], "servers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" } } } } }

Alternatively, place a similar configuration (omitting the top-level mcp key) into a .vscode/mcp.json file within your project workspace to facilitate configuration sharing.

{ "inputs": [ { "type": "promptString", "id": "github_token", "description": "GitHub Personal Access Token", "password": true } ], "servers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}" } } } }

Explore further details on leveraging MCP service tooling within VS Code's agent mode documentation.

Usage with Claude Desktop

{ "mcpServers": { "github": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } }

Compilation from Source

If Docker is unavailable, compilation via go build within the cmd/github-mcp-server directory is an option. Invoke the service using github-mcp-server stdio, ensuring the GITHUB_PERSONAL_ACCESS_TOKEN environment variable is set. The output binary path can be specified using the -o flag. Update your server configuration to point to this executable as the command.

Example configuration for local execution:

JSON { "mcp": { "servers": { "github": { "command": "/path/to/github-mcp-server", "args": ["stdio"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" } } } } }

Toolset Management

The GitHub MCP Gateway permits granular control over exposed functionalities via the --toolsets command-line flag. Restricting enabled toolsets enhances LLM tool selection precision and minimizes required context overhead.

Supported Functionality Groups

All toolsets are active by default:

Toolset	Functionality Scope
repos	Operations concerning repositories (file modifications, branching, commits)
issues	Tools for managing Issues (creation, retrieval, modification, annotation)
users	Utilities related to GitHub User entity data
pull_requests	Actions involving Pull Requests (initiation, merging, review cycles)
code_security	Interaction with Code Scanning alerts and security findings
experiments	Features currently under active experimentation (unstable)

Activating Specific Toolsets

Toolsets can be specified via two mechanisms:

1. Command Line Parameter:

bash github-mcp-server --toolsets repos,issues,pull_requests,code_security

1. Environment Variable: bash GITHUB_TOOLSETS="repos,issues,pull_requests,code_security" ./github-mcp-server

The GITHUB_TOOLSETS environment variable supersedes any command-line specification.

Docker Integration for Toolsets

When deployed via Docker, utilize environment variables for control:

bash docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN= \ -e GITHUB_TOOLSETS="repos,issues,pull_requests,code_security,experiments" \ ghcr.io/github/github-mcp-server

The 'all' Sentinel Toolset

Supplying the special toolset name all guarantees activation of every available capability, irrespective of other configuration settings:

bash ./github-mcp-server --toolsets all

Or via environment variable:

bash GITHUB_TOOLSETS="all" ./github-mcp-server

Dynamic Tool Activation (Beta)

Warning: This feature is presently in a beta state and availability may vary. Feedback on encountered issues is welcomed.

Instead of pre-enabling all tools, dynamic toolset discovery allows the MCP host to dynamically load and enable toolsets based on the immediate user prompt context. This mitigates LLM confusion arising from an excessive tool catalog.

Enabling Dynamic Discovery

Use the --dynamic-toolsets flag when running the binary:

bash ./github-mcp-server --dynamic-toolsets

For Docker execution, set the environment variable:

bash docker run -i --rm \ -e GITHUB_PERSONAL_ACCESS_TOKEN= \ -e GITHUB_DYNAMIC_TOOLSETS=1 \ ghcr.io/github/github-mcp-server

GitHub Enterprise Server Configuration

The --gh-host flag or the GITHUB_HOST environment variable permits specification of a custom GitHub Enterprise Server (GHES) hostname.

Localization and Tool Description Overrides

Tool descriptions can be customized by placing a github-mcp-server-config.json file alongside the executable. This JSON object maps tool identifiers to replacement descriptions (e.g., TOOL_ADD_ISSUE_COMMENT_DESCRIPTION).

To preserve existing overrides while incorporating any new translations added to the binary, execute the tool with the --export-translations flag:

sh ./github-mcp-server --export-translations cat github-mcp-server-config.json

Alternatively, description overrides can be applied using environment variables. These variables mirror the JSON keys but are prefixed with GITHUB_MCP_ and uppercased. For instance, to alter the description for adding an issue comment:

sh export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="A revised explanation for annotating issues"

Exposed Tools

User Management

• get_me - Fetches authenticated user identity details.
• Parameters: None.

Issue Tracking

• get_issue - Retrieves specifics of a designated repository issue.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• issue_number: Issue sequence index (Number, Mandatory)

• get_issue_comments - Fetches all annotations linked to a GitHub issue.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• issue_number: Issue sequence index (Number, Mandatory)

• create_issue - Registers a new issue within a specified GitHub repository.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• title: Subject line for the issue (String, Mandatory)
• body: Detailed content/description (String, Optional)
• assignees: List of user logins to be assigned (String Array, Optional)

• labels: List of labels to apply (String Array, Optional)

• add_issue_comment - Appends a new comment to an existing issue.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• issue_number: Issue sequence index (Number, Mandatory)

• body: Comment payload text (String, Mandatory)

• list_issues - Retrieves a filtered collection of repository issues.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• state: Issue status filter ('open', 'closed', 'all') (String, Optional)
• labels: Labels used for filtering (String Array, Optional)
• sort: Ordering criterion ('created', 'updated', 'comments') (String, Optional)
• direction: Ascending/Descending sort ('asc', 'desc') (String, Optional)
• since: Filter based on creation/update time (ISO 8601) (String, Optional)
• page: Page index for pagination (Number, Optional)

• perPage: Count of results per page (Number, Optional)

• update_issue - Modifies attributes of a current issue.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• issue_number: Issue sequence index requiring update (Number, Mandatory)
• title: Revised subject line (String, Optional)
• body: New descriptive content (String, Optional)
• state: New status ('open' or 'closed') (String, Optional)
• labels: Revised set of labels (String Array, Optional)
• assignees: Revised list of assigned users (String Array, Optional)

• milestone: Target milestone index (Number, Optional)

• search_issues - Executes a generalized search across issues and pull requests.

• query: Search phrase (String, Mandatory)
• sort: Field for ordering results (String, Optional)
• order: Direction of ordering (String, Optional)
• page: Pagination index (Number, Optional)
• perPage: Result limit per page (Number, Optional)

Pull Requests

• get_pull_request - Retrieves specific metadata for a single Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• pullNumber: PR sequence index (Number, Mandatory)

• list_pull_requests - Generates a list of PRs based on filtering criteria.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• state: PR status filter (String, Optional)
• sort: Ordering field (String, Optional)
• direction: Sort direction (String, Optional)
• perPage: Page size limit (Number, Optional)

• page: Pagination index (Number, Optional)

• merge_pull_request - Finalizes the integration of a specified Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• pullNumber: PR sequence index (Number, Mandatory)
• commit_title: Title assigned to the resulting merge commit (String, Optional)
• commit_message: Detailed message for the merge commit (String, Optional)

• merge_method: Strategy to employ for merging (e.g., 'merge', 'squash', 'rebase') (String, Optional)

• get_pull_request_files - Lists all file modifications contained within a Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• pullNumber: PR sequence index (Number, Mandatory)

• get_pull_request_status - Obtains the aggregated status check results for a Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• pullNumber: PR sequence index (Number, Mandatory)

• update_pull_request_branch - Synchronizes a PR's head branch with the latest state of its base branch.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• pullNumber: PR sequence index (Number, Mandatory)

• expectedHeadSha: The anticipated SHA of the PR's head reference (String, Optional)

• get_pull_request_comments - Retrieves all conversational annotations made on a Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• pullNumber: PR sequence index (Number, Mandatory)

• get_pull_request_reviews - Fetches the formal review submissions against a Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• pullNumber: PR sequence index (Number, Mandatory)

• create_pull_request_review - Submits a formal review action on a Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• pullNumber: PR sequence index (Number, Mandatory)
• body: Review narrative text (String, Optional)
• event: Required review disposition ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (String, Mandatory)
• commitId: SHA of the commit being formally reviewed (String, Optional)

• comments: Structured array for line-specific feedback (Array, Optional)

  • Inline comments require: path, position (or line), and body
  • Multi-line comments require: path, start_line, line, optional side/start_side, and body

• create_pull_request - Initiates a new Pull Request resource.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• title: Subject line for the PR (String, Mandatory)
• body: Informational description (String, Optional)
• head: Source branch containing the feature/fix (String, Mandatory)
• base: Target branch intended for integration (String, Mandatory)
• draft: Designate as a non-ready draft (Boolean, Optional)

• maintainer_can_modify: Permit maintainers to edit source branch (Boolean, Optional)

• add_pull_request_review_comment - Posts a specific comment, potentially inline, to a PR or replies to an existing thread.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• pull_number: PR sequence index (Number, Mandatory)
• body: The actual content of the review annotation (String, Mandatory)
• commit_id: SHA of the commit being annotated (String, Mandatory unless replying)
• path: Relative path to the file in question (String, Mandatory unless replying)
• line: Target line number within the diff (Number, Optional)
• side: Which side of the diff to anchor the comment (LEFT or RIGHT) (String, Optional)
• start_line: For range annotations, the initial line number (Number, Optional)
• start_side: For range annotations, the initial side of the diff (LEFT or RIGHT) (String, Optional)
• subject_type: Granularity of comment targeting (line or file) (String, Optional)

• in_reply_to: ID of the parent comment to thread under (Number, Optional). If present, only body is required.

• update_pull_request - Modifies the metadata of an extant Pull Request.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• pullNumber: PR sequence index to update (Number, Mandatory)
• title: New title string (String, Optional)
• body: New description text (String, Optional)
• state: New status ('open' or 'closed') (String, Optional)
• base: New destination branch name (String, Optional)
• maintainer_can_modify: Allow maintainer edits (Boolean, Optional)

Repositories

• create_or_update_file - Atomically creates a new file or overwrites an existing one within a repository structure.
• owner: Repository principal identifier (String, Mandatory)
• repo: Repository identifier (String, Mandatory)
• path: Destination file path within the repo (String, Mandatory)
• message: Commit summary text (String, Mandatory)
• content: Base64 encoded file payload (String, Mandatory)
• branch: Target branch name (String, Optional)

• sha: ETag/SHA required for modification (String, Optional)

• list_branches - Retrieves an enumeration of branches associated with a repository.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• page: Page index (Number, Optional)

• perPage: Result count limit (Number, Optional)

• push_files - Executes a batch commit operation across multiple files in a single transaction.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• branch: The branch reference for the push (String, Mandatory)
• files: Array detailing path and content for each file (Array, Mandatory)

• message: The singular commit message for the batch (String, Mandatory)

• search_repositories - Conducts a generalized search across the repository catalog.

• query: Search terms (String, Mandatory)
• sort: Field to sort results by (String, Optional)
• order: Sort direction ('asc' or 'desc') (String, Optional)
• page: Pagination index (Number, Optional)

• perPage: Results per page (Number, Optional)

• create_repository - Provisions a novel GitHub repository.

• name: Desired repository name (String, Mandatory)

• description: Repository summary (String, Optional)
• private: Visibility setting (Boolean, Optional)

• autoInit: Include a default README file upon creation (Boolean, Optional)

• get_file_contents - Fetches the raw data or structure of a file or directory listing.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• path: Target location within the repository (String, Mandatory)

• ref: Specific Git reference (branch, tag, or SHA) to query (String, Optional)

• fork_repository - Creates a personal or organizational copy (fork) of a source repository.

• owner: Source repository principal identifier (String, Mandatory)

• repo: Source repository identifier (String, Mandatory)

• organization: Target organization for the fork (String, Optional)

• create_branch - Establishes a new branch pointer based on an existing commit SHA.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• branch: Name of the new branch to be created (String, Mandatory)

• sha: The commit SHA from which the new branch originates (String, Mandatory)

• list_commits - Provides a chronological log of commits for a specified reference or file path.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• sha: Reference point (branch name, tag, or SHA) (String, Optional)
• path: Filter commits that affected this specific file path (String, Optional)
• page: Pagination index (Number, Optional)

• perPage: Result count limit (Number, Optional)

• get_commit - Retrieves detailed metadata for a specific commit object.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• sha: The unique commit hash or reference (String, Mandatory)
• page: Page index for viewing files included in the commit (Number, Optional)

• perPage: Page size limit for files included in the commit (Number, Optional)

• search_code - Performs an indexed search across code blobs across all accessible repositories.

• query: The code search predicate (String, Mandatory)
• sort: Primary sort field (String, Optional)
• order: Sort direction (String, Optional)
• page: Pagination index (Number, Optional)
• perPage: Result limit per page (Number, Optional)

User Interaction

• search_users - Locates GitHub user accounts matching a query string.
• q: Search criteria string (String, Mandatory)
• sort: Field used for ordering results (String, Optional)
• order: Sort direction ('asc' or 'desc') (String, Optional)
• page: Pagination index (Number, Optional)
• perPage: Result limit per page (Number, Optional)

Security Analysis

• get_code_scanning_alert - Retrieves the full record for a singular Code Scanning notification.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• alertNumber: The unique sequence ID of the alert (Number, Mandatory)

• list_code_scanning_alerts - Enumerates Code Scanning notifications for a repository.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• ref: Target Git reference (branch, tag, or SHA) (String, Optional)
• state: Filter by alert status (String, Optional)
• severity: Filter by reported severity level (String, Optional)
• tool_name: Filter by the security analysis tool that found the issue (String, Optional)

Secret Scanning

• get_secret_scanning_alert - Fetches details for a specific Secret Scanning notification.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)

• alertNumber: The unique sequence ID of the alert (Number, Mandatory)

• list_secret_scanning_alerts - Lists Secret Scanning notifications for a target repository.

• owner: Repository principal identifier (String, Mandatory)

• repo: Repository identifier (String, Mandatory)
• state: Filter by alert status (String, Optional)
• secret_type: Filter by secret type, comma-separated (String, Optional)
• resolution: Filter by resolution status (String, Optional)

Content Access Resources (Internal URI Scheme)

Repository Content Retrieval

• Get Repository Content Fetches the data or directory structure at a specified repository path.

• Scheme Template: repo://{owner}/{repo}/contents{/path*}

• Parameters:

  • owner: Repository owner identifier (String, Required)
  • repo: Repository identifier (String, Required)
  • path: Relative path to file or folder (String, Optional)

• Get Repository Content for a Specific Branch Retrieves content targeted to a specific branch revision.

• Scheme Template: repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}

• Parameters:

  • owner: Repository owner identifier (String, Required)
  • repo: Repository identifier (String, Required)
  • branch: The target branch name (String, Required)
  • path: Relative path to file or folder (String, Optional)

• Get Repository Content for a Specific Commit Retrieves content corresponding to a historical commit snapshot.

• Scheme Template: repo://{owner}/{repo}/sha/{sha}/contents{/path*}

• Parameters:

  • owner: Repository owner identifier (String, Required)
  • repo: Repository identifier (String, Required)
  • sha: The commit hash identifier (String, Required)
  • path: Relative path to file or folder (String, Optional)

• Get Repository Content for a Specific Tag Retrieves content as it existed when a specific tag was applied.

• Scheme Template: repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}

• Parameters:

  • owner: Repository owner identifier (String, Required)
  • repo: Repository identifier (String, Required)
  • tag: The tag name (String, Required)
  • path: Relative path to file or folder (String, Optional)

• Get Repository Content for a Specific Pull Request Retrieves content reflecting the state of a Pull Request merge base.

• Scheme Template: repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}

• Parameters:
  • owner: Repository owner identifier (String, Required)
  • repo: Repository identifier (String, Required)
  • prNumber: The Pull Request sequence number (String, Required)
  • path: Relative path to file or folder (String, Optional)

Library Integration

The exported programming interface (Go API) is currently considered mutable and subject to non-backward-compatible revisions. Future stability commitments may be considered upon demonstrating critical dependency use cases.

Licensing

This software is distributed under the terms of the MIT License. Full stipulations are detailed in the MIT file.