GitHub MCP Adapter Service

The GitHub MCP Adapter operates as a Model Context Protocol (MCP) compliant endpoint, offering deep integration with GitHub's application programming interfaces to unlock advanced process automation and interactive capabilities for software engineering teams and automated agents.

Key Capabilities

• Orchestrating GitHub CI/CD pipelines and development routines.
• Extracting comprehensive datasets and performing analyses on GitHub repository artifacts.
• Facilitating the construction of sophisticated, domain-specific applications leveraging the GitHub ecosystem through modular configuration.

Prerequisites for Container Operation

1. Docker runtime environment must be installed and operational.
2. A valid GitHub Personal Access Token (PAT) is required for authentication.

To generate a PAT, navigate to Create a GitHub Personal Access Token. Ensure the token is provisioned with sufficient scopes to permit the AI agents to interact with the necessary GitHub APIs. Consult the official documentation for details on token permissions.

Deployment Procedures

Integration via VS Code

For rapid setup, employ one of the one-click provisioning badges above. Completing this sequence enables Agent mode (accessible via the Copilot Chat interface), which automatically initiates the adapter.

For manual configuration, inject the following JSON structure into your VS Code User Settings (JSON file), accessible via Ctrl + Shift + P followed by searching for Preferences: Open User Settings (JSON).

Alternatively, place this configuration within a .vscode/mcp.json file in your project workspace to facilitate shared configurations:

The top-level mcp key is omitted when using the workspace-specific .vscode/mcp.json file.

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

Refer to the VS Code agent mode documentation for further details on utilizing MCP adapter services.

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

Compilation from Source

If Docker is unavailable, compilation via go build within the cmd/github-mcp-server directory yields the necessary binary. Execute it using the github-mcp-server stdio command, ensuring the GITHUB_PERSONAL_ACCESS_TOKEN environment variable is set. The -o flag specifies the output path for the executable. Configure your host connection to point to this compiled artifact:

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

Functional Module Control

The GitHub MCP Adapter allows fine-grained control over exposed capabilities using the --toolsets command-line argument. Limiting enabled modules optimizes LLM tool selection and reduces contextual overhead.

Registered Tool Modules

The following functional modules are available (all are active by default):

Module Name	Scope of Operations
repos	Repository administration (file manipulations, branch tracking, commit history)
issues	Issue lifecycle management (creation, retrieval, modification, commenting)
users	Operations pertaining to GitHub User entities
pull_requests	Management of PRs (generation, merging, review processing)
code_security	Interaction with code scanning alerts and security features
experiments	Features currently in experimental status (unstable)

Applying Module Filters

To restrict functionality accessible to the LLM, specify an allow-list through one of two methods:

1. Via Command Line:

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

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

The GITHUB_TOOLSETS environment variable takes precedence over the command-line specification.

Containerized Module Configuration

When deploying with Docker, toolset specification is managed via environment variables:

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' Module Designation

The reserved module name all ensures that every accessible module is activated, overriding any other configuration directives:

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

Or via environment variable:

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

Adaptive Module Discovery (Beta)

Warning: This feature is in a preliminary release phase. User feedback is encouraged for stability assessment.

Instead of pre-enabling all functionalities, dynamic module discovery allows the MCP host to intelligently activate required tool modules based on the immediate context of a user query. This mitigates potential confusion arising from an overabundance of exposed tools.

Enabling Adaptive Discovery

When executing the binary:

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

When using Docker, activate this feature using an 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 Connectivity

The --gh-host command-line flag or the GITHUB_HOST environment variable can be utilized to direct the adapter towards a specific GitHub Enterprise Server instance hostname.

Internationalization and Description Overrides

Descriptions associated with tools can be customized by generating a github-mcp-server-config.json file in the same directory as the executable. This file should map tool identifiers (e.g., TOOL_ADD_ISSUE_COMMENT_DESCRIPTION) to their desired replacement strings.

For example, to provide an alternative description:

