GitHub MCP Server Instructions

Source: github/github-mcp-server Mapping File: pkg/workflow/data/github_toolsets_permissions.json Last Updated: 2026-05-24

Overview

The GitHub MCP server provides tools to interact with GitHub APIs through the Model Context Protocol (MCP). It operates in two modes:

• Remote mode: Connects to GitHub's hosted MCP endpoint (https://api.githubcopilot.com/mcp/)
• Local mode: Runs gh mcp (GitHub CLI) as a local subprocess

Authentication

Remote mode: Uses a Bearer token in the Authorization header:

Authorization: Bearer <github-token>

Read-only mode: Add the X-MCP-Readonly: true header to restrict to read operations only:

X-MCP-Readonly: true

Local mode: Uses the GitHub CLI's existing authentication (gh auth login).

Configuration

In Agentic Workflows

tools:
  github:
    toolsets: [default]     # or specific toolsets
    # Optional: GitHub App authentication
    github-app:
      client-id: ${{ vars.APP_ID }}
      private-key: ${{ secrets.APP_PRIVATE_KEY }}

⚠️ Do NOT use mode: remote in GitHub Actions workflows. Remote mode does not work with the GitHub Actions token (GITHUB_TOKEN) — it requires a special PAT or GitHub App token with MCP access. The default mode: local (Docker-based) works with GITHUB_TOKEN and should always be used.

Toolset Options

• [default] — Recommended defaults: context, repos, issues, pull_requests
• [all] — Enable all toolsets
• Specific toolsets: [repos, issues, pull_requests, discussions]
• Extend defaults: [default, discussions, actions]

Recommended Default Toolsets

The following toolsets are recommended as defaults for typical agentic workflows:

Toolset	Rationale
context	Identity and team awareness (get_me, get_teams) — essential for any GitHub-aware agent
repos	Core repository operations (read files, list commits/branches) — most workflows need file access
issues	Issue management (read, comment, create) — common in CI/CD and automation workflows
pull_requests	PR operations (read, create, review) — critical for code review and merge automation

Enable explicitly when needed (not in defaults):

Toolset	When to Enable
actions	Workflow introspection, triggering runs
code_security	Code scanning alert management
copilot_spaces	GitHub Copilot Spaces (remote mode only)
dependabot	Dependency vulnerability management
discussions	Community discussion workflows
experiments	Dynamic toolset management
gists	Gist creation and management
git	Git API operations (tree, refs)
github_support_docs_search	GitHub support documentation search (remote mode only)
labels	Label management automation
notifications	Notification processing agents
orgs	Organization-level security advisories
projects	GitHub Projects automation (requires PAT)
search	Cross-repository search operations
secret_protection	Secret scanning alert management
security_advisories	Advisory database queries
stargazers	Star/unstar repository operations
users	(currently empty — no tools registered)

Tools by Toolset

context

Description: GitHub context and environment (current user, teams)

Tool	Purpose	Key Parameters
get_me	Get details of the authenticated user	—
get_team_members	List members of a GitHub team	org, team_slug
get_teams	List teams the authenticated user belongs to	org

---

copilot_spaces

Description: GitHub Copilot Spaces (remote-only)

