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

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

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.

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