{ "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "a revised description for adding comments", "TOOL_CREATE_BRANCH_DESCRIPTION": "Generate a new branch within a specified GitHub repository" }

To preserve existing customizations while integrating any new default translations added to the binary, run with the --export-translations flag:

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

Description overrides are also supported via environment variables, mirroring the JSON keys but prefixed with GITHUB_MCP_ and converted to uppercase. For instance, to override the issue comment tool description:

sh export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="a description set via environment variable"

Available Operations

User Account Operations

• get_me: Retrieves authentication details for the currently configured user.
• Parameters: None required.

Issue Tracking Subsystem

• get_issue: Fetches the complete details of an issue within a specified repository.

• owner: Identifier for the repository principal (String, mandatory).

• repo: Name of the repository (String, mandatory).

• issue_number: Numerical index of the issue (Number, mandatory).

• get_issue_comments: Retrieves all commentary associated with a GitHub issue.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• issue_number: Issue index (Number, mandatory).

• create_issue: Initiates a new issue record in a designated repository.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• title: Subject line for the issue (String, mandatory).
• body: Main narrative content (String, optional).
• assignees: List of GitHub usernames to delegate responsibility (String Array, optional).

• labels: Tags to categorize the issue (String Array, optional).

• add_issue_comment: Posts a new comment onto an existing issue.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• issue_number: Issue index (Number, mandatory).

• body: Text content of the commentary (String, mandatory).

• list_issues: Filters and retrieves a collection of issues based on specified criteria.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• state: Filter by status ('open', 'closed', 'all') (String, optional).
• labels: Filter by associated tags (String Array, optional).
• sort: Sorting metric ('created', 'updated', 'comments') (String, optional).
• direction: Ascending/descending sort order ('asc', 'desc') (String, optional).
• since: Filter records dated after this ISO 8601 timestamp (String, optional).
• page: Pagination index (Number, optional).

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

• update_issue: Modifies the attributes of a pre-existing issue.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• issue_number: Target issue index (Number, mandatory).
• title: New 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 responsible parties (String Array, optional).

• milestone: Associated milestone index (Number, optional).

• search_issues: Executes a federated search across issues and pull requests using a query string.

• query: The specific search expression (String, required).
• sort: Field to sort results by (String, optional).
• order: Sorting sequence (String, optional).
• page: Page index (Number, optional).
• perPage: Results limit per page (Number, optional).

Pull Request Management

• get_pull_request: Retrieves detailed information for a designated pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• pullNumber: Numerical PR identifier (Number, mandatory).

• list_pull_requests: Generates a list of pull requests matching specified filtering criteria.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• state: PR status filter (String, optional).
• sort: Sorting criterion (String, optional).
• direction: Sort direction (String, optional).
• perPage: Page size limit (Number, optional).

• page: Page index (Number, optional).

• merge_pull_request: Finalizes and integrates the changes from a pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• pullNumber: Target PR index (Number, mandatory).
• commit_title: Proposed subject for the resulting merge commit (String, optional).
• commit_message: Detailed message for the merge commit (String, optional).

• merge_method: Specified merge strategy (String, optional).

• get_pull_request_files: Fetches the list of modified files within a pull request's diff.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• pullNumber: PR index (Number, mandatory).

• get_pull_request_status: Retrieves the aggregated status check results for a pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• pullNumber: PR index (Number, mandatory).

• update_pull_request_branch: Synchronizes a PR's source branch with the latest commit from its target base branch.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• pullNumber: PR index (Number, mandatory).

• expectedHeadSha: The anticipated SHA for the PR's head reference (String, optional).

• get_pull_request_comments: Fetches line-by-line review comments associated with a PR.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• pullNumber: PR index (Number, mandatory).

• get_pull_request_reviews: Retrieves formal review submissions made against a PR.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• pullNumber: PR index (Number, mandatory).

• create_pull_request_review: Submits a formal review action on a pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• pullNumber: PR index (Number, mandatory).
• body: Review summary text (String, optional).
• event: Action taken ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (String, required).
• commitId: SHA of the commit being reviewed (String, optional).

• comments: Array detailing line-specific feedback objects (Array, optional)

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

• create_pull_request: Formally opens a new pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• title: Proposed title (String, mandatory).
• body: Detailed description (String, optional).
• head: Source branch containing modifications (String, mandatory).
• base: Target branch for integration (String, mandatory).
• draft: Mark as a draft proposal (Boolean, optional).

• maintainer_can_modify: Permit maintainer edits to the PR (Boolean, optional).

• add_pull_request_review_comment: Posts a comment to a PR diff or replies to an existing discussion thread.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• pull_number: PR index (Number, mandatory).
• body: The commentary payload (String, mandatory).
• commit_id: SHA of the commit relevant to the comment (String, mandatory if not replying).
• path: Relative file path for the comment target (String, mandatory if not replying).
• line: The specific line number in the diff chunk (Number, optional).
• side: Side of the comparison ('LEFT' or 'RIGHT') (String, optional).
• start_line: For range comments, the initial line index (Number, optional).
• start_side: For range comments, the initial side of the diff (String, optional).
• subject_type: Level of focus for the comment ('line' or 'file') (String, optional).

• in_reply_to: ID of the parent review comment to respond to (Number, optional). If set, only body is processed.

• update_pull_request: Modifies existing attributes of a pull request.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• pullNumber: Target PR index (Number, mandatory).
• title: Replacement subject (String, optional).
• body: Replacement description (String, optional).
• state: New status ('open' or 'closed') (String, optional).
• base: New destination branch name (String, optional).
• maintainer_can_modify: Toggle maintainer edit permission (Boolean, optional).

Repository Services

• create_or_update_file: Atomically writes or replaces a single file within a repository tree.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• path: Target file location (String, mandatory).
• message: Commit notation (String, mandatory).
• content: The data payload for the file (String, mandatory).
• branch: Target branch for the change (String, optional).

• sha: Current file SHA if performing an update operation (String, optional).

• list_branches: Retrieves the navigable branch references within a repository.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• page: Pagination index (Number, optional).

• perPage: Result set size (Number, optional).

• push_files: Commits a batch of file changes in a singular transaction.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• branch: The branch receiving the combined commit (String, mandatory).
• files: Collection of file objects, each containing path and content (Array, mandatory).

• message: Overarching commit log entry (String, mandatory).

• search_repositories: Locates repositories based on specified criteria.

• query: Search criteria string (String, required).

• sort: Field for ordering results (String, optional).
• order: Sequence of ordering (String, optional).
• page: Page index (Number, optional).

• perPage: Page capacity (Number, optional).

• create_repository: Provisions a new, empty repository under a specified account/organization.

• name: Desired name for the repository (String, mandatory).

• description: Brief summary of the repository's purpose (String, optional).
• private: Designate the repository visibility as private (Boolean, optional).

• autoInit: Automatically include a starter README file (Boolean, optional).

• get_file_contents: Accesses the serialized data for a file or the listing for a directory.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• path: The path to the artifact (String, mandatory).

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

• fork_repository: Creates a personal copy (fork) of an existing repository.

• owner: Source repository principal (String, mandatory).

• repo: Source repository identifier (String, mandatory).

• organization: The organization under which to place the new fork (String, optional).

• create_branch: Establishes a new branch reference point.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• branch: Name to assign to the new branch (String, mandatory).

• sha: The commit SHA that forms the genesis point for the new branch (String, mandatory).

• list_commits: Retrieves a chronological sequence of commits for a specified branch or SHA.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• sha: Target reference (branch name, tag, or commit SHA) (String, optional).
• path: Constrain results to commits affecting this specific file path (String, optional).
• page: Page index (Number, optional).

• perPage: Items per page (Number, optional).

• get_commit: Fetches detailed metadata for a specific commit object.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• sha: Identifier for the commit to examine (String, required).
• page: Index for paginating the list of files modified in the commit (Number, optional).

• perPage: Limit on files listed per page (Number, optional).

• search_code: Performs a global search across source code contents in repositories.

• query: The expression used for code searching (String, required).
• sort: Field for result ordering (String, optional).
• order: Sequence for ordering (String, optional).
• page: Page index (Number, optional).
• perPage: Items per page (Number, optional).

User Directory Operations

• search_users: Locates GitHub user profiles based on query parameters.
• query: Search expression (String, required).
• sort: Field for ordering results (String, optional).
• order: Sequence for ordering (String, optional).
• page: Page index (Number, optional).
• perPage: Items per page (Number, optional).

Security Scanning Subsystem

• get_code_scanning_alert: Retrieves the specifics of a singular code vulnerability alert.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• alertNumber: Unique identifier for the alert (Number, mandatory).

• list_code_scanning_alerts: Presents a filtered enumeration of code scanning notifications for a repository.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• ref: Specific Git reference for the scan context (String, optional).
• state: Filter by alert resolution status (String, optional).
• severity: Filter by identified risk level (String, optional).
• tool_name: Filter by the security scanner application that found the issue (String, optional).

Secret Scanning Subsystem

• get_secret_scanning_alert: Fetches the details of one discovered leaked secret notification.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).