Note: Remote-only toolset — only available when using the GitHub MCP server in remote mode (https://api.githubcopilot.com/mcp/). Not available with the local gh mcp mode.

Tool	Purpose	Key Parameters
get_copilot_space	Get details of a specific Copilot Space	owner, name
list_copilot_spaces	List Copilot Spaces for a user or organization	owner

---

repos

Description: Repository operations

Tool	Purpose	Key Parameters
create_branch	Create a new branch	owner, repo, branch, from_branch
create_or_update_file	Create or update a file in a repository	owner, repo, path, content, message, branch
create_repository	Create a new GitHub repository	name, description, private, auto_init
delete_file	Delete a file from a repository	owner, repo, path, message, sha, branch
fork_repository	Fork a repository	owner, repo, organization
get_commit	Get details of a specific commit	owner, repo, sha
get_file_contents	Read file or directory contents	owner, repo, path, ref
get_latest_release	Get the latest release for a repository	owner, repo
get_release_by_tag	Get a release by its tag name	owner, repo, tag
get_tag	Get details of a specific tag	owner, repo, tag
list_branches	List branches in a repository	owner, repo, page, per_page
list_commits	List commits in a repository	owner, repo, sha, path, page
list_releases	List all releases for a repository	owner, repo, page, per_page
list_repository_collaborators	List collaborators of a repository	owner, repo, affiliation, page, per_page
list_tags	List tags in a repository	owner, repo, page, per_page
push_files	Push multiple files in a single commit	owner, repo, branch, files, message

---

git

Description: Git API operations (tree, refs)

Tool	Purpose	Key Parameters
get_repository_tree	Get the file tree of a repository	owner, repo, sha, recursive

---

github_support_docs_search

Description: GitHub support documentation search (remote-only)

Note: Remote-only toolset — only available when using the GitHub MCP server in remote mode (https://api.githubcopilot.com/mcp/). Not available with the local gh mcp mode.

Tool	Purpose	Key Parameters
github_support_docs_search	Search GitHub support documentation	query

---

issues

Description: Issue management

Tool	Purpose	Key Parameters
add_issue_comment	Add a comment to an issue	owner, repo, issue_number, body
issue_read	Read issue details and comments	owner, repo, issue_number
issue_write	Create or update an issue	owner, repo, title, body, labels, assignees
list_issue_types	List available issue types for a repository	owner, repo
list_issues	List issues in a repository	owner, repo, state, labels, page
search_issues	Search issues across GitHub	query, page, per_page
sub_issue_write	Create or manage sub-issues	owner, repo, issue_number

---

pull_requests

Description: Pull request operations

Tool	Purpose	Key Parameters
add_comment_to_pending_review	Add a comment to a pending PR review	owner, repo, pull_number, review_id
add_reply_to_pull_request_comment	Reply to a PR review comment	owner, repo, pull_number, comment_id, body
create_pull_request	Create a new pull request	owner, repo, title, body, head, base
list_pull_requests	List pull requests in a repository	owner, repo, state, head, base
merge_pull_request	Merge a pull request	owner, repo, pull_number, merge_method
pull_request_read	Read PR details, reviews, and comments	owner, repo, pull_number
pull_request_review_write	Create or submit a PR review	owner, repo, pull_number, event, body
search_pull_requests	Search pull requests across GitHub	query, page, per_page
update_pull_request	Update PR title, body, or state	owner, repo, pull_number, title, body
update_pull_request_branch	Update PR branch with latest base	owner, repo, pull_number

---

actions

Description: GitHub Actions workflows

Tool	Purpose	Key Parameters
actions_get	Get details of a specific workflow run	owner, repo, run_id
actions_list	List GitHub Actions workflows and runs	owner, repo, method, resource_id, per_page, page
actions_run_trigger	Trigger a workflow run	owner, repo, workflow_id, ref, inputs
get_job_logs	Download logs for a specific workflow job	owner, repo, job_id

---

code_security

Description: Code scanning alerts

Tool	Purpose	Key Parameters
get_code_scanning_alert	Get details of a specific code scanning alert	owner, repo, alert_number
list_code_scanning_alerts	List code scanning alerts for a repository	owner, repo, state, severity

---

dependabot

Description: Dependabot alerts

Tool	Purpose	Key Parameters
get_dependabot_alert	Get details of a specific Dependabot alert	owner, repo, alert_number
list_dependabot_alerts	List Dependabot alerts for a repository	owner, repo, state, severity

---

discussions

Description: GitHub Discussions

Tool	Purpose	Key Parameters
get_discussion	Get details of a specific discussion	owner, repo, discussion_number
get_discussion_comments	Get comments for a specific discussion	owner, repo, discussion_number
list_discussion_categories	List discussion categories for a repository	owner, repo
list_discussions	List discussions in a repository	owner, repo, category_id

---

experiments

Description: Experimental features — dynamic toolset management

Tool	Purpose	Key Parameters
enable_toolset	Dynamically enable a toolset	toolset
get_toolset_tools	Get tools available in a specific toolset	toolset
list_available_toolsets	List all available toolsets	—

---

gists

Description: Gist operations

Tool	Purpose	Key Parameters
create_gist	Create a new gist	description, files, public
get_gist	Get a specific gist by ID	gist_id
list_gists	List gists for a user	username, page, per_page
update_gist	Update an existing gist	gist_id, description, files

---

labels

Description: Label management

Tool	Purpose	Key Parameters
get_label	Get details of a specific label	owner, repo, name
label_write	Create or update a label	owner, repo, name, color, description
list_label	List labels in a repository	owner, repo, page, per_page

---

notifications

Description: Notification management

Tool	Purpose	Key Parameters
dismiss_notification	Dismiss a specific notification	notification_id
get_notification_details	Get details of a specific notification	notification_id
list_notifications	List user notifications	all, participating, page
manage_notification_subscription	Manage notification subscription for a thread	thread_id, subscribed
manage_repository_notification_subscription	Manage notifications for a repository	owner, repo, subscribed
mark_all_notifications_read	Mark all notifications as read	last_read_at

---

orgs

Description: Organization operations

Tool	Purpose	Key Parameters
list_org_repository_security_advisories	List security advisories for all repos in an org	org, state

---

projects

Description: GitHub Projects (requires PAT — not supported by GITHUB_TOKEN)

Tool	Purpose	Key Parameters
projects_get	Get details of a specific project	owner, project_number
projects_list	List GitHub Projects for a user or organization	owner, per_page
projects_write	Create or update project items/fields	owner, project_number

---

search

Description: Advanced search across GitHub

Tool	Purpose	Key Parameters
search_code	Search code across repositories	query, page, per_page
search_orgs	Search GitHub organizations	query, page, per_page
search_repositories	Search for repositories	query, page, per_page
search_users	Search GitHub users	query, page, per_page
semantic_issue_similarity_search	Find GitHub issues semantically similar to a given issue	owner, repo, issue_number
semantic_issues_search	Search issues using natural language queries	query, owner, repo

---

secret_protection

Description: Secret scanning

Tool	Purpose	Key Parameters
get_secret_scanning_alert	Get details of a specific secret scanning alert	owner, repo, alert_number
list_secret_scanning_alerts	List secret scanning alerts for a repository	owner, repo, state
run_secret_scanning	Scan file contents or diffs for exposed secrets	content

---

security_advisories

Description: Security advisories

Tool	Purpose	Key Parameters
check_dependency_vulnerabilities	Check dependencies against known vulnerabilities in the GitHub Advisory Database	owner, repo, dependencies
get_global_security_advisory	Get a specific global security advisory	ghsa_id
list_global_security_advisories	List advisories from the GitHub Advisory Database	type, severity, ecosystem
list_repository_security_advisories	List security advisories for a specific repository	owner, repo, state

---

stargazers

Description: Repository stars

Tool	Purpose	Key Parameters
list_starred_repositories	List repositories starred by a user	username, page, per_page
star_repository	Star a repository	owner, repo
unstar_repository	Unstar a repository	owner, repo

---

users

Description: User information

Note: No tools are currently registered in the users toolset. User search is available via the search toolset (search_users).

---

Best Practices

Toolset Selection

1. Start with defaults (context, repos, issues, pull_requests) for most workflows
2. Add toolsets incrementally based on actual needs rather than enabling all
3. Security toolsets (code_security, dependabot, secret_protection, security_advisories) require security-events permission
4. Write operations require appropriate GitHub token permissions (see write_permissions in the JSON mapping)
5. Projects toolset requires a PAT (Personal Access Token) — GITHUB_TOKEN lacks the required project scope

Permission Requirements

Most toolsets work with the default GITHUB_TOKEN in GitHub Actions. Exceptions:

• projects — Requires a PAT with project scope
• security_advisories (write) — Requires security-events: write permission
• actions (write for actions_run_trigger) — Requires actions: write permission