---
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)**:
```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`, `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):**
```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` | `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:

```yaml
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](https://github.com/github/github-mcp-server)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [GitHub Actions Documentation](https://docs.github.com/actions)