name	github-mcp-server
description	GitHub MCP Server Documentation

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

Toolset	Description	Common Tools
`context`	User and environment context	`get_teams`, `get_team_members`
`repos`	Repository management	`get_repository`, `get_file_contents`, `search_code`, `list_commits`
`issues`	Issue management	`issue_read`, `list_issues`, `create_issue`, `search_issues`
`pull_requests`	Pull request operations	`pull_request_read`, `list_pull_requests`, `create_pull_request`
`actions`	GitHub Actions/CI/CD	`list_workflows`, `list_workflow_runs`, `download_workflow_run_artifact`
`code_security`	Code scanning and security	`list_code_scanning_alerts`, `get_code_scanning_alert`
`dependabot`	Dependency management	Dependabot alerts and updates
`discussions`	GitHub Discussions	`list_discussions`, `create_discussion`
`experiments`	Experimental features	Unstable/preview APIs
`gists`	Gist operations	`create_gist`, `list_gists`
`labels`	Label management	`get_label`, `list_labels`, `create_label`
`notifications`	Notifications	`list_notifications`, `mark_notifications_read`
`orgs`	Organization management	`get_organization`, `list_organizations`
`projects`	GitHub Projects	Project board operations
`secret_protection`	Secret scanning	Secret detection and management
`security_advisories`	Security advisories	Advisory creation and management
`stargazers`	Repository stars	Star-related operations
`users`	User profiles	`get_me`, `get_user`, `list_users`
`search`	Advanced search	Search across repos, code, users

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

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

Start with defaults: For most workflows, the recommended default toolsets provide sufficient functionality
Enable specific toolsets: Only enable additional toolsets when you need their specific functionality
Security consideration: Be mindful of write operations - consider using read-only mode when possible
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:

`allowed:` Tools	Migrate to `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`
Mixed repos/issues/PRs tools	`[default]`
All tools	`[all]`

Quick Migration Steps

Identify tools in use: Review your current allowed: list
Map to toolsets: Use the table above to find corresponding toolsets
Replace configuration: Change allowed: to toolsets:
Test: Run gh aw mcp inspect <workflow> to verify tools are available
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.

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

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

Install Skill

SKILL.md