Skip to content

tool-permissions.md

Latest commit

 

History

History
312 lines (239 loc) · 12.5 KB

tool-permissions.md

File metadata and controls

312 lines (239 loc) · 12.5 KB

Tool Authentication Requirements

This document provides a comprehensive reference for the authentication requirements of each tool in the GitHub MCP Server. It covers both OAuth scopes (for classic personal access tokens and OAuth apps) and fine-grained permissions (for fine-grained personal access tokens).

Quick Reference

  • OAuth Scopes: Used by OAuth apps and classic Personal Access Tokens (PATs)
  • Fine-Grained Permissions: Used by fine-grained Personal Access Tokens

For OAuth scopes documentation, see: Scopes for OAuth Apps

For fine-grained permission documentation, see: Permissions for Fine-Grained PATs

Scope and Permission Hierarchy

OAuth Scope Hierarchy

Some OAuth scopes include access to other scopes. If you have a parent scope, you automatically have access to all child scopes:

Parent Scope Includes
repo repo:status, repo_deployment, public_repo, repo:invite, security_events
user read:user, user:email, user:follow
admin:org write:org, read:org
write:org read:org
admin:repo_hook write:repo_hook, read:repo_hook
write:repo_hook read:repo_hook
admin:public_key write:public_key, read:public_key
write:public_key read:public_key
admin:gpg_key write:gpg_key, read:gpg_key
write:gpg_key read:gpg_key
project read:project
write:packages read:packages

Fine-Grained Permission Levels

Fine-grained permissions have three access levels:

Level Description
read Read-only access to the resource
write Read and write access to the resource
admin Full administrative access to the resource

Write access typically includes read access, and admin access typically includes both read and write access.

Tools by Category

Repository Tools

Tool OAuth Scope Fine-Grained Permission
get_file_contents repo contents:read
create_or_update_file repo contents:write
delete_file repo contents:write
push_files repo contents:write
create_repository repo administration:write
fork_repository repo contents:read, administration:write
create_branch repo contents:write
list_branches repo contents:read
list_commits repo contents:read
get_commit repo contents:read
list_tags repo contents:read
get_tag repo contents:read
list_releases repo contents:read
get_latest_release repo contents:read
get_release_by_tag repo contents:read
star_repository public_repo starring:write
unstar_repository public_repo starring:write
list_starred_repositories (none) starring:read
get_repository_tree repo contents:read

Issue Tools

Tool OAuth Scope Fine-Grained Permission
list_issues repo issues:read
get_issue repo issues:read
create_issue repo issues:write
update_issue repo issues:write
add_issue_comment repo issues:write
list_issue_comments repo issues:read
search_issues repo issues:read
list_issue_types read:org issues:read
assign_copilot_to_issue repo issues:write

Pull Request Tools

Tool OAuth Scope Fine-Grained Permission
list_pull_requests repo pull_requests:read
get_pull_request repo pull_requests:read
create_pull_request repo pull_requests:write
update_pull_request repo pull_requests:write
merge_pull_request repo contents:write, pull_requests:write
list_pull_request_commits repo pull_requests:read
get_pull_request_diff repo pull_requests:read
get_pull_request_files repo pull_requests:read
update_pull_request_branch repo contents:write, pull_requests:write
list_pull_request_reviews repo pull_requests:read
create_pull_request_review repo pull_requests:write
add_pull_request_review_comment repo pull_requests:write
request_copilot_review repo pull_requests:write
get_pull_request_review repo pull_requests:read
get_pull_request_comments repo pull_requests:read
create_pending_pull_request_review repo pull_requests:write
submit_pending_pull_request_review repo pull_requests:write
delete_pending_pull_request_review repo pull_requests:write

Git Tools

Tool OAuth Scope Fine-Grained Permission
create_git_tag repo contents:write
create_tree repo contents:write

Actions Tools

Tool OAuth Scope Fine-Grained Permission
list_workflows repo actions:read
list_workflow_runs repo actions:read
get_workflow_run repo actions:read
get_workflow_run_logs repo actions:read
run_workflow repo actions:write
cancel_workflow_run repo actions:write
rerun_workflow repo actions:write
rerun_failed_jobs repo actions:write
list_workflow_jobs repo actions:read
get_job_logs repo actions:read
list_workflow_run_artifacts repo actions:read
download_workflow_run_artifact repo actions:read
get_workflow_run_usage repo actions:read

Label Tools

Tool OAuth Scope Fine-Grained Permission
list_labels repo issues:read or pull_requests:read
get_label repo issues:read or pull_requests:read
label_write repo issues:write or pull_requests:write