• alertNumber: Unique identifier for the secret alert (Number, mandatory).

• list_secret_scanning_alerts: Lists secret scanning notifications for a repository, applying filters.

• owner: Repository principal (String, mandatory).

• repo: Repository identifier (String, mandatory).
• state: Filter by alert resolution status (String, optional).
• secret_type: Comma-separated list of sensitive token types to include (String, optional).
• resolution: Filter by the resolution status applied (String, optional).

Protocol Endpoints (Content Access Schemas)

Repository File System Manifests

• Repository Content Retrieval (Latest) Accesses the serialized state of a repository file or directory listing.

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

• Arguments:

  • owner: Principal of the repository (String, required).
  • repo: Name tag of the repository (String, required).
  • path: Target file or directory segment (String, optional).

• Repository Content Retrieval (Branch Specific) Retrieves content based on a specific branch reference.

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

• Arguments:

  • owner: Principal of the repository (String, required).
  • repo: Name tag of the repository (String, required).
  • branch: The reference branch name (String, required).
  • path: Target artifact segment (String, optional).

• Repository Content Retrieval (Commit SHA Context) Retrieves content as it existed at a specific commit hash.

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

• Arguments:

  • owner: Principal of the repository (String, required).
  • repo: Name tag of the repository (String, required).
  • sha: The target commit identifier (String, required).
  • path: Target artifact segment (String, optional).

