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

Migration from Allowed to Toolsets

If you have existing workflows using the allowed: pattern, we recommend migrating to toolsets: for better maintainability and stability. Individual tool names may change between MCP server versions, but toolsets provide a stable API that won't break your workflows.

Migration Examples

Using allowed: (not recommended):

tools:
  github:
    allowed:
      - get_repository
      - get_file_contents
      - list_commits
      - list_issues
      - create_issue
      - update_issue

Using toolsets: (recommended):

tools:
  github:
    toolsets: [repos, issues]

Tool-to-Toolset Mapping

Use this table to identify which toolset contains the tools you need:

Quick Migration Steps

1. Identify tools in use: Review your current allowed: list
2. Map to toolsets: Use the table above to find corresponding toolsets
3. Replace configuration: Change allowed: to toolsets:
4. Test: Run gh aw mcp inspect <workflow> to verify tools are available
5. Compile: Run gh aw compile to update the lock file

Using Allowed Pattern with Custom MCP Servers

:::note[When to Use Allowed] The allowed: pattern is appropriate for:

• Custom MCP servers (non-GitHub)
• Gradual migration of existing workflows
• Fine-grained restriction of specific tools within a toolset

For GitHub tools, always use toolsets: instead of allowed:. :::

The allowed: field can still be used to restrict tools for custom MCP servers:

mcp-servers:
  notion:
    container: "mcp/notion"
    allowed: ["search_pages", "get_page"]  # Fine for custom MCP servers

For GitHub tools, allowed: can be combined with toolsets: to further restrict access, but this pattern is not recommended for new workflows.

GitHub API Limitations

Not all GitHub data is accessible through the GitHub MCP server or the GitHub REST API. Be aware of these limitations when designing workflows to avoid silent failures or incomplete results at runtime.

Billing and Cost Data

❌ Not available via standard API permissions:

• Detailed per-run cost data — GitHub Actions does not expose per-workflow-run billing costs through the REST API. There is no endpoint to retrieve the exact cost of a specific workflow run.
• Actions billing summary — Billing endpoints (e.g., /orgs/{org}/settings/billing/actions) require admin:org scope, which is not granted by actions:read or the default GITHUB_TOKEN.

⚠️ When suggesting billing/cost workflows, always note:

Detailed GitHub Actions billing and cost data is not accessible through the standard GitHub API with actions:read permissions. Workflows that attempt to read per-run cost data or billing summaries will fail silently or return empty results unless an admin:org-scoped personal access token is explicitly configured.

✅ Alternatives for cost reporting:

1. GitHub Actions usage reports — Download usage reports from the GitHub billing UI (Settings → Billing → Usage) or via the billing CSV export endpoint (requires admin:org scope with a PAT).
2. Billing settings UI — Direct users to https://github.com/organizations/{org}/settings/billing or https://github.com/settings/billing for personal accounts to view cost data manually.
3. Workflow run metadata — Use list_workflow_runs and get_workflow_run (available via actions toolset) to get run duration, status, and timing — but not dollar costs.
4. Third-party cost tracking — Integrate with third-party CI cost tools that use pre-authorized API access.

Cross-Organization Data Access

❌ Not available without explicit authorization:

• Workflows can only access data from repositories and organizations that the configured GitHub token has been granted access to.
• Cross-organization repository reads require a PAT or GitHub App token with access to the target org — the default GITHUB_TOKEN is scoped to the current repository's organization only.
• Organization membership and team data from other organizations is not accessible without explicit read:org permissions on those organizations.

Organization Membership and Private Data

❌ Requires additional scopes:

• Organization member lists — Reading private organization membership requires read:org scope; the default GITHUB_TOKEN only exposes public membership.
• Private repository contents — Only accessible if the token has explicit repository access.
• Secret values — GitHub Secrets are write-only through the API; their values cannot be read back after creation.

Rate Limits

⚠️ Be aware of API rate limits:

• The GitHub REST API enforces rate limits (typically 5,000 requests/hour for authenticated requests with a PAT, lower for GITHUB_TOKEN).
• Workflows that perform bulk data collection (e.g., listing all workflow runs across many repositories) may hit rate limits. Design workflows to paginate carefully and avoid unnecessary requests.
• GraphQL API has separate rate limits based on query complexity.

Troubleshooting

Common Issues

Issue: Tool not found or not available

• Solution: Check if you're using allowed: to restrict tools. Consider using toolsets: instead to get all related tools.
• Verify: Run gh aw mcp inspect <workflow-name> to see which tools are actually available.

Issue: Missing functionality after specifying toolset

• Cause: Using a too-narrow toolset that doesn't include all needed tools
• Solution: Either add additional toolsets (e.g., toolsets: [default, actions]) or use [all] for full access

Issue: Workflow using allowed: list is verbose and hard to maintain

• Solution: Migrate to toolsets: configuration using the migration guide above

Best Practices for Debugging

1. Start with [default] toolset: Most workflows work well with default toolsets
2. Add specific toolsets as needed: Incrementally add toolsets like actions, discussions, etc.
3. Use gh aw mcp inspect: Verify which tools are actually available
4. Check tool-to-toolset mapping: Reference the tables above to find the right toolset

References

• GitHub MCP Server Repository
• Model Context Protocol Specification
• GitHub Actions Documentation