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:

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