Notification Tools

Tool OAuth Scope Fine-Grained Permission
list_notifications notifications N/A - Requires classic token
get_notification_details notifications N/A - Requires classic token
dismiss_notification notifications N/A - Requires classic token
mark_all_notifications_read notifications N/A - Requires classic token
manage_notification_subscription notifications N/A - Requires classic token
manage_repository_notification_subscription notifications N/A - Requires classic token

Note: Notification endpoints are not available with fine-grained PATs. Use a classic PAT with the notifications scope.

Discussion Tools

Tool OAuth Scope Fine-Grained Permission
list_discussions repo discussions:read
get_discussion repo discussions:read
list_discussion_categories repo discussions:read
get_discussion_comments repo discussions:read

Project Tools

Tool OAuth Scope Fine-Grained Permission
list_projects read:project organization_projects:read
get_project read:project organization_projects:read
list_project_items read:project organization_projects:read
get_project_item read:project organization_projects:read
list_project_fields read:project organization_projects:read
update_project_item project organization_projects:write
create_project_draft project organization_projects:write
add_project_item project organization_projects:write
delete_project_item project organization_projects:write

Gist Tools

Tool OAuth Scope Fine-Grained Permission
list_gists (none) gists:read
get_gist (none) gists:read
create_gist gist gists:write
update_gist gist gists:write

Search Tools

Tool OAuth Scope Fine-Grained Permission
search_code repo contents:read
search_issues repo issues:read
search_users repo metadata:read
search_repositories repo metadata:read

Security Tools

Code Scanning

Tool OAuth Scope Fine-Grained Permission
list_code_scanning_alerts security_events code_scanning_alerts:read
get_code_scanning_alert security_events code_scanning_alerts:read
update_code_scanning_alert security_events code_scanning_alerts:write

Secret Scanning

Tool OAuth Scope Fine-Grained Permission
list_secret_scanning_alerts security_events secret_scanning_alerts:read
get_secret_scanning_alert security_events secret_scanning_alerts:read

Dependabot

Tool OAuth Scope Fine-Grained Permission
list_dependabot_alerts repo dependabot_alerts:read
get_dependabot_alert repo dependabot_alerts:read
update_dependabot_alert repo dependabot_alerts:write

Security Advisories

Tool OAuth Scope Fine-Grained Permission
list_repository_security_advisories repo repository_security_advisories:read
get_global_security_advisory (none) (none - public data)
list_global_security_advisories (none) (none - public data)

Context Tools

Tool OAuth Scope Fine-Grained Permission
get_me (none) metadata:read
list_teams read:org members:read
get_team_members read:org members:read

Dynamic Tools (Meta-tools)

These tools are internal to the MCP server and don't call GitHub APIs:

Tool OAuth Scope Fine-Grained Permission
enable_toolset (none) (none)
list_available_toolsets (none) (none)
get_toolset_tools (none) (none)

Minimum Required Scopes by Use Case

Read-Only Access

If you only need to read data (no modifications):

OAuth Scopes:

  • repo - For private repositories
  • public_repo - For public repositories only
  • read:org - For organization and team information
  • read:project - For project boards

Fine-Grained Permissions:

  • contents:read
  • issues:read
  • pull_requests:read
  • actions:read
  • metadata:read

Full Development Workflow

For a typical development workflow (read, write, manage PRs and issues):

OAuth Scopes:

  • repo - Covers most repository operations
  • notifications - If using notification tools
  • project - If using project boards

Fine-Grained Permissions:

  • contents:write
  • issues:write
  • pull_requests:write
  • actions:write
  • metadata:read

Security Scanning

For security-related tools:

OAuth Scopes:

  • security_events - For code scanning and secret scanning
  • repo - For Dependabot alerts (included in repo)

Fine-Grained Permissions:

  • code_scanning_alerts:read or write
  • secret_scanning_alerts:read
  • dependabot_alerts:read or write

Notes

  1. Metadata Permission: The metadata:read permission is automatically granted for all repositories that a fine-grained PAT has access to.

  2. Private vs Public Repositories: The repo scope covers both public and private repositories. Use public_repo if you only need access to public repositories with OAuth apps.

  3. Organization Permissions: Some tools require organization-level permissions (read:org, write:org, or admin:org), which are separate from repository permissions.

  4. Notification Limitations: Notification endpoints are not available with fine-grained PATs. You must use a classic PAT with the notifications scope for notification tools.

  5. Copilot Tools: The assign_copilot_to_issue and request_copilot_review tools require repo scope and work with repositories where Copilot is enabled.