GitHub MCP Server Documentation

This file contains comprehensive documentation about the GitHub MCP (Model Context Protocol) server, including available tools and configuration options.

Note: This file is automatically generated and updated by the

github-mcp-tools-report.md

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]

[all]

:::note[Why Use Toolsets?] The

allowed:

toolsets:

:::tip[Best Practice] Always use

toolsets:

• 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:

• context

  - User and environment context (strongly recommended)

• repos

  - Repository management

• issues

  - Issue management

• pull_requests

  - Pull request operations

Note: The

users

All Available Toolsets

context

get_teams

get_team_members

repos

get_repository

get_file_contents

search_code

list_commits

issues

issue_read

list_issues

create_issue

search_issues

pull_requests

pull_request_read

list_pull_requests

create_pull_request

actions

list_workflows

list_workflow_runs

download_workflow_run_artifact

code_security

list_code_scanning_alerts

get_code_scanning_alert

dependabot

discussions

list_discussions

create_discussion

experiments

gists

create_gist

list_gists

labels

get_label

list_labels

create_label

notifications

list_notifications

mark_notifications_read

orgs

get_organization

list_organizations

projects

secret_protection

security_advisories

stargazers

users

get_me

get_user

list_users

search

Available Tools by Toolset

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

allowed:

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

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

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

  - Get current authenticated user information

• 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:

toolsets:

Migration Examples

Using

allowed:

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

Using

toolsets:

tools:
  github:
    toolsets: [repos, issues]

Tool-to-Toolset Mapping

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

allowed:

toolsets:

get_me

users

get_teams

get_team_members

context

get_repository

get_file_contents

search_code

list_commits

repos

issue_read

list_issues

create_issue

update_issue

search_issues

issues

pull_request_read

list_pull_requests

create_pull_request

pull_requests

list_workflows

list_workflow_runs

get_workflow_run

actions

list_code_scanning_alerts

get_code_scanning_alert

code_security

list_discussions

create_discussion

discussions

get_label

list_labels

create_label

labels

get_user

list_users

users

[default]

[all]

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:

• 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:

allowed:

The

allowed:

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

For GitHub tools,

allowed:

toolsets:

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:

• 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