github-mcp-server

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

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

---

*Content truncated.*