github-mcp-server

name github-mcp-server description Reference for GitHub MCP server tools, methods, and usage patterns. GitHub MCP Server Documentation This file documents the GitHub MCP (Model Context Protocol) server, including 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 ⚠️ (always include state: open and severity: critical,high ), 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 ⚠️ (see note below), get_user , list_users search Advanced search Search across repos, code, users :::caution[ get_me returns 403 under the integration token] get_me is not recommended in agentic workflows. It returns HTTP 403 when called under the GitHub Actions integration token (which is the default in all gh-aw runs). Do not call get_me to determine the agent's identity. Canonical identity source : The <github-context> block is injected at the start of every workflow prompt and contains actor , repository , run_id , and other context values. Always read identity from there. ::: 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 When invoking list_pull_requests from workflow prompts/templates: Default to a small page size ( perPage: 10 unless a smaller/larger value is justified). On GitHub MCP server ≥ 1.6.0 with the fields_param feature (enabled automatically in Insiders mode), pass fields: [number, title, state, html_url] (or whichever top-level fields you need) to reduce response size. The same fields parameter is available on list_issues , search_issues , search_pull_requests , list_commits , list_releases , and search_code . For get_file_contents , fields only reduces directory listings; use fields: [name, type, size, path] to check file metadata before deciding whether to read a file. Before using get_file_contents on a file, list its parent directory with fields: [name, type, size, path] . If the file is large or you only need a header/section, use a bounded excerpt such as a raw file URL with an HTTP range or another available ranged-read tool instead of fetching the whole file. On older servers, request minimal_output: true when the installed MCP server exposes that input (minimal output trims non-essential nested fields such as large head / base payloads). Confirm parameter support in the method schema from mcp list-tools or the tool docs for your server version. 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 When invoking list_code_scanning_alerts from workflow prompts/templates, always include state: open and severity: critical,high to bound the response size and avoid oversized payloads. 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 - ⚠️ Not recommended — returns HTTP 403 under the integration token. Use the <github-context> block (provided at the start of every prompt) to read your identity: actor , repository , run_id , etc. 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 ⚠️ (not recommended — returns 403; use <github-context> instead) 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 ⚠️ (always include state: open and severity: critical,high ), 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]