GitHub MCP Connector Service

This service acts as a Model Context Protocol (MCP) endpoint, establishing robust connectivity with the GitHub Application Programming Interface (API) suite. It enables sophisticated automation routines and deep data introspection for engineering teams and associated automated systems.

Core Capabilities

Automating repetitive tasks within the GitHub environment.
Retrieving, aggregating, and analyzing version control metadata from repositories.
Facilitating the creation of intelligent agents leveraging GitHub data structures.

Setup Requirements

Docker Prerequisite: Docker must be installed and operational to run the service in a containerized environment.
Image Pull: The container image is publicly accessible. If pulling fails, authentication issues might be present; execute docker logout ghcr.io if your token has expired.
Authentication Token: A valid GitHub Personal Access Token (PAT) is required. You can generate one here: Generate New PAT. The server interacts with extensive GitHub APIs; grant permissions commensurate with the tasks your connected AI tools will perform (Consult the PAT Documentation for scope details).

Deployment Instructions

Integration with Visual Studio Code

For immediate deployment, utilize the one-click buttons situated at the top of this document. Upon completion of the setup wizard, activate Agent mode (accessible via the Copilot Chat input box) to initiate the service.

For manual configuration, insert the subsequent JSON structure into your VS Code User Settings (JSON file). Access this via Ctrl + Shift + P followed by typing 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 configuration resembling the example below (omitting the root mcp key) into a .vscode/mcp.json file within your workspace directory for shared configuration across team members.

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

Further documentation on utilizing MCP services within VS Code's agent environment is available.

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 using go build within the cmd/github-mcp-server directory is an option. Run the resulting binary with github-mcp-server stdio, ensuring the GITHUB_PERSONAL_ACCESS_TOKEN environment variable is set. The output path can be specified using the -o flag. Update your server configuration to point the command to this executable, for instance:

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

Tool Functionality Scoping

The GitHub MCP Service permits granular control over exposed API capabilities using the --toolsets command-line argument. Limiting active toolsets can improve LLM efficiency in tool selection and reduce unnecessary context loading.

Supported Toolsets

By default, all categories below are active:

Toolset	Capability Summary
`repos`	Operations concerning repositories (file handling, branching, history)
`issues`	Management of development issues (creation, retrieval, annotation)
`users`	Information retrieval pertaining to GitHub accounts
`pull_requests`	Handling of PR lifecycle events (creation, integration, feedback)
`code_security`	Access to code scanning alerts and security findings
`experiments`	Features designated as experimental and potentially unstable

Configuring Toolsets

Use an allow-list to constrain functionality, specified via two methods:

Command Line Interface (CLI):

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

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

The GITHUB_TOOLSETS environment variable overrides any specification made via the CLI argument.

Docker Toolset Management

When deploying via Docker, specify toolsets through 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' Designation

Providing the special value all to either parameter enables every defined toolset:

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

Or via environment variable:

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

On-Demand Toolset Revelation (Dynamic Discovery)

Beta Notice: This feature is currently undergoing trials and might not be universally available. Feedback on its performance is encouraged.

Instead of pre-enabling all tools, dynamic discovery permits the MCP host to query and activate toolsets dynamically based on the immediate user prompt. This minimizes model overload from an extensive tool manifest.

Enabling Dynamic Discovery

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

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

For Docker deployments, set the corresponding 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 Context

The hostname for GitHub Enterprise instances can be set via the --gh-host flag or the GITHUB_HOST environment variable.

Internationalization (i18n) / Description Customization

The default descriptions for tools can be supplanted by providing a github-mcp-server-config.json file alongside the executable. This file must be a JSON object mapping tool identifiers to new descriptions, for example:

{ "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "A revised descriptor for adding comments", "TOOL_CREATE_BRANCH_DESCRIPTION": "Provision a novel branch within the specified GitHub repository" }

To generate a file reflecting current translations plus any additions, run the binary with the --export-translations flag:

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

Description overrides can also be set using environment variables. The variable name mirrors the JSON key, but prefixed with GITHUB_MCP_ and converted to uppercase. For instance, to override TOOL_ADD_ISSUE_COMMENT_DESCRIPTION:

sh export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="A superior comment annotation mechanism"

Available Tools

User Accounts

get_me - Retrieves authenticated user identity details
Parameters: None

Issue Tracking

get_issue - Fetches the details of a specific repository issue
owner: Originator of the repository (string, required)
repo: Repository identifier (string, required)
issue_number: Numerical ID of the issue (number, required)
get_issue_comments - Fetches all annotations associated with a GitHub issue
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
issue_number: Issue numerical ID (number, required)
create_issue - Submits a new issue record to a repository
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
title: Subject line for the issue (string, required)
body: Primary content/description (string, optional)
assignees: List of usernames assigned responsibility (string[], optional)
labels: Tags to categorize the issue (string[], optional)
add_issue_comment - Posts a new annotation onto an issue thread
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
issue_number: Target issue ID (number, required)
body: The comment payload (string, required)
list_issues - Queries and filters the collection of repository issues
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
state: Status filter ('open', 'closed', or 'all') (string, optional)
labels: Filter by specific tags (string[], optional)
sort: Primary sorting criterion ('created', 'updated', 'comments') (string, optional)
direction: Sorting order ('asc' or 'desc') (string, optional)
since: Filter issues modified after this ISO 8601 timestamp (string, optional)
page: Pagination index (number, optional)
perPage: Result count per page (number, optional)
update_issue - Modifies an existing issue record
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
issue_number: Issue ID to modify (number, required)
title: New subject line (string, optional)
body: New description text (string, optional)
state: New status ('open' or 'closed') (string, optional)
labels: Replacement set of tags (string[], optional)
assignees: New list of responsible users (string[], optional)
milestone: Associated milestone's numerical ID (number, optional)
search_issues - Executes a generalized search across issues and pull requests
query: Search string conforming to GitHub syntax (string, required)
sort: Field for sorting results (string, optional)
order: Ascending/Descending sort (string, optional)
page: Page index (number, optional)
perPage: Items per page (number, optional)

Pull Requests

get_pull_request - Retrieves detailed metadata for a singular Pull Request
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR numerical identifier (number, required)
list_pull_requests - Retrieves a filtered listing of repository PRs
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
state: PR lifecycle status (string, optional)
sort: Sorting attribute (string, optional)
direction: Sort orientation (string, optional)
perPage: Items per page limit (number, optional)
page: Pagination index (number, optional)
merge_pull_request - Integrates the changes from a specified PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: Target PR ID (number, required)
commit_title: Title for the resulting merge commit (string, optional)
commit_message: Detailed message for the merge commit (string, optional)
merge_method: Strategy for merging (string, optional)
get_pull_request_files - Lists all file modifications included in a PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID (number, required)
get_pull_request_status - Fetches the aggregated status check outcome for a PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID (number, required)
update_pull_request_branch - Synchronizes a PR's head branch with its base branch
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID (number, required)
expectedHeadSha: The anticipated SHA of the PR's tip (string, optional)
get_pull_request_comments - Retrieves inline review annotations on a PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID (number, required)
get_pull_request_reviews - Fetches formal reviews submitted against a PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID (number, required)
create_pull_request_review - Submits a formal review decision for a PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: Target PR ID (number, required)
body: Review summary text (string, optional)
event: The action taken ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (string, required)
commitId: SHA hash of the commit being reviewed (string, optional)
comments: Structured data for line-by-line feedback (array, optional)
- Inline comments require path, one of (position or line), and body
- Multi-line feedback requires path, start_line, line, optional context sides (side/start_side), and body
create_pull_request - Initiates a new Pull Request resource
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
title: PR headline (string, required)
body: Detailed explanation (string, optional)
head: Source branch containing the modifications (string, required)
base: Target branch for integration (string, required)
draft: Flag to create as an unfinished draft (boolean, optional)
maintainer_can_modify: Permission for repo maintainers to push changes (boolean, optional)
add_pull_request_review_comment - Posts an annotation directly onto a PR's diff or replies to an existing annotation
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pull_number: PR numerical ID (number, required)
body: Content of the annotation (string, required)
commit_id: SHA of the commit being annotated (string, required unless replying)
path: Relative path of the affected file (string, required unless replying)
line: Specific line number in the diff context (number, optional)
side: Which side of the diff to anchor the comment (LEFT/RIGHT) (string, optional)
start_line: Start line for range annotations (number, optional)
start_side: Starting side for range annotations (LEFT/RIGHT) (string, optional)
subject_type: Granularity of the target ('line' or 'file') (string, optional)
in_reply_to: ID of the comment being replied to (number, optional). If present, only body is processed.
update_pull_request - Alters properties of an existing PR
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
pullNumber: PR ID to modify (number, required)
title: New title text (string, optional)
body: New description text (string, optional)
state: New status ('open' or 'closed') (string, optional)
base: New target branch name (string, optional)
maintainer_can_modify: Update modification permission (boolean, optional)

Repositories

create_or_update_file - Creates a new file or overwrites an existing one within a repository
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
path: Location of the file within the repo (string, required)
message: Commit message summary (string, required)
content: Base64 encoded file payload (string, required)
branch: Target branch name (string, optional)
sha: ETag/SHA for optimistic locking during updates (string, optional)
list_branches - Retrieves a list of branches present in a specified repository
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
page: Page index for pagination (number, optional)
perPage: Maximum results per page (number, optional)
push_files - Commits and pushes multiple file changes atomically
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
branch: Branch destination for the changes (string, required)
files: An array detailing each file's path and content (array, required)
message: The commit message summary (string, required)
search_repositories - Executes a query against the public repository index
query: Search criteria string (string, required)
sort: Field to sort results by (string, optional)
order: Ascending or descending order (string, optional)
page: Pagination index (number, optional)
perPage: Results limit per page (number, optional)
create_repository - Provisions a brand new repository resource
name: Desired name for the repository (string, required)
description: Brief explanation of the project (string, optional)
private: Set visibility to private (boolean, optional)
autoInit: Automatically include a starting README file (boolean, optional)
get_file_contents - Fetches the binary or text content of a repository item
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
path: Full path to the file or directory (string, required)
ref: Specific Git reference (branch, tag, or SHA) to query against (string, optional)
fork_repository - Creates a personal or organizational copy of a repository
owner: Source repository owner (string, required)
repo: Source repository name (string, required)
organization: Target organization under which to place the fork (string, optional)
create_branch - Establishes a new branch pointer
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
branch: Name for the new branch (string, required)
sha: The commit SHA to base the new branch upon (string, required)
list_commits - Generates a chronological record of commits for a specified reference
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
sha: Reference point (branch name, tag, or SHA) (string, optional)
path: Filter commits that modified this specific file path (string, optional)
page: Pagination index (number, optional)
perPage: Results per page (number, optional)
get_commit - Retrieves comprehensive metadata for an individual commit object
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
sha: The precise commit SHA (string, required)
page: Pagination index for files listed in the commit (number, optional)
perPage: Results per page for files listed in the commit (number, optional)
search_code - Finds code snippets across repositories matching a query
query: Code search string (string, required)
sort: Field used for sorting results (string, optional)
order: Sort direction (string, optional)
page: Pagination index (number, optional)
perPage: Results limit per page (number, optional)

User Directory

search_users - Performs a lookup for GitHub user accounts
q: Search input string (string, required)
sort: Field to sort results by (string, optional)
order: Sort direction (string, optional)
page: Pagination index (number, optional)
perPage: Results limit per page (number, optional)

Code Analysis

get_code_scanning_alert - Fetches details for a specific static analysis finding
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
alertNumber: The unique identifier for the alert (number, required)
list_code_scanning_alerts - Retrieves all security findings generated by code scanning for a repository
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
ref: Git reference to check (string, optional)
state: Status of the alert ('open', 'dismissed', etc.) (string, optional)
severity: Priority level of the finding (string, optional)
tool_name: Name of the analysis engine used (string, optional)

Secret Protection

get_secret_scanning_alert - Views the specifics of a detected secret leak alert
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
alertNumber: Alert's unique ID (number, required)
list_secret_scanning_alerts - Lists all alerts generated by secret scanning for a repository
owner: Repository owner (string, required)
repo: Repository identifier (string, required)
state: Current resolution status (string, optional)
secret_type: Filter by type of secret detected (comma-separated list) (string, optional)
resolution: Filter by how the alert was handled (string, optional)

Contextual Resource Access

Repository File System Traversal

Get Repository Content Accesses the file or directory structure at the repository root or specified path.
URI Pattern: repo://{owner}/{repo}/contents{/path*}
Parameters:
- owner: Owner identity (string, mandatory)
- repo: Repository slug (string, mandatory)
- path: File path or directory path suffix (string, optional)
Get Content by Branch Pointer Retrieves content based on a specific branch reference.
URI Pattern: repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}
Parameters:
- owner: Owner identity (string, mandatory)
- repo: Repository slug (string, mandatory)
- branch: Branch identifier (string, mandatory)
- path: File path or directory path suffix (string, optional)
Get Content by Commit SHA Retrieves content as it existed at a specific commit hash.
URI Pattern: repo://{owner}/{repo}/sha/{sha}/contents{/path*}
Parameters:
- owner: Owner identity (string, mandatory)
- repo: Repository slug (string, mandatory)
- sha: Commit SHA hash (string, mandatory)
- path: File path or directory path suffix (string, optional)
Get Content by Tag Reference Retrieves content associated with a specific Git tag.
URI Pattern: repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}
Parameters:
- owner: Owner identity (string, mandatory)
- repo: Repository slug (string, mandatory)
- tag: Tag name (string, mandatory)
- path: File path or directory path suffix (string, optional)
Get Content Specific to a PR Head Retrieves content reflecting the state of a pull request's source branch.
URI Pattern: repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}
Parameters:
- owner: Owner identity (string, mandatory)
- repo: Repository slug (string, mandatory)
- prNumber: Pull Request numerical ID (string, mandatory)
- path: File path or directory path suffix (string, optional)

Library Interface

The exported Go Application Programming Interface (API) for this module is currently deemed experimental and subject to modification without notice. Stability assurances may be provided later; file an issue if API stability is critical to your use case.

Licensing

This software is distributed under the MIT Open Source License terms. Full details are located in the MIT file.

Contextual Note on Business Management Tools (Derived from Wikipedia): Organizational management tools encompass methodologies, applications, and systems designed to help entities adapt to market shifts, maintain competitive advantage, and elevate overall performance. These tools span functional areas such as planning, process control, data analysis, and decision support. Modern business software has rapidly transformed from legacy Management Information Systems (MIS) to comprehensive cloud-based Enterprise Resource Planning (ERP) and Customer Relationship Management (CRM) solutions. Effective implementation hinges upon judicious tool selection tailored to specific organizational requirements, rather than merely adopting the newest available technology.

gh-mcp-connector

Author

rshivamrapid

Quick Info

Actions

Tags