• Repository Content Retrieval (Tag Context) Retrieves content associated with a specific version tag.

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

• Arguments:

  • owner: Principal of the repository (String, required).
  • repo: Name tag of the repository (String, required).
  • tag: The Git tag name (String, required).
  • path: Target artifact segment (String, optional).

• Repository Content Retrieval (Pull Request Context) Retrieves content from the head reference of an active pull request.

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

• Arguments:
  • owner: Principal of the repository (String, required).
  • repo: Name tag of the repository (String, required).
  • prNumber: The numerical PR identifier (String, required).
  • path: Target artifact segment (String, optional).

Internal Library Interface

The exported Go language API for this module is currently designated as unstable and subject to future modifications. Stability guarantees may be introduced later; kindly file an issue if stability is critical for your application.

Licensing Information

This software is distributed under the terms of the permissive MIT open source license. Refer to the MIT document for comprehensive details.

WIKIPEDIA: Enterprise management solutions encompass all the frameworks, computing assets, governance structures, analytical engines, prescriptive methods, etc., utilized by commercial entities to navigate evolving market dynamics, secure competitive advantages, and elevate organizational efficacy. These systems span functional domains such as strategic forecasting, operational oversight, record-keeping, human capital management, and performance auditing. Modern management tooling has undergone rapid transformation due to technological advancements, complicating the selection process for optimal solutions. Success in this environment mandates a strategic approach to adopting management technologies, ensuring they are customized to the firm's specific requirements rather than forcing organizational conformity to the tool's inherent structure.

== Core Adoption Trends == Industry surveys indicate that key management systems globally focus on areas such as Customer Relationship Management, strategic goal alignment (Balanced Scorecard), core capability identification, and systematic quality improvement (TQM). The successful integration of IT investments with overall business outcomes heavily depends on the efficacy of the deployment process and the judicious selection of the underlying software applications.