GitHub MCP Server

GitHub MCP Server Documentation

This file documents the GitHub MCP (Model Context Protocol) server, including tools and configuration options.

Note: This file is automatically generated and updated by the github-mcp-tools-report.md workflow. Manual edits may be overwritten.

Last Updated: [To be filled by workflow]

Overview

The GitHub MCP server provides AI agents with programmatic access to GitHub's API through the Model Context Protocol. It supports two modes of operation:

Local Mode (Docker-based)

• Runs as a Docker container on the GitHub Actions runner
• Uses GITHUB_PERSONAL_ACCESS_TOKEN environment variable for authentication
• Configurable toolsets via GITHUB_TOOLSETS environment variable
• Supports read-only mode via GITHUB_READ_ONLY environment variable

Remote Mode (Hosted)

• Connects to hosted GitHub MCP server at https://api.githubcopilot.com/mcp/
• Uses Bearer token authentication in HTTP headers
• Supports read-only mode via X-MCP-Readonly header
• No Docker container required

Configuration

Basic Configuration

Local Mode (Docker):

tools:
  github:
    mode: "local"
    toolsets: [default]  # or [repos, issues, pull_requests]

Remote Mode (Hosted):

tools:
  github:
    mode: "remote"
    toolsets: [default]  # or [repos, issues, pull_requests]

Read-Only Mode

To restrict the GitHub MCP server to read-only operations:

tools:
  github:
    mode: "remote"
    read-only: true
    toolsets: [repos, issues]

Custom Authentication

Use a custom GitHub token instead of the default:

tools:
  github:
    mode: "remote"
    github-token: "${{ secrets.CUSTOM_GITHUB_PAT }}"
    toolsets: [repos, issues]

Available Toolsets

The GitHub MCP server organizes tools into logical toolsets. You can enable specific toolsets, use [default] for the recommended defaults, or use [all] to enable everything.

:::note[Why Use Toolsets?] The allowed: pattern for listing individual GitHub tools is not recommended for new workflows. Individual tool names may change between GitHub MCP server versions, but toolsets provide a stable API. Always use toolsets: instead. See Migration from Allowed to Toolsets for guidance on updating existing workflows. :::

:::tip[Best Practice] Always use toolsets: for GitHub tools. Toolsets provide:

• Stability: Tool names may change between MCP server versions, but toolsets remain stable
• Better organization: Clear groupings of related functionality
• Complete functionality: Get all related tools automatically
• Reduced verbosity: Cleaner configuration
• Future-proof: New tools are automatically included as they're added :::

Recommended Default Toolsets

The following toolsets are enabled by default when toolsets: is not specified:

• context - User and environment context (strongly recommended)
• repos - Repository management
• issues - Issue management
• pull_requests - Pull request operations

Note: The users toolset is not included by default and must be explicitly specified if needed.

All Available Toolsets

:::caution[get_me returns 403 under the integration token] get_me is not recommended in agentic workflows. It returns HTTP 403 when called under the GitHub Actions integration token (which is the default in all gh-aw runs). Do not call get_me to determine the agent's identity.

Canonical identity source: The <github-context> block is injected at the start of every workflow prompt and contains actor, repository, run_id, and other context values. Always read identity from there. :::

Available Tools by Toolset

This section maps individual tools to their respective toolsets to help with migration from allowed: to toolsets:.

Context Toolset

• get_teams - List teams the user belongs to
• get_team_members - List members of a specific team

Repos Toolset

• get_repository - Get repository information
• get_file_contents - Read file contents from repository
• search_code - Search code across repositories
• list_commits - List commits in a repository
• get_commit - Get details of a specific commit
• get_latest_release - Get the latest release
• list_releases - List all releases

Issues Toolset

• issue_read - Read issue details
• list_issues - List issues in a repository
• create_issue - Create a new issue
• update_issue - Update an existing issue
• search_issues - Search issues across repositories
• add_reaction - Add reaction to an issue or comment
• create_issue_comment - Add a comment to an issue

Pull Requests Toolset

• pull_request_read - Read pull request details
• list_pull_requests - List pull requests in a repository
• get_pull_request - Get details of a specific pull request
• create_pull_request - Create a new pull request
• search_pull_requests - Search pull requests across repositories

When invoking list_pull_requests from workflow prompts/templates:

• Default to a small page size (perPage: 10 unless a smaller/larger value is justified).
• On GitHub MCP server ≥ 1.6.0 with the fields_param feature (enabled automatically in Insiders mode), pass fields: [number, title, state, html_url] (or whichever top-level fields you need) to reduce response size. The same fields parameter is available on list_issues, search_issues, search_pull_requests, list_commits, list_releases, and search_code. For get_file_contents, fields only reduces directory listings; use fields: [name, type, size, path] to check file metadata before deciding whether to read a file.
• Before using get_file_contents on a file, list its parent directory with fields: [name, type, size, path]. If the file is large or you only need a header/section, use a bounded excerpt such as a raw file URL with an HTTP range or another available ranged-read tool instead of fetching the whole file.
• On older servers, request minimal_output: true when the installed MCP server exposes that input (minimal output trims non-essential nested fields such as large head/base payloads).
• Confirm parameter support in the method schema from mcp list-tools or the tool docs for your server version.

Actions Toolset

• list_workflows - List GitHub Actions workflows
• list_workflow_runs - List workflow runs
• get_workflow_run - Get details of a specific workflow run
• download_workflow_run_artifact - Download workflow artifacts

Code Security Toolset

• list_code_scanning_alerts - List code scanning alerts
• get_code_scanning_alert - Get details of a specific alert
• create_code_scanning_alert - Create a code scanning alert

When invoking list_code_scanning_alerts from workflow prompts/templates, always include state: open and severity: critical,high to bound the response size and avoid oversized payloads.

Discussions Toolset

• list_discussions - List discussions in a repository
• create_discussion - Create a new discussion

Labels Toolset

• get_label - Get label details
• list_labels - List labels in a repository
• create_label - Create a new label

Users Toolset

• get_me - ⚠️ Not recommended — returns HTTP 403 under the integration token. Use the <github-context> block (provided at the start of every prompt) to read your identity: actor, repository, run_id, etc.
• get_user - Get user profile information
• list_users - List users

Notifications Toolset

• list_notifications - List user notifications
• mark_notifications_read - Mark notifications as read

Organizations Toolset

• get_organization - Get organization details
• list_organizations - List organizations

Gists Toolset

• create_gist - Create a new gist
• list_gists - List user's gists

Authentication Details

Remote Mode Authentication

The remote mode uses Bearer token authentication:

Headers:

• Authorization: Bearer <token> - Required for authentication
• X-MCP-Readonly: true - Optional, enables read-only mode

Token Source:

• Default: ${{ secrets.GH_AW_GITHUB_TOKEN }} or ${{ secrets.GITHUB_TOKEN }}
• Custom: Configure via github-token field

Local Mode Authentication

The local mode uses environment variables:

Environment Variables:

• GITHUB_PERSONAL_ACCESS_TOKEN - Required for authentication
• GITHUB_READ_ONLY=1 - Optional, enables read-only mode
• GITHUB_TOOLSETS=<comma-separated-list> - Optional, specifies enabled toolsets

Best Practices

Toolset Selection

1. Start with defaults: For most workflows, the recommended default toolsets provide sufficient functionality
2. Enable specific toolsets: Only enable additional toolsets when you need their specific functionality
3. Security consideration: Be mindful of write operations - consider using read-only mode when possible
4. Performance: Using fewer toolsets reduces initialization time and memory usage

Token Permissions

Ensure your GitHub token has appropriate permissions for the toolsets you're enabling:

• repos toolsets: Requires repository read/write permissions
• issues toolsets: Requires issues read/write permissions
• pull_requests toolsets: Requires pull requests read/write permissions
• actions toolsets: Requires actions read/write permissions
• discussions toolsets: Requires discussions read/write permissions

Remote vs Local Mode

Use Remote Mode when:

• You want faster initialization (no Docker container to start)
• You're running in a GitHub Actions environment with internet access
• You want to use the latest version without specifying Docker image tags

Use Local Mode when:

• You need a specific version of the MCP server
• You want to use custom arguments
• You're running in an environment without internet access
• You want to test with a local build of the MCP server