github-mcp-server

# 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)**: ```yaml tools: github: mode: "local" toolsets: [default] # or [repos, issues, pull_requests] ``` **Remote Mode (Hosted)**: ```yaml tools: github: mode: "remote" toolsets: [default] # or [repos, issues, pull_requests] ``` ### Read-Only Mode To restrict the GitHub MCP server to read-only operations: ```yaml tools: github: mode: "remote" read-only: true toolsets: [repos, issues] ``` ### Custom Authentication Use a custom GitHub token instead of the default: ```yaml 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](#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 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):** ```yaml tools: github: allowed: - get_repository - get_file_contents - list_commits - list_issues - create_issue - update_issue ``` **Using `toolsets:` (recommended):** ```yaml 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 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]