github-mcp-server

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

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:

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

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