DOCSEARCHbyAlgolia
Submit Docs

GitHub MCP Server

repository·main·Indexed 12 days ago

https://github.com/github/github-mcp-server

A Model Context Protocol (MCP) interface that allows AI agents and tools to interact with GitHub for automated repository management, issue/PR handling, and code analysis. It supports installation via Docker, pre-built binaries, or source builds (Go 1.24+), and provides a remote server option for VS Code. Includes mcpcurl, a CLI tool for executing MCP tools via stdio.

Tokens
62.5K
Snippets
136
Records
248
Agent score
98%

What's inside GitHub MCP Server

  1. Overview of GitHub MCP Server use cases

    main

    The GitHub MCP Server connects AI tools directly to GitHub, allowing AI agents and assistants to interact with your repositories via natural language. Key capabilities include:

    • Repository Management: Browsing code, searching files, analyzing commits, and understanding project structures.
    • Issue & PR Automation: Creating and managing issues and pull requests, triaging bugs, and reviewing code changes.
    • CI/CD & Workflow Intelligence: Monitoring GitHub Actions, analyzing build failures, and managing releases.
    • Code Analysis: Examining security findings, reviewing Dependabot alerts, and understanding code patterns.
    • Team Collaboration: Accessing discussions, managing notifications, and analyzing team activity.

  2. Check GitHub MCP Server support by host application

    main

    Support varies by host application regarding Local and Remote MCP capabilities.

    Key takeaways:

    • Remote Support: Most applications support Remote MCP via Personal Access Tokens (PAT), but only VS Code currently supports full remote GitHub server support (including OAuth).
    • OAuth vs PAT: Many applications (Claude Desktop, Cline, Cursor, etc.) support PAT for remote connections but do not yet support OAuth.
    • Copilot Coding Agent: Supports full remote capabilities by default with no additional authentication needed, provided you have a paid Copilot license.

    Refer to the support matrix in the installation guides to confirm if your specific IDE (e.g., JetBrains, Zed, Windsurf, Xcode) supports the connection type you require.

  3. E2E Test Limitations and Scope

    main

    The E2E test suite has the following characteristics and limitations:

    • Scope: The suite is intentionally limited to minimize maintenance costs associated with GitHub integration tests.
    • Global State: Tools that mutate global state (e.g., marking all notifications as read) or are not idempotent are excluded from E2E tests. These should be handled via unit tests or manual verification.
    • Visibility: Failure visibility in the black-box Docker mode is currently limited. Using GITHUB_MCP_SERVER_E2E_DEBUG=true is the recommended workaround for deep inspection.

  4. Compare authentication methods and scope handling

    main

    The GitHub MCP Server handles tool visibility differently depending on your authentication method:

    AuthenticationScope Handling
    Classic PAT (ghp_)Filters tools at startup based on token scopes—tools requiring unavailable scopes are hidden
    OAuth (remote server only)Uses scope challenges—when a tool needs a scope you haven't granted, you're prompted to authorize it
    Fine-grained PAT (github_pat_)No filtering—all tools shown, API enforces permissions
    GitHub App (ghs_)No filtering—all tools shown, permissions based on app installation
    Server-to-serverNo filtering—all tools shown, permissions based on app/token configuration

  5. Understand the differences between Remote and Local MCP Servers

    main

    The remote GitHub MCP server is a hosted version of this repository's logic, integrated into GitHub's infrastructure.

    Key Difference: The remote server includes additional tools not available in the local version. Specifically, it provides the create_pull_request_with_copilot tool, which allows you to invoke the Copilot coding agent to create pull requests.

  6. How to use toolsnaps for tool schema snapshots

    main

    The toolsnaps utility prevents unexpected changes to tool JSON schemas by comparing current schemas against stored snapshots.

    • Storage: Snapshots are stored in __toolsnaps__/*.snap files.
    • Failure Behavior: If a schema differs from the snapshot, the test fails and displays a diff. In CI (when GITHUB_ACTIONS=true), missing snapshots cause test failures to ensure all snapshots are committed.
    • Updating Snapshots: If you have intentionally changed a tool's schema, you must update the snapshots by running the tests with the UPDATE_TOOLSNAPS=true environment variable.
    UPDATE_TOOLSNAPS=true go test ./...

  7. Distinguish between User-Actionable and Developer errors

    main

    The server follows a specific design principle for error classification to ensure proper client feedback and system stability:

    • User-actionable errors: These are errors the end-user can potentially fix (e.g., authentication failures, rate limits, or 404 Not Found). These must be returned as failed tool calls using the ghErrors response functions.
    • Developer errors: These are internal system failures (e.g., JSON marshaling failures, internal logic errors, or database connection issues). These should be returned as actual Go error values that bubble up through the MCP framework.

  8. How feature flags are resolved

    main

    The GitHub MCP Server uses a hierarchical resolution system for feature flags. This determines which experimental or specific tools are available to a client. The resolution follows this order:

    1. User Input: Users can explicitly opt into specific features.
      • Local server: Use the --features=<flag>,<flag> CLI flag or set the GITHUB_FEATURES environment variable.
      • Self-hosted HTTP server: Use the X-MCP-Features: <flag>,<flag> request header.
    2. Allowlist Filter: User-supplied flags are checked against AllowedFeatureFlags. If a flag is not on this allowlist, it is silently dropped. Only flags on the allowlist can be enabled via user input.
    3. Insiders Expansion: If Insiders Mode is enabled (via --insiders, the /insiders route, or the X-MCP-Insiders: true header), all flags defined in InsidersFeatureFlags are automatically enabled. Note that Insiders expansion bypasses the allowlist filter, allowing access to internal-only flags.
    4. Server-side Fallback: For remote servers, any undecided flags fall back to the remote server's internal feature manager.
    # Example: Enabling specific features on a local server via CLI
./github-mcp-server --features=flag1,flag2

# Example: Enabling specific features via environment variable
export GITHUB_FEATURES="flag1,flag2"
./github-mcp-server

  9. Configure GitHub MCP Server tool access

    main

    The GitHub MCP Server can be configured to enable or disable specific tools and toolsets. Configuration is composable, meaning you can combine toolsets, individual tools, and exclusions.

    Precedence Rules:

    1. Read-only mode is a strict security filter that takes precedence over all other configurations by disabling write tools, even if explicitly requested.
    2. Excluded tools take precedence over toolsets and individual tools; if a tool is in the exclusion list, it will not be available even if its toolset is enabled or it is explicitly added.

    Default Behavior: If no configuration is provided, the server enables the following default toolsets: context, issues, pull_requests, repos, and users.

  10. Understand MCP Architecture for GitHub Integration

    main

    The Model Context Protocol (MCP) allows a client application (like an IDE) to connect to multiple MCP Servers. GitHub provides two types of servers:

    1. Local MCP Server: Runs side-by-side with the application, typically communicating via stdio.
    2. Remote MCP Server: Hosted remotely and accessed over the internet via OAuth 2.0 + HTTP/SSE.

    An MCP Client within your application maintains a 1:1 connection with a single MCP server to orchestrate tool calls.

  11. Use Device Code flow for headless authentication

    main
    If the server cannot use the authorization code flow (e.g., in a remote shell, CI, or a container without a published port), it falls back to the device-code flow. The server will provide a short code and a verification URL (e.g., https://github.com/login/device). You must visit this URL on any device and enter the provided code to authorize the server.

  12. Choose between GitHub Apps and OAuth Apps for MCP

    main

    To enable OAuth for your MCP client, you must use either a GitHub App or an OAuth App.

    GitHub Apps (Recommended)

    • Security: More secure as they support expiration and fine-grained permissions.
    • Lifecycle: Must be installed on a GitHub Organization (requires admin approval) before use.
    • Usage: Use the Web Application Flow to generate user access tokens.

    OAuth Apps

    • Lifecycle: Do not require installation and can typically be used immediately.
    • Usage: Use the Web Application Flow for authorization.

    Security Warning for Client Authors

    Both app types require a client secret to initiate the OAuth flow. If your application runs in an uncontrolled environment (e.g., customer-provided hardware), users may discover your secret. In these cases, register a new GitHub App/OAuth App exclusively for your client application to limit exposure.