GitHub MCP Server

The GitHub MCP Server functions as a Model Context Protocol (MCP) endpoint, providing fluid connectivity to GitHub's APIs. This unlocks powerful automation and sophisticated interaction capabilities for development professionals and autonomous agents.

Primary Applications

• Orchestrating automated routines and processes within GitHub environments.
• Extracting valuable metadata and performing analytics on repository data.
• Developing intelligent tools and applications that interface directly with GitHub's functional components.

Prerequisites for Container Operation

1. Docker must be installed on the host system to execute the server within a container.
2. Verify that the Docker daemon is actively running. Public images are available; if image pulling fails, a renewal or re-login to ghcr.io might be necessary.
3. A GitHub Personal Access Token (PAT) must be generated via GitHub settings. The MCP server utilizes numerous GitHub APIs; ensure the PAT is granted sufficient permissions appropriate for your AI tools. Consult the official documentation for token scopes.

Deployment Instructions

Integration via VS Code

For rapid deployment, utilize the one-click installation badges located at the document's apex. After completing the installation sequence, activate Agent mode (found adjacent to the Copilot Chat input field) to initiate the server.

For manual configuration, insert the following JSON structure into your VS Code User Settings file. Access this file by invoking Ctrl + Shift + P and selecting 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, you may place a structurally similar configuration (omitting the top-level mcp key) into a file named .vscode/mcp.json within your project workspace to facilitate shared configuration.

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

Refer to the agent mode documentation for more details on leveraging MCP server tools within VS Code.

Integration 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": "<YOUR_TOKEN>"
      }
    }
  }
}

Compilation from Source

If Docker is unavailable, compilation via go build from the cmd/github-mcp-server directory yields an executable. Subsequently, invoke the server using the github-mcp-server stdio command, ensuring the GITHUB_PERSONAL_ACCESS_TOKEN environment variable is set. The build output path can be specified using the -o flag. Configure your server definition to point to this compiled executable as its command. Example:

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

Functional Configuration (Toolsets)

The GitHub MCP Server allows for granular control over exposed functionalities using the --toolsets argument. Limiting the available toolsets helps the LLM make more accurate tool selections and reduces necessary context payload.

Available Function Groups

The following operational sets are available (enabled by default):

Toolset	Description
repos	Utilities related to repository artifacts (e.g., file manipulation, branch tracking, commit history)
issues	Functions governing issue management (creation, retrieval, modification, commenting)
users	Endpoints related to GitHub user entities
pull_requests	Operations concerning Pull Requests (PR creation, merging, review handling)
code_security	Tools for accessing code scanning alerts and security features
experiments	Features currently under experimental status (unstable)

Specifying Enabled Toolsets

You can restrict the available capabilities using an allow-list via two methods:

1. Command Line Interface (CLI):

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 the CLI argument if both are present.

Toolsets with Docker

When operating via Docker, toolsets are configured via environment variables:

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

The "all" Designation

The special identifier all ensures every defined toolset is activated, overriding any other configuration:

./github-mcp-server --toolsets all

Or via environment variable:

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

Dynamic Tool Discovery (Beta)

Attention: This capability is currently in a testing phase and might not be universally available. Feedback on its performance is encouraged.

This mode replaces the static enabling of all tools. Dynamic discovery permits the MCP host to dynamically query and activate toolsets based on the context of the user's request, thereby preventing model confusion caused by an overly verbose tool inventory.

Enabling Dynamic Discovery

For the compiled binary, use the --dynamic-toolsets flag:

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

When using Docker, set the following environment variable:

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
  -e GITHUB_DYNAMIC_TOOLSETS=1 \
  ghcr.io/github/github-mcp-server

GitHub Enterprise Server (GHES) Support

The --gh-host flag or the GITHUB_HOST environment variable can be utilized to specify a custom GHES hostname. It is crucial to prepend the hostname with the https:// URI scheme, as omitting it defaults to insecure http://, which GHES typically rejects.

"github": {
    "command": "docker",
    "args": [
    "run",
    "-i",
    "--rm",
    "-e",
    "GITHUB_PERSONAL_ACCESS_TOKEN",
    "-e",
    "GITHUB_HOST",
    "ghcr.io/github/github-mcp-server"
    ],
    "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}",
        "GITHUB_HOST": "https://<your GHES domain name>"
    }
}

Internationalization (i18n) / Description Overrides

Tool descriptions can be customized by generating a github-mcp-server-config.json file located alongside the binary executable. This file should map tool identifiers to their desired replacement descriptions.

Example configuration:

{
  "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description",
  "TOOL_CREATE_BRANCH_DESCRIPTION": "Construct a new branch within a GitHub repository"
}

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

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

Alternatively, descriptions can be overridden using environment variables. The naming convention involves prefixing the JSON keys with GITHUB_MCP_ and converting to uppercase.

For instance, overriding TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:

export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="a revised commentary text"

Function Inventory

Users

• get_me - Retrieves the authenticated user's profile details
• No inputs required

Issues

• get_issue - Fetches the detailed content of a specified repository issue

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• issue_number: Numerical identifier for the issue (number, mandatory)

• get_issue_comments - Retrieves all comments associated with a GitHub issue

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• issue_number: Numerical identifier for the issue (number, mandatory)

• create_issue - Submits a new issue to a designated GitHub repository

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• title: Subject line for the new issue (string, mandatory)
• body: Main content of the issue (string, optional)
• assignees: List of GitHub usernames to assign responsibility (string[], optional)

• labels: Tags to categorize the issue (string[], optional)

• add_issue_comment - Appends a comment to an existing issue

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• issue_number: Numerical identifier for the issue (number, mandatory)

• body: The text content of the comment (string, mandatory)

• list_issues - Retrieves a filtered collection of repository issues

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• state: Filter status ('open', 'closed', 'all') (string, optional)
• labels: Criteria based on labels (string[], optional)
• sort: Field for ordering results ('created', 'updated', 'comments') (string, optional)
• direction: Ascending or descending order ('asc', 'desc') (string, optional)
• since: Filter issues created or modified after this ISO 8601 timestamp (string, optional)
• page: Pagination index (number, optional)

• perPage: Maximum items per response (number, optional)

• update_issue - Modifies properties of an existing GitHub issue

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• issue_number: Target issue number for modification (number, mandatory)
• title: Revised subject line (string, optional)
• body: Revised description content (string, optional)
• state: New status ('open' or 'closed') (string, optional)
• labels: Updated set of labels (string[], optional)
• assignees: Revised list of assignees (string[], optional)

• milestone: Associated milestone identifier (number, optional)

• search_issues - Executes a search query across issues and pull requests

• query: The search string (string, mandatory)
• sort: Parameter for result ordering (string, optional)
• order: Direction of sort (string, optional)
• page: Pagination index (number, optional)
• perPage: Items per page (number, optional)

Pull Requests

• get_pull_request - Retrieves specific metadata for a designated pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• pullNumber: Numerical identifier for the PR (number, mandatory)

• list_pull_requests - Fetches a collection of pull requests based on specified criteria

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• state: PR status filter (string, optional)
• sort: Field to sort results by (string, optional)
• direction: Sort direction (string, optional)
• perPage: Limit on returned items (number, optional)

• page: Pagination index (number, optional)

• merge_pull_request - Finalizes the integration of a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• pullNumber: Numerical identifier for the PR (number, mandatory)
• commit_title: Title to assign to the resulting merge commit (string, optional)
• commit_message: Detailed message for the merge commit (string, optional)

• merge_method: Preferred merging strategy (e.g., 'merge', 'squash', 'rebase') (string, optional)

• get_pull_request_files - Returns the manifest of files modified within a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• pullNumber: Numerical identifier for the PR (number, mandatory)

• get_pull_request_status - Fetches the consolidated status check report for a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• pullNumber: Numerical identifier for the PR (number, mandatory)

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

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• pullNumber: Numerical identifier for the PR (number, mandatory)

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

• get_pull_request_comments - Retrieves inline review comments posted on a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• pullNumber: Numerical identifier for the PR (number, mandatory)

• get_pull_request_reviews - Fetches formal reviews submitted for a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• pullNumber: Numerical identifier for the PR (number, mandatory)

• create_pull_request_review - Submits a formal review or comment action on a pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• pullNumber: Numerical identifier for the PR (number, mandatory)
• body: The body text accompanying the review (string, optional)
• event: The review action to perform ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (string, mandatory)
• commitId: The SHA of the commit being reviewed (string, optional)

• comments: Structured data for line-specific comments (array, optional)

  • For line-level annotations: supply path, position (or line), and body
  • For multi-line annotations: supply path, start_line, line, optional side/start_side, and body

• create_pull_request - Initiates a new pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• title: The intended title of the PR (string, mandatory)
• body: The description narrative for the PR (string, optional)
• head: Source branch name containing feature changes (string, mandatory)
• base: Target branch name for integration (string, mandatory)
• draft: Flag to create as a non-ready draft (boolean, optional)

• maintainer_can_modify: Permission setting for maintainer edits (boolean, optional)

• add_pull_request_review_comment - Posts a comment on a PR diff or replies to an existing thread

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• pull_number: Numerical identifier for the PR (number, mandatory)
• body: The content of the review comment (string, mandatory)
• commit_id: The SHA of the code snapshot to annotate (string, mandatory unless in_reply_to is used)
• path: The relative file path for the annotation (string, mandatory unless in_reply_to is used)
• line: The specific line number in the diff for the annotation (number, optional)
• side: Which side of the comparison to place the comment ('LEFT' or 'RIGHT') (string, optional)
• start_line: For range comments, the starting line number (number, optional)
• start_side: For range comments, the starting side of the diff (string, optional)
• subject_type: Defines the scope of the comment (line or file) (string, optional)

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

• update_pull_request - Modifies attributes of an established pull request

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• pullNumber: Target PR number for update (number, mandatory)
• title: New title for the PR (string, optional)
• body: New descriptive text (string, optional)
• state: New status ('open' or 'closed') (string, optional)
• base: New target base branch name (string, optional)
• maintainer_can_modify: Updated permission setting (boolean, optional)

Repositories

• create_or_update_file - Atomically creates a new file or overwrites an existing one within a repository
• owner: Repository owner identifier (string, mandatory)
• repo: Name of the repository (string, mandatory)
• path: Location of the file within the repo (string, mandatory)
• message: Commit note describing the change (string, mandatory)
• content: The data payload for the file (string, mandatory)
• branch: Target branch name (string, optional)

• sha: The existing file's SHA for update operations (string, optional)

• list_branches - Retrieves an enumeration of branches in a GitHub repository

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• page: Pagination index (number, optional)

• perPage: Results limit per page (number, optional)

• push_files - Commits and pushes a batch of file modifications in a single transaction

• owner: Repository owner identifier (string, mandatory)
• repo: Name of the repository (string, mandatory)
• branch: The destination branch for the push (string, mandatory)
• files: A list of file objects, each containing path and content (array, mandatory)

• message: The commit summary message (string, mandatory)

• search_repositories - Executes a query against GitHub repositories

• query: The search predicate (string, mandatory)
• sort: Field for result sorting (string, optional)
• order: Sort direction ('asc'/'desc') (string, optional)
• page: Pagination index (number, optional)

• perPage: Items per page limit (number, optional)

• create_repository - Provisions a new code repository

• name: Desired name for the new repository (string, mandatory)

• description: A brief summary of the repository's purpose (string, optional)
• private: Sets visibility to private (boolean, optional)

• autoInit: Automatically include a starting README file (boolean, optional)

• get_file_contents - Fetches the raw data or metadata for a specified file or directory listing

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• path: The file or directory path within the repo (string, mandatory)

• ref: The specific Git reference (branch, tag, or SHA) to query (string, optional)

• fork_repository - Duplicates a repository under the caller's namespace or a specified organization

• owner: Original repository owner identifier (string, mandatory)

• repo: Original repository name (string, mandatory)

• organization: Target organization handle for the fork (string, optional)

• create_branch - Establishes a new branch pointer

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• branch: Name to assign to the new branch (string, mandatory)

• sha: The commit SHA that the new branch should reference (string, mandatory)

• list_commits - Retrieves the history of commits for a given reference or path

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• sha: Reference to examine (branch name, tag, or commit SHA) (string, optional)
• path: Filter results to only include commits touching this file path (string, optional)
• page: Pagination index (number, optional)

• perPage: Items per page limit (number, optional)

• get_commit - Fetches detailed metadata for a single commit object

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)
• sha: The unique commit SHA, branch name, or tag identifier (string, mandatory)
• page: Pagination index, primarily for large files lists within the commit (number, optional)

• perPage: Results per page, for files list (number, optional)

• search_code - Performs a targeted search for code snippets across repositories

• query: The specific search criteria (string, mandatory)
• sort: Field for ordering results (string, optional)
• order: Direction of sort (string, optional)
• page: Pagination index (number, optional)
• perPage: Items per page limit (number, optional)

Users

• search_users - Finds GitHub accounts matching a given query
• q: The required search term (string, mandatory)
• sort: Parameter for result ordering (string, optional)
• order: Sort direction (string, optional)
• page: Pagination index (number, optional)
• perPage: Items per page limit (number, optional)

Code Scanning

• get_code_scanning_alert - Retrieves the details of a singular security alert

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• alertNumber: The unique ID of the alert (number, mandatory)

• list_code_scanning_alerts - Enumerates security alerts present in a repository

• owner: Repository owner identifier (string, mandatory)
• repo: Name of the repository (string, mandatory)
• ref: The Git reference (e.g., branch name) to scan (string, optional)
• state: Filter by alert status (string, optional)
• severity: Filter by severity level (string, optional)
• tool_name: Filter by the scanning utility that raised the alert (string, optional)

Secret Scanning

• get_secret_scanning_alert - Fetches information on a specific detected secret exposure

• owner: Repository owner identifier (string, mandatory)

• repo: Name of the repository (string, mandatory)

• alertNumber: The unique ID of the alert (number, mandatory)

• list_secret_scanning_alerts - Lists all secret scanning notifications for a repository

• owner: Repository owner identifier (string, mandatory)
• repo: Name of the repository (string, mandatory)
• state: Filter by alert resolution status (string, optional)
• secret_type: Comma-separated list of secret types to filter by (string, optional)
• resolution: Filter by resolution status (string, optional)

Resource Addressing

Repository Content Navigation

• Get Repository Content Accesses content at a path within a repository's default reference.

• Address: repo://{owner}/{repo}/contents{/path*}

• Parameters:

  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • path: File path or directory path (string, optional)

• Get Repository Content for a Specific Branch Retrieves content indexed to a specific branch head.

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

• Parameters:

  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • branch: Branch designator (string, required)
  • path: File path or directory path (string, optional)

• Get Repository Content for a Specific Commit Retrieves content as it existed at a specific commit SHA.

• Address: repo://{owner}/{repo}/sha/{sha}/contents{/path*}

• Parameters:

  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • sha: Commit SHA identifier (string, required)
  • path: File path or directory path (string, optional)

• Get Repository Content for a Specific Tag Retrieves content associated with a version tag.

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

• Parameters:

  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • tag: Tag version name (string, required)
  • path: File path or directory path (string, optional)

• Get Repository Content for a Specific Pull Request Accesses content reflecting the merged state of a PR.

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

• Parameters:
  • owner: Repository owner (string, required)
  • repo: Repository name (string, required)
  • prNumber: Pull request numerical identifier (string, required)
  • path: File path or directory path (string, optional)

Library Interfacing

The exported Go language API for this module should be treated as provisional and is subject to future compatibility breaks. Stability guarantees may be introduced later; please submit an issue if your use case mandates a stable API contract.

Licensing

This software is distributed under the terms of the MIT open source license. Comprehensive details are available in the MIT file.

WIKIPEDIA: Business management tools encompass all methodologies, controls, computational solutions, applications, and systems utilized by organizations to effectively navigate market fluctuations, secure competitive standing, and enhance overall enterprise performance.

== General View == Management tools can be categorized based on the organizational department they serve and the management aspect they address. Examples include tools for process oversight, strategic planning, data recording, employee administration, decision support, and performance monitoring. A functional grouping might isolate these key areas:

Tools involved in data entry and integrity verification across departments. Tools designed for regulating and optimizing operational workflows. Tools facilitating data synthesis and strategic decision formulation. Modern management tools have undergone radical modernization in the last ten years due to rapid technological advancement, creating a challenge for organizations to select optimal solutions for their specific needs. This complexity stems from the continuous drive to reduce operational expenditures, maximize revenue, deeply understand client requirements, and deliver products matching those expectations precisely. In this dynamic environment, executives must adopt a strategic perspective toward selecting management tools rather than chasing the newest release. Often, relying on tools without necessary customization leads to systemic instability. Management tools mandate careful selection, followed by adaptation to the organization's unique operational structure, not the inverse.

== Prominent Selections == Bain & Company's 2013 global survey illustrated the prevalent deployment of various business tools, reflecting how their outcomes address regional needs amid varying market conditions. The ten most frequently cited categories included:

Strategic planning frameworks Customer relationship management platforms Employee sentiment surveys Benchmarking analysis utilities Balanced scorecard systems Core competency identification Outsourcing management procedures Change management programs Supply chain governance tools Mission/Vision statement articulation aids Market segmentation analysis Total quality management methodologies

== Commercial Software Applications == Software packages or integrated systems utilized by enterprise users to execute diverse operational tasks are termed business software (or enterprise applications). These applications are designed to elevate productivity metrics, quantify performance indicators, and execute various company functions with precision. The evolution proceeded from early Management Information Systems (MIS) to comprehensive Enterprise Resource Planning (ERP) systems. Customer Relationship Management (CRM) capabilities were subsequently integrated, leading to the current landscape dominated by cloud-based business management solutions. While a measurable correlation exists between IT investments and organizational outcomes, two factors critically determine realized value: the efficacy of the implementation process and the meticulous selection and tailoring of the required tools.

== Tools Tailored for Small and Medium Enterprises (SMEs) == Specialized tools for SMEs are vital as they provide mechanisms to conserve resources...