gh_mcp
This MCP server integrates the GitHub CLI to provide read and write access to GitHub repositories, issues, pull requests, releases, workflows, and more.
Read Operations:
Search repositories, issues/PRs, and code with various qualifiers.
List and get detailed information for repositories, issues, PRs, releases, workflows, runs, labels, milestones.
Get file contents and view PR diffs, changed files, and commits.
Watch workflow runs until completion.
Provide server and GH CLI info (version, auth status).
Write Operations (disabled by default, require opt-in):
Create and edit repositories, issues, pull requests, releases, labels, milestones.
Upsert (create or overwrite) labels.
Submit formal PR reviews (approve, request changes, comment) and merge PRs with exact head SHA validation.
Post comments on issues/PRs; create branches linked to issues.
Atomically commit files to a branch with expected head SHA.
Trigger workflow dispatch events.
Safety:
Writes are disabled by default; enabled via
MCP_GH_ALLOW_WRITE_COMMANDS.High-risk operations require separate opt-in flags.
Writes can be scoped to specific repos/owners via allowlists.
All commands are non-interactive, async, with configurable timeouts.
Results are bounded and paginated with hard limits.
Allows managing GitHub repositories, issues, pull requests, releases, labels, milestones, and more through the gh command-line interface.
Provides tools for listing, viewing, and triggering GitHub Actions workflows and monitoring workflow runs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gh_mcp show me open pull requests in the repo vercel/next.js"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP 2.0 GitHub CLI Server
A Python MCP server for the gh CLI. It uses the official MCP Python SDK 2.x,
runs gh asynchronously without a terminal, and returns structured results from
direct JSON output or a post-write readback.
Version 0.9.0 exposes 64 public MCP tools: 43 read-only and 21 write.
The 0.9.0 release splits the former generic gh_submit_pr_review into three
action-specific formal pull-request review writes — gh_approve_pr,
gh_request_pr_changes, and gh_comment_pr_review — and adds the read-only
gh_get_pr_review_eligibility preflight. Each review write submits exactly one review
through the server-configured reviewer principal, verifies the exact head and
authenticated reviewer identity immediately before the review POST, and readbacks
immutable review-ID state. Issue #80 additionally adds gh_patch_files, a focused
exact-context text-patch write that materializes all edits against immutable original
blob snapshots before creating Git objects and then reuses the canonical content-commit
CAS/readback state machine. Issue #82 adds the read-only gh_list_repository_tree structural
discovery primitive, pinned to one exact commit SHA with bounded completeness evidence and
safe root/nested directory traversal. Issue #83 adds gh_get_pr_review_thread, an exact-head
bounded detail read for one opaque review-thread node ID, including ownership proof, ordered
comment provenance, independent comment/body truncation evidence, and complete-body digests.
The 0.8.0 release retired the weaker generic workflow-dispatch,
release-creation, and label-upsert writes, removed obsolete write-compatibility
infrastructure, and registered every public write exactly once through the canonical
host-facing schema facade. Historical 0.7.0/0.7.1, 0.8.0, and 0.8.1 release records
remain available under docs/ but do not define the current runtime inventory.
Tools
Read-only (43)
gh_server_info: report the deployed MCP server and tool-schema version without contacting GitHub or starting a subprocess.gh_info: gh CLI version, authentication status, and active account.gh_get_api_rate_status: report GitHub-provided primary rate-limit observations separately from locally governed blocking/pacing state, with bounded anti-polling reuse.gh_search_repos: search GitHub repositories with qualifiers.gh_search_issues: search issues and pull requests with qualifiers.gh_search_code: search source code with qualifiers.gh_list_issues: list issues in a repository with filters.gh_get_issue: get details of a specific issue or pull request, including its body.gh_list_prs: list pull requests in a repository.gh_get_pr: get a bounded, fully typed pull-request snapshot and exact base/head commit SHAs through one explicit noninteractive GET.gh_get_pr_diff: read a bounded diff or patch pinned to the PR's exact base and head SHAs, with truncation metadata and a SHA-256 fingerprint.gh_list_pr_files: list one bounded page of changed files and patch fragments.gh_list_pr_commits: list one bounded page of commits in a pull request.gh_list_pr_reviews: list one bounded page of formal reviews for an exact PR head, preserving pagination and exact-head evidence.gh_get_pr_review_state: aggregate exact-head review/request/thread evidence without treating truncated evidence as complete.gh_get_pr_review_thread: resolve one exact opaque thread ID from that aggregate workflow, prove repository/PR ownership at the expected PR head, and return bounded ordered comments with provenance plus independent connection/body completeness metadata and complete-body SHA-256 digests.gh_get_pr_review_eligibility: read-only exact-head preflight reporting the PR author, ordinary GitHub identity, configured reviewer identity, and whether an independent APPROVED review or ordinary COMMENTED review is currently eligible.gh_get_merge_requirements: aggregate effective merge requirements/readiness for an exact expected PR head and fail closed when policy or identity evidence is incomplete.gh_get_repo: get details of a specific repository.gh_list_repos: list repositories for a user or organization.gh_list_releases: list releases in a repository.gh_get_release: get details of a specific release.gh_list_workflows: list GitHub Actions workflows in a repository.gh_get_workflow: get details of a specific workflow.gh_list_runs: list recent GitHub Actions workflow runs.gh_get_run: get details of a specific workflow run.gh_list_run_artifacts: list one bounded page of artifact metadata for an exact workflow run, with optional exact-name filtering and run attempt/head identity.gh_get_artifact: get one exact artifact's metadata, including digest, expiry, associated workflow run, and workflow head SHA.gh_list_artifact_files: inspect one exact unexpired artifact ZIP and list a bounded page of normalized regular-file metadata without extracting the archive.gh_read_artifact_file: read one exact normalized artifact path as bounded UTF-8 text/JSON evidence with complete-file digest and truncation metadata.gh_watch_run: poll a workflow run until completion or a caller-supplied timeout.gh_get_pr_checks: return bounded CI check summaries pinned to an exact PR revision.gh_list_run_jobs: list one bounded page of jobs and steps for an exact run attempt.gh_get_failed_run_logs: return bounded failed-step logs for an exact run attempt.gh_get_job_logs: return bounded full log evidence for one exact job and explicit run attempt, with literal tail/marker selectors and complete-source SHA-256.gh_get_run_logs: return bounded full log evidence for one exact run attempt, with literal tail/marker selectors and complete-source SHA-256.gh_list_labels: list labels in a repository.gh_list_milestones: list milestones in a repository.gh_get_file_contents: read a complete file at an exact branch, tag, or commit ref.gh_list_repository_tree: list immediate or recursive structural entries for a repository root or nested directory at one exact commit SHA, with exact tree/object identity and explicit truncation/completeness metadata but no file content.gh_get_ref: resolve one exact branch or tag Git ref, preserving direct object identity and returning the peeled commit SHA for annotated tags.gh_get_commit: read one exact 40-character Git commit SHA with its immutable tree, ordered parents, author/committer, message, and GitHub verification evidence.gh_compare_commits: compare two exact commit SHAs with explicit merge-base, ahead/behind status, independently bounded commit/file evidence, and digests.
Write (21)
gh_create_issue: create a new issue (write, disabled by default).gh_create_pr: create a new pull request (write, disabled by default).gh_create_repo: create a new repository only for an exact configured prospectiveOWNER/REPOtarget (write, disabled by default).gh_create_release_exact: create a release against one exact target commit with fail-closed absence preconditions and authoritative readback (write, disabled by default).gh_run_workflow_exact: dispatch one exact numeric workflow ID or canonical workflow path only when the requested ref resolves to the expected exact SHA, with post-dispatch evidence bound to the resolved numeric workflow/run identities (write, disabled by default).gh_edit_issue: edit an existing issue (write, disabled by default).gh_set_issue_state: change issue state only from the caller-declared expected state and verify the resulting state by readback (write, disabled by default).gh_create_label: create a new label (write, disabled by default).gh_edit_label: edit an existing label (write, disabled by default).gh_create_milestone: create a new milestone (write, disabled by default).gh_create_comment: create a comment on an issue or PR (write, disabled by default).gh_create_branch: create an issue development branch from a branch-name base (additive write, disabled by default).gh_create_branch_from_sha: create a branch at one exact 40-character commit SHA without moving an existing ref (additive write, disabled by default).gh_edit_pr: edit an existing pull request (write, disabled by default).gh_set_pr_draft_state: change PR draft state only for the expected exact head and expected current draft state, with authoritative readback (write, disabled by default).gh_approve_pr: submit exactly one formal APPROVED review for an exact PR head through the server-configured independent reviewer principal, verifying exact head and authenticated reviewer login before the POST (additive write, disabled by default).gh_request_pr_changes: submit exactly one formal CHANGES_REQUESTED review for an exact PR head through the configured reviewer principal with an exact expected reviewer login compare-only precondition (additive write, disabled by default).gh_comment_pr_review: submit exactly one formal COMMENTED review through the ordinary authenticated principal for an exact PR head as the explicit same-author fallback; COMMENTED is never reported as APPROVED (additive write, disabled by default).gh_merge_pr: merge an exact reviewed PR head with an explicit strategy (destructive write, separately disabled by default).gh_commit_files: atomically create or replace files in one branch commit (destructive write, separately disabled by default).gh_patch_files: apply bounded exact-context UTF-8 text edits to existing files in one branch commit, preserving supported file modes and reusing the content-commit exact-CAS and authoritative readback contract (destructive write, separately disabled by default).
Historical 0.7.1 additionally exposed the weaker generic gh_run_workflow,
gh_create_release, and gh_upsert_label writes. They are retired in 0.8.0 rather
than preserved as aliases. gh_run_workflow_exact and gh_create_release_exact are
the sole public primitives for their mutation classes, while label callers choose
explicit gh_create_label or gh_edit_label semantics. Do not restore retired tools
or reinterpret historical 0.7.x inventory records as current runtime authority.
Related MCP server: GitHub CLI MCP Server
0.9.0 architecture and evidence contract
src/mcp_gh_server/server.py is the composition root; public read implementations live
in cohesive domain modules under src/mcp_gh_server/tools/, while the 21 public writes
are registered exactly once from src/mcp_gh_server/current_write_tool_schema.py. That
facade keeps the non-review writes and delegates the three formal review writes to
src/mcp_gh_server/pr_review_tool_schema.py. gh_commit_files and gh_patch_files
share src/mcp_gh_server/content_commit_service.py as the sole materialized-content
object/CAS/readback state machine. GitHub request execution is centralized through the
shared GitHubRequestGovernor rather than duplicated in individual tools.
Writes remain default-off. Exact-state tools preserve expected state/SHA preconditions
where applicable, perform one mutation attempt, and require authoritative readback
before reporting verified success. Ambiguous or partial writes are not blindly retried.
Canonical metadata-aware write paths rely on structured GitHubRequestError ambiguity
metadata produced by GhClient; bare RuntimeError message text is not upgraded into
an invented transport classification.
Evidence reads remain explicitly bounded. Callers must preserve truncation/completeness metadata, byte counts, digests, and warnings rather than presenting partial artifact, log, or comparison evidence as complete.
The conservative read surface includes exact-state evidence such as
gh_get_merge_requirements, gh_compare_commits, artifact-content inspection, and
gh_get_api_rate_status. These tools fail closed or report incomplete evidence when
identity, policy, or bounded-source completeness cannot be established. See the
focused documents under docs/ for each contract.
0.9.0 intentionally does not expose arbitrary public gh <args...>, arbitrary public
gh api, a generic shell/subprocess MCP tool, administrator bypasses, automatic
mutation replay, artifact/log deletion, or branch-protection/ruleset mutation. See
docs/release_gate_0_9_0.md for the current release acceptance mapping.
Install
cp .env.example .env
$EDITOR .env
uv sync --devGITHUB_TOKEN is required and can be supplied either in the process
environment or the located .env file. To use an env file outside the
launch directory, set:
export MCP_GH_ENV_FILE=/absolute/path/to/.envStart the MCP Inspector:
uv run mcp dev src/mcp_gh_server/server.pyRun as a local stdio MCP server:
uv run mcp-ghThe default transport is stdio. For local Streamable HTTP:
MCP_GH_TRANSPORT=streamable-http uv run mcp-gh
# endpoint: http://127.0.0.1:8766/mcpAlternative ASGI launch:
uv run uvicorn mcp_gh_server.asgi:app --host 127.0.0.1 --port 8766Client configuration
VS Code / compatible local stdio host
Use an absolute project path. The host should launch the locked project
environment. Run uv sync --dev first so the project has a generated
uv.lock before using --frozen:
{
"servers": {
"gh-local": {
"type": "stdio",
"command": "/absolute/path/to/uv",
"args": [
"run",
"--directory",
"/absolute/path/to/gh_mcp",
"--frozen",
"mcp-gh"
],
"env": {
"MCP_GH_ENV_FILE": "/absolute/path/to/gh_mcp/.env"
}
}
}
}For Qwen Code or another host using the common mcpServers shape, keep
the same command/args and place the entry under mcpServers.
ChatGPT plan and gateway limitations
The action surface is version 0.9.0, but availability in ChatGPT depends on the
account plan and integration surface:
OpenAI currently limits full custom MCP apps, including write/modify actions, to Business and Enterprise/Edu workspaces.
A ChatGPT Plus user may be able to install or discover a custom plugin, but the plugin's MCP gateway is a separate, more limited integration. This project does not assume that gateway supports arbitrary custom MCP tools or write actions.
Seeing
gh_get_file_contents,gh_commit_files, orgh_patch_filesin a discovery response proves only that the server advertised the tools. It does not prove that the Plus plugin gateway will route the invocation to the server.
The Business/Enterprise Action control, action-refresh, and workspace-publish
instructions do not apply to a Plus account. If the Plus gateway reports that the
plugin or gh_CLI namespace has been disabled, there may be no user-accessible
action setting that can re-enable the tool in that conversation.
Tentative Plus schema-refresh procedure
Limited testing indicates that the Plus custom-plugin gateway may retain a cached tool schema after the backend changes. Deleting and reinstalling the custom plugin appears to force rediscovery of the revised tools and may be necessary when tool names, parameters, annotations, or result schemas change:
Increment the project, package, and MCP server version whenever a deployed revision changes tool names, schemas, annotations, or routing behavior.
Deploy the revised backend and restart the MCP server.
Delete the existing custom plugin from ChatGPT Plus.
Reinstall the plugin so the gateway scans the backend's current tool definitions.
In a new conversation, call
gh_server_infoand confirm bothserver_versionandtool_schema_versionmatch the expected deployment.Only then test the revised GitHub tools.
This procedure is based on observed behavior rather than a documented compatibility guarantee. A backend restart alone may leave the Plus gateway using stale tool definitions, while deletion and reinstallation may still fail if the gateway does not support a particular tool or capability.
gh_server_info is intentionally the smallest and safest possible verification
call. It takes no model-controlled arguments, performs no external I/O, starts no
subprocess, triggers no elicitation or approval flow, and returns only bounded local
metadata. gh_info is not a substitute: it reports the installed GitHub CLI version,
not the deployed MCP server version.
See OpenAI's current MCP app availability and plugin availability.
At INFO, repository-content tools log content-free reachability markers using their
own tool names, including gh_get_file_contents, gh_list_repository_tree,
gh_commit_files, and gh_patch_files.
The focused PR snapshot/review reads emit the same marker using their own tool name.
The version probe emits the equivalent marker with tool=gh_server_info.
gh_get_pr Plus gateway contract
Version 0.5.1 replaces the former gh_get_pr contract that could be discovered
but was not safe for a strict execution gateway. The old definition had no explicit
tool title, did not declare idempotence, accepted unconstrained repository identifiers,
and advertised ambiguous structured-output fragments: label items had an empty JSON
schema and comments had no JSON type. A host can catalog such a tool while rejecting
it later when it constructs or validates the executable route.
The revised operation preserves the mixed read/write server and changes only the offending read contract and common read annotation accuracy:
the title and description explicitly identify a read-only, noninteractive snapshot;
readOnlyHint=true,destructiveHint=false, andidempotentHint=trueare explicit;owner, repository, and positive PR-number constraints are present in the input schema;
every output field is typed, including
labels: string[], nonnegative integercomments, and required 40-character base/head SHAs;the implementation performs exactly one
gh api ... -X GETrequest and exposes no approval, elicitation, comment, review, merge, or generic-command path;the reachability marker is logged before repository validation or client execution:
MCP tool invocation reached server: tool=gh_get_prAfter deploying the current release, delete and reinstall the Plus custom plugin and
verify gh_server_info reports both versions as 0.9.0. An immediate namespace-disabled
response with no gh_get_pr marker still proves rejection occurred in the host before
the revised server operation. It does not indicate GitHub authentication, repository,
PR, or readback failure and must not be retried as though a GitHub write partially ran.
If ChatGPT reports that the app or namespace is disabled and this marker is absent,
the call was rejected by ChatGPT's plugin gateway before reaching the MCP server.
Restarting gh, changing the GitHub token, or changing this server's command
implementation cannot repair that host-side state. On Plus, full validation should
therefore use a standard MCP client such as the local stdio or Streamable HTTP
configurations above; passing those checks does not establish compatibility with
ChatGPT's limited custom-plugin gateway.
Read-only pull-request review without checkout
The server deliberately does not expose a generic command executor or a standalone checkout operation. A checkout performed by this backend would exist on the MCP server's filesystem, not in ChatGPT's local environment, and a path alone would not provide a safe review workspace. The focused review tools instead operate through noninteractive GitHub reads and return bounded structured results:
Call
gh_get_prand record its exactbase_shaandhead_sha.Call
gh_get_pr_difffor a unifieddiffor email-stylepatch. The server resolves the PR's object IDs and reads the comparison by those immutable SHAs.Check
truncated,bytes_returned,total_bytes, andsha256. A truncated result is not a complete diff and must not be described as one.Page through
gh_list_pr_filesandgh_list_pr_commitsas needed. The server rechecks the SHA pair after each numbered-PR page and rejects the result if the snapshot changed during the read. GitHub may omit or truncate an individual file'spatch, and the server also bounds patch fragments and commit messages. Usegh_list_repository_treewhen structural path discovery is needed, then usegh_get_file_contentsat the same returned SHA for complete file inspection.If the PR changes during review, restart from the new exact SHA pair rather than combining observations from different snapshots.
gh_get_pr_diff returns at most MCP_GH_MAX_PR_DIFF_BYTES UTF-8 bytes. A caller may
request a smaller limit, but cannot raise the deployment cap above 1,000,000 bytes:
MCP_GH_MAX_PR_DIFF_BYTES=500000
MCP_GH_MAX_PR_FILE_PATCH_BYTES=8000
MCP_GH_MAX_PR_COMMIT_MESSAGE_BYTES=4000This workflow is valid for source-level, read-only review. It does not check out a worktree, inspect generated or untracked files, install dependencies, build code, or run tests. A validation record should state that boundary explicitly, for example:
Reviewed the pull request using GitHub metadata, diff data, and repository file contents pinned to the recorded base and head SHAs. No local checkout, build, or test execution was performed.
If acceptance requires execution, use a separate isolated repository runner with a managed workspace, bounded commands, cancellation, cleanup, and exact-head-SHA validation. The read-only MCP tools are not a substitute for that environment.
Formal pull-request review and merge
gh_create_comment creates an issue-style conversation comment; it does not submit
a GitHub pull-request review and cannot produce the formal APPROVED,
CHANGES_REQUESTED, or COMMENTED review states. Use the action-specific review
writes — gh_approve_pr, gh_request_pr_changes, or gh_comment_pr_review — when
a formal disposition is required.
The safe completion sequence is:
Read and review the PR using
gh_get_pr,gh_get_pr_diff, file pages, commit pages, and exact-ref file reads. Record the returnedhead_sha.Optionally run the read-only
gh_get_pr_review_eligibilitypreflight with that SHA to see which formal review states are currently eligible.Call the action-specific write for that SHA:
gh_approve_pr(optional body) orgh_request_pr_changes(mandatory body) through the server-configured reviewer principal withexpected_reviewer_login, orgh_comment_pr_review(mandatory body) through the ordinary principal.Confirm the structured result's
state,commit_sha, andreview_id. The tool submits the review with GitHub'scommit_idfield and rejects a stale head before writing.If merge is separately authorized, call
gh_merge_prwith the same exact head SHA and an explicitmerge,squash, orrebasestrategy.Treat the PR as merged only when the result reports
merged: true. A successful command may instead report a merge queue or unmet requirements; formal review submission by itself never merges or closes the PR.
Both operations are focused tools with bounded text fields. They start no nested MCP elicitation, inherit no stdin, and return structured readback. Review request bodies are transferred through a temporary JSON input file; merge bodies are supplied on controlled stdin. If a write succeeds but readback fails, the response is marked as partial success and instructs the caller not to retry automatically.
Before an approve or request_changes write, the server compares the
server-configured reviewer login against the PR author. GitHub documents that PR
authors cannot approve their own pull requests, so an exact match is rejected before
the POST with an explicit no review was attempted error. gh_comment_pr_review
remains available to the author. GitHub's public review documentation does not
explicitly state the equivalent author rule for request_changes, so the server
does not invent one: GitHub remains authoritative.
When GitHub rejects any review write, including HTTP 422 validation failures, the
client now preserves a bounded, sanitized JSON error summary containing GitHub's
message, errors, documentation_url, and status. Request values and arbitrary
response fields are excluded. A failed POST remains a direct tool error—there is no
readback and no partial-success result because GitHub did not create a review. Do not
retry it automatically; correct the reported validation or use comment when the
authenticated account is the PR author.
gh_merge_pr deliberately exposes no administrator bypass, branch deletion, or
automatic-merge switch. It passes GitHub CLI's --match-head-commit guard so a
force-push or new commit cannot silently change the authorized merge target. GitHub
permissions and branch protection still apply, and an author generally cannot
approve their own pull request.
Read-only CI diagnosis
Use the focused CI tools instead of inferring a failure from run metadata:
Call
gh_get_prand record the exact PRhead_sha.Call
gh_get_pr_checks. Its result includes the same base/head SHA pair and categorizedpass,fail,pending,skipping, orcancelchecks. Failed and pending checks are returned as data even thoughgh pr checksuses nonzero status codes for those states.Use the check link or
gh_list_runsto identify the positive integer run ID.Call
gh_list_run_jobs, optionally with an exact attempt number, to retrieve one page of jobs and their step status/conclusion metadata.For failed-step-only evidence, call
gh_get_failed_run_logsfor the same attempt. For successful or complete job/run evidence, callgh_get_job_logsorgh_get_run_logswith an explicit attempt and inspect the returned exact identity.Before claiming log evidence is complete, inspect
truncated,bytes_returned,total_bytes,warning, andsha256. Tail and marker selectors intentionally produce incomplete evidence relative to the complete retrieved source log.
All five diagnostic tools are explicitly read-only, idempotent, and open-world. They
expose no watch, rerun, cancel, delete, dispatch, browser, generic-command, approval,
or elicitation option. Repository identifiers, PR/run/job IDs, attempts, pages, and
output sizes are schema constrained. Every gh subprocess remains asynchronous and
noninteractive with detached stdin.
gh_get_pr_checks reads and verifies the PR SHA pair around the checks request so a
force-push cannot silently mix revisions. Jobs and logs first resolve a concrete run
attempt and head SHA, operate on that exact attempt, and verify immutable identity
again before returning. Job pages contain at most 100 jobs. Failed logs are bounded
by both the request and their deployment setting; general job/run logs use a separate
bounded-evidence cap:
MCP_GH_MAX_FAILED_RUN_LOG_BYTES=500000
MCP_GH_MAX_ACTION_LOG_BYTES=500000Both deployment settings are capped at 1,000,000 UTF-8 bytes. Empty log output is
valid. Authentication, retention expiry, missing logs, or malformed output are
returned as ordinary tool errors; the namespace remains available for subsequent
reads. gh_get_job_logs and gh_get_run_logs use only literal tail/marker selectors;
no regex or generic shell filtering is exposed. See docs/gh_action_logs.md for the
complete selection, byte-accounting, and digest contract.
Write-command policy
Write execution is off by default:
MCP_GH_ALLOW_WRITE_COMMANDS=falseTo enable writes:
MCP_GH_ALLOW_WRITE_COMMANDS=trueWrite tools do not initiate nested MCP elicitation. A compatible MCP host is
responsible for presenting any user-facing action approval. The ChatGPT Plus
custom-plugin gateway may reject write tools instead of offering approval. The
server independently enforces the write-enable flag, optional repository policy,
and high-risk operation switches before starting gh.
Limit enabled writes to explicit repositories or owners:
MCP_GH_ALLOWED_REPOSITORIES=fvanevski/project-a,fvanevski/project-b
MCP_GH_ALLOWED_OWNERS=fvanevskiWhen either allowlist is non-empty, a target is accepted if its exact
owner/repo or its owner is listed. Fine-grained GitHub token permissions
remain the primary GitHub-side authorization boundary.
Repository creation and workflow dispatch have an additional exact target policy. The corresponding allowlist must be non-empty when the fine gate is enabled; a target mismatch fails before the mutation request. Repository creation targets are prospective canonical repository identities and therefore do not require an owner-wide allowlist:
# Exact repositories that may be created. Prospective repositories may be listed in
# MCP_GH_ALLOWED_REPOSITORIES as exact owner/repo entries without granting owner-wide writes.
MCP_GH_ALLOWED_REPO_CREATION_TARGETS=fvanevski/new-project
# Exact workflow targets. WORKFLOW is either a positive numeric ID or an exact,
# case-sensitive canonical workflow path.
MCP_GH_ALLOWED_WORKFLOW_DISPATCH_TARGETS=fvanevski/project-a@12345678,fvanevski/project-b@.github/workflows/Release.ymlFor a workflow path, the public write schema accepts only canonical
.github/workflows/<file>.yml or .yaml values. The server first applies the local
repository/fine-gate/target policy to the caller-supplied selector. If the selector is
a path, it then performs a read-only workflow lookup, requires GitHub to return that
same path with exact case, and converts it to GitHub's positive numeric workflow ID.
Duplicate detection, exact-ref checks, dispatch, reservation state, and authoritative
run readback continue to use that numeric identity. A path mismatch or resolution
failure is fail-closed and never authorizes a different workflow.
Repository creation, release creation, workflow dispatch, repository-content commits, and PR merging require separate opt-in because they can have broader effects:
MCP_GH_ALLOW_REPO_CREATION=true
MCP_GH_ALLOW_RELEASE_CREATION=true
MCP_GH_ALLOW_WORKFLOW_DISPATCH=true
MCP_GH_ALLOW_CONTENT_COMMITS=true
MCP_GH_ALLOW_PR_MERGE=trueEnable only the operations the deployment actually needs; all five default to
false. The exact repository-creation and workflow-dispatch target lists also default
to empty, so those two operations remain denied even if their fine gate is accidentally
enabled without a target policy.
Exact-SHA branch creation
The two branch tools intentionally have different contracts:
gh_create_branchdelegates togh issue develop. Its optionalbaseis an existing branch name, because GitHub CLI resolves that field as a branch. The tool rejects a 40-character commit SHA before startingghand directs the caller to the exact-SHA primitive.gh_create_branch_from_shaaccepts no issue number or moving base name. It requires an exact 40-characterbase_sha, verifies that exact commit in the target repository, and creates onlyrefs/heads/<name>through GitHub's Git refs API.
Use gh_create_branch_from_sha whenever the base is an immutable reviewed commit.
The operation is additive: it never force-updates, moves, overwrites, or deletes an
existing ref. If GitHub rejects or interrupts the create response, the tool reads the
requested branch. A branch already at the requested SHA is returned as a safe
no-write result; a branch at any other SHA is an error and remains unchanged. An
unexpected successful response produces an explicit partial-success warning telling
the caller to read the branch and not retry automatically.
Both tools use the ordinary server write gate, repository/owner allowlists, and the
branch_create operation policy. Their schemas contain canonical repository bounds,
positive issue-number constraints where applicable, bounded branch names, and an
exact SHA pattern. They are classified as additive external writes and contain no
generic command input, nested MCP elicitation, interactive stdin, force option, ref
update, or issue-content mutation. Host approval remains the only interactive approval
layer.
Repository content writes
gh_commit_files accepts complete UTF-8 file contents, validates repository-relative
paths, and creates all supplied files in one Git tree and one commit. It conditionally
advances the named branch only if it still points to expected_head_sha; the update
uses GitHub's atomic updateRefs mutation with beforeOid and never forces a ref.
The operation does not support file deletion.
gh_patch_files is the narrow existing-file edit primitive. Every requested old_text
must occur exactly once in the target file's immutable original blob snapshot. All edits
for a file are resolved against that same original snapshot, so later edits cannot match
text introduced by earlier edits; overlapping source spans fail closed. The tool rejects
missing or non-unique context, stale or moved branch heads, symlinks and unsupported Git
modes, binary/NUL content, and non-UTF-8 targets before creating content Git objects.
It cannot create, delete, or rename files and preserves supported regular/executable modes.
After all patch files have been materialized, it rechecks the branch head and delegates the
one-commit/one-CAS mutation and bounded exact-ref reconciliation to the same canonical
content_commit_service.py path used by gh_commit_files.
Bound both content-write request families with:
MCP_GH_MAX_COMMIT_FILES=100
MCP_GH_MAX_FILE_BYTES=1000000
MCP_GH_MAX_COMMIT_BYTES=5000000If the final ref-update response is interrupted, the content-write service reads the branch
before reporting the outcome. An indeterminate result explicitly requires a fresh read and
must not be retried automatically. See docs/gh_patch_files.md for the focused patch-write
contract and regressions.
Operational limits
Search tools use GitHub's
gh searchsubcommands with--jsonoutput.Search tools obtain count evidence from one matching bounded Search REST read. Structurally valid
incomplete_results=trueevidence or a later count below already-returned items does not discard those items:total_countis reconciled to at least the returned-item count andtruncated=true. Malformed count evidence still fails closed. Seedocs/search-read-contract.md.gh_list_issues(labels=...)passes its comma-separated filter through the supported singulargh issue list --labeloption; it never emits the unsupported--labelsspelling.Results are bounded by
MCP_GH_DEFAULT_MAX_RESULTS(default: 30) and capped atMCP_GH_HARD_MAX_RESULTS(default: 100).All output is JSON-safe:
Decimal→ string,bytes→base64:prefix, datetimes → ISO 8601, infinities → string.Logs are sent to stderr so stdio protocol output is not corrupted.
Every
ghprocess is noninteractive, receives either closed or explicitly supplied stdin, and runs with prompting, pagers, Git credential prompts, spinners, color, and update notices disabled.User-authored bodies and notes are supplied through stdin rather than command arguments. Debug command logs redact titles and other free-form values.
Commands run asynchronously, are terminated with their process group on timeout or cancellation, and default to
MCP_GH_COMMAND_TIMEOUT_SECONDS=30.Write results distinguish write completion from structured readback. A partial-success warning explicitly instructs callers to verify before retrying.
Streamable HTTP binds to
127.0.0.1by default and uses MCP's localhost DNS-rebinding protection.MCP_GH_LOG_LEVEL(default:INFO) controls logging verbosity; set toDEBUGfor detailed command logs.
Validation
Pyrefly is the sole Python static type-check authority for CI/review and release decisions.
requirements-typecheck.txt pins the checker independently from the runtime/dev lock, and
[tool.pyrefly] in pyproject.toml defines project scope. Mypy may remain installed for
historical developer use but is not a validation substitute.
uv run pytest tests/test_release_gate_0_9_0.py
uv run ruff check .
uv run ruff format --check .
uv run --with-requirements requirements-typecheck.txt pyrefly check
uv run pytest
git diff --checkFor PR review, changed Python tests must also be passed explicitly to the changed-scope
pyrefly check <paths...> invocation even though the no-argument project scope excludes the
historical test corpus.
The 0.9.0 release passes only when package/server/tool-schema/lock versions, the exact 64/43/21 executable inventory, schema snapshots, canonical registration invariants, compatibility-path absence, focused negative/fail-closed regressions, static checks, and the full test suite agree on the same exact candidate SHA. Any source change invalidates affected validation and requires rerunning it.
Historical 0.7.0, 0.7.1, 0.8.0, and 0.8.1 release mappings remain under docs/; current
release authority is docs/release_gate_0_9_0.md and tests/test_release_gate_0_9_0.py.
Known boundaries
The server runs
ghas a subprocess, including allowlisted REST and GraphQL calls inside focused tools; it does not expose a generic command or API executor. Rate limits, authentication, and permission scoping are governed by theghCLI and the token inGITHUB_TOKEN.gh_patch_filesis deliberately text-only and existing-file-only; create/delete/rename, binary edits, symlink edits, and mode changes remain outside that public primitive.Commands like
gh release createthat require file uploads or complex multi-step flows are intentionally out of scope — they would need a dedicated maintenance tool.The
ghCLI must be installed and available on PATH.
Available Tools
61 toolsgh_approve_prApprove pull request at exact headA
Additive write: submit exactly one formal GitHub APPROVED review for the supplied exact pull-request head through the server-configured independent reviewer principal. Before the review POST the server verifies repository write policy, current head, expected reviewer login, authenticated reviewer login, and reviewer != PR author. The caller cannot select credentials. The write is attempted once and immutable review-ID readback verifies APPROVED state, actor, head, and body. It never comments as a fallback, merges, dismisses reviews, or retries an ambiguous mutation automatically.
Inputs: repo (required), owner (required), number (required), expected_head_sha (required), +2 more. Returns: Outcome of one action-specific GitHub APPROVED review attempt.
gh_comment_pr_reviewComment on pull request as formal review at exact headA
Additive write: submit exactly one formal GitHub COMMENTED review through the ordinary authenticated GitHub principal for the supplied exact PR head. This is the explicit same-author fallback for recording an external or Central disposition; COMMENTED is never reported as GitHub APPROVED. The write is attempted once and immutable review-ID readback verifies actor, state, head, and body. It cannot select reviewer credentials, approve, merge, or retry an ambiguous mutation automatically.
Inputs: body (required), repo (required), owner (required), number (required), +1 more. Returns: Outcome of one action-specific GitHub COMMENTED review attempt.
gh_commit_filesCommit repository files atomicallyADestructive
Destructive write: create or replace bounded UTF-8 file contents in one Git commit and conditionally advance exactly one existing branch only when its head matches expected_head_sha. Ordinary write authorization and the content-commit fine gate are required. The branch advance uses one exact compare-and-swap attempt followed by authoritative ref readback; it cannot delete files, force-update the ref, or blindly retry an ambiguous update.
Inputs: repo (required), files (required), owner (required), branch (required), +2 more. Returns: Result of one exact-head atomic repository content commit.
gh_compare_commitsCompare exact Git commitsARead-onlyIdempotent
Read-only: compare two exact 40-character commit SHAs without branch or tag resolution. Returns explicit merge-base/status evidence plus independently bounded commit and changed-file metadata with completeness and SHA-256 fingerprints.
Inputs: repo (required), owner (required), base_sha (required), head_sha (required), +2 more. Returns: Exact immutable comparison identity plus independently bounded evidence.
gh_create_branchCreate issue development branchA
Additive write: create exactly one branch linked to the specified issue after ordinary write authorization. The requested or default branch-name base is resolved to an exact commit and rechecked immediately before one mutation. Authoritative bounded readback verifies the exact issue association, branch ref, and target SHA. Full commit SHAs in base are rejected; use gh_create_branch_from_sha for a caller-supplied immutable base. The operation never moves or deletes refs and never blindly retries an ambiguous mutation.
Inputs: name (required), repo (required), owner (required), issue_number (required), +1 more. Returns: Result of creating and linking one issue development branch.
gh_create_branch_from_shaCreate branch from exact commitA
Additive write: create exactly one new branch at an exact 40-character commit SHA after ordinary write authorization. A branch already at the requested SHA is a safe no-write result; a conflicting existing branch is left unchanged. One mutation attempt is followed by authoritative exact-ref readback; the operation never force-updates, moves, overwrites, deletes, or blindly retries an ambiguous ref creation.
Inputs: name (required), repo (required), owner (required), base_sha (required). Returns: Result of creating one branch at an exact commit SHA.
gh_create_commentCreate issue or pull request commentA
Additive write: post exactly one bounded Markdown conversation comment on the specified issue or pull request after ordinary write authorization. The mutation is attempted once through the issue-comments REST endpoint, and authoritative readback of the returned immutable comment ID verifies repository and issue identity plus the requested body. It is not a formal pull-request review and cannot merge.
Inputs: body (required), repo (required), owner (required), issue_number (required). Returns: Authoritative result of creating an issue or pull-request comment.
gh_create_issueCreate issueA
Additive write: create exactly one issue in the target repository. The ordinary write gate and repository policy must allow the target. Optional labels and assignees are bounded; one mutation attempt is followed by authoritative semantic readback when stable identity is available. The tool never retries an ambiguous mutation automatically and does not edit, close, comment on, or delete an existing issue.
Inputs: repo (required), owner (required), title (required), body, +2 more. Returns: Authoritative outcome of one issue creation attempt.
gh_create_labelCreate labelA
Additive write: create exactly one new repository label after ordinary write authorization. Name, color, and description are explicitly bounded; one mutation attempt is followed by authoritative semantic readback. The operation never overwrites an existing label or retries an ambiguous create automatically, and it does not edit issues or delete labels.
Inputs: name (required), repo (required), color (required), owner (required), +1 more. Returns: Authoritative outcome of one label creation attempt.
gh_create_milestoneCreate milestoneA
Additive write: create exactly one repository milestone with bounded title, description, due date, and explicit open/closed state after ordinary write authorization. One mutation attempt is followed by authoritative readback of the stable milestone number and requested fields; ambiguous creation is never retried automatically. It does not assign issues to the milestone or edit existing milestones.
Inputs: repo (required), owner (required), title (required), state, +2 more. Returns: Authoritative outcome of one milestone creation attempt.
gh_create_prCreate pull requestA
Additive write: create exactly one pull request from the specified bounded head and base selectors after ordinary write authorization. Optional labels, assignees, and review requests are bounded and read back when created. It does not approve, merge, or change another pull request.
Inputs: base (required), body (required), head (required), repo (required), +6 more. Returns: Authoritative outcome of one pull-request creation attempt.
gh_create_release_exactCreate release at exact targetA
Additive write: create one GitHub release using an exact 40-character target commit SHA after ordinary write authorization and the separate release-creation fine gate. The tool verifies target identity, optionally requires the tag and every release state including drafts to be absent, performs exactly one governed creation request, and verifies release, tag commit, and explicit latest state. It never retries an ambiguous release mutation automatically.
Inputs: repo (required), owner (required), tag_name (required), make_latest (required), +7 more. Returns: Authoritative outcome of one exact-target guarded release creation.
gh_create_repoCreate repositoryA
Additive write: create exactly one repository at the canonical OWNER/REPO target after ordinary write policy, exact prospective-repository target policy, and the separate repository-creation fine gate allow it. The mutation is attempted once, then exact authoritative readback verifies repository identity, visibility, description, and initialization when GitHub exposes that evidence. It never retries an ambiguous creation and cannot delete, rename, transfer, or otherwise administer an existing repository.
Inputs: repo (required), owner (required), private, auto_init, +1 more. Returns: Authoritative outcome of one exact-target repository creation attempt.
gh_edit_issueEdit issue metadataADestructive
Destructive write: edit metadata on exactly one existing issue after ordinary write authorization. The request may change title, body, labels, assignees, or milestone; one mutation attempt is followed by authoritative semantic readback of the requested fields. Ambiguous mutations are never retried automatically. It does not close or reopen the issue, post comments, delete the issue, or bypass repository policy.
Inputs: repo (required), owner (required), number (required), body, +7 more. Returns: Authoritative outcome of one issue metadata edit attempt.
gh_edit_labelEdit labelADestructive
Destructive write: edit exactly one existing label's name, color, or description after ordinary write authorization. One mutation attempt is followed by authoritative semantic readback of the resulting label; an ambiguous edit is never retried automatically. It does not delete labels or mutate issue content.
Inputs: name (required), repo (required), owner (required), color, +2 more. Returns: Authoritative outcome of one label edit attempt.
gh_edit_prEdit pull request metadataADestructive
Destructive write: edit metadata on exactly one pull request after ordinary write authorization. The request may change title, body, labels, assignees, or base and uses authoritative readback for requested fields. Draft-state transition, formal review, merge, branch deletion, and direct head rewrite are separate or unavailable.
Inputs: repo (required), owner (required), number (required), base, +6 more. Returns: Authoritative outcome of one pull-request metadata edit attempt.
gh_get_api_rate_statusGet GitHub API rate statusARead-onlyIdempotent
Read-only diagnostic: perform or reuse a locally paced governed GET /rate_limit observation and return GitHub-provided primary rate-limit evidence separately from local request-governor blocking and write-pacing state. Repeated calls inside the configured diagnostic refresh interval are served from a local cache and do not create additional GitHub requests.
Inputs: no named parameters. Returns: GitHub API rate-limit evidence plus separate local governor policy state.
gh_get_artifactGet workflow artifact metadataARead-onlyIdempotent
Read-only: return metadata for one exact GitHub Actions artifact identifier, including digest, expiry, and workflow-run/head identity. The artifact archive is never downloaded and GitHub is never modified.
Inputs: repo (required), owner (required), artifact_id (required). Returns: Immutable identity and metadata for one GitHub Actions artifact record.
gh_get_commitGet exact Git commitARead-onlyIdempotent
Read-only: return immutable identity and commit-object evidence for one exact 40-character commit SHA. The result includes the tree SHA, every parent SHA, author, committer, message, and GitHub's verification/signature metadata without reinterpreting or upgrading that verification state.
Inputs: repo (required), owner (required), commit_sha (required). Returns: Exact immutable Git commit identity and verification evidence.
gh_get_failed_run_logsRead failed workflow logsARead-onlyIdempotent
Read-only: return bounded failed-step log text for one exact GitHub Actions run attempt, with truncation metadata and a SHA-256 fingerprint. This never reruns, cancels, deletes, or dispatches a workflow and never requests input.
Inputs: repo (required), owner (required), run_id (required), attempt, +1 more. Returns: Bounded failed-step logs for one exact workflow-run attempt.
gh_get_file_contentsRead repository fileARead-onlyIdempotent
Read-only: fetch the complete contents and blob metadata for one repository file at a branch, tag, or commit ref. This tool never modifies GitHub.
Inputs: ref (required), path (required), repo (required), owner (required). Returns: Complete contents and metadata for one repository file.
gh_get_issueBRead-onlyIdempotent
Get details of a specific issue or pull request, including its body.
Inputs: repo (required), owner (required), number (required). Returns: An issue or pull request.
gh_get_job_logsGet exact workflow job logsARead-onlyIdempotent
Read-only: stream bounded plaintext log evidence for one exact GitHub Actions job and explicit run attempt. The server verifies exact attempt membership before and after retrieval and never downloads a workflow-run log archive. Supports a UTF-8 byte cap, a literal tail selection, or inclusive literal start/end markers; it exposes no regex, shell, rerun, cancel, delete, or dispatch operation. sha256 fingerprints the complete normalized plaintext source before selection.
Inputs: repo (required), owner (required), job_id (required), attempt (required), +4 more. Returns: Bounded logs for one exact job in one exact workflow-run attempt.
gh_get_merge_requirementsGet exact-head pull request merge requirementsARead-onlyIdempotent
Read-only: aggregate effective branch/ruleset merge policy, current required checks, exact-head review/thread state, base freshness, mergeability, and allowed merge methods for one expected pull-request head. Missing policy visibility or head movement is reported as incomplete evidence and never interpreted as no requirement.
Inputs: repo (required), owner (required), number (required), expected_head_sha (required). Returns: Conservative exact-head aggregate of merge-policy and readiness evidence.
gh_get_prGet pull request snapshotARead-onlyIdempotent
Read-only: return bounded metadata and exact base/head commit SHAs for one GitHub pull request. Performs one noninteractive GET request and cannot create comments, submit reviews, merge the pull request, request approval, or modify GitHub state.
Inputs: repo (required), owner (required), number (required). Returns: A pull request with additional fields.
gh_get_pr_checksGet pull request checksARead-onlyIdempotent
Read-only: return a bounded structured summary of CI checks for one exact pull-request head revision. This performs no watching, log download, workflow dispatch, approval, or GitHub write.
Inputs: repo (required), owner (required), number (required), max_checks, +1 more. Returns: Bounded CI check summary for an immutable pull-request snapshot.
gh_get_pr_diffRead pull request diffARead-onlyIdempotent
Read-only: return a bounded unified diff or patch for the exact immutable base and head commit SHAs currently identified by a pull request. The result reports truncation, byte counts, and a SHA-256 fingerprint. This tool never checks out code, runs tests, requests approval, or modifies GitHub.
Inputs: repo (required), owner (required), number (required), format, +1 more. Returns: Bounded diff or patch for an immutable pull-request snapshot.
gh_get_pr_review_eligibilityGet pull request review eligibilityARead-onlyIdempotent
Read-only exact-head preflight: report the pull-request author, ordinary GitHub identity, configured reviewer identity, and whether an independent APPROVED review or ordinary COMMENTED review is currently eligible. This advisory call performs no review write and never mints a reviewer installation token.
Inputs: repo (required), owner (required), number (required), expected_head_sha (required). Returns: Advisory review eligibility bound to one exact pull-request head.
gh_get_pr_review_stateGet exact-head pull request review stateARead-onlyIdempotent
Read-only: aggregate bounded review, requested-reviewer, and unresolved-thread evidence only for an exact expected PR head. Head mismatch or partial evidence prevents a definitive satisfied result.
Inputs: repo (required), owner (required), number (required), expected_head_sha (required). Returns: Conservative exact-head aggregate of review evidence for one pull request.
gh_get_refGet exact Git referenceARead-onlyIdempotent
Read-only: resolve one exact branch or tag reference path such as heads/main or tags/v1.0.0. This tool never performs matching-reference or prefix discovery. Annotated tag objects retain their tag-object identity and are peeled through bounded exact tag-object reads to a commit when applicable.
Inputs: ref (required), repo (required), owner (required). Returns: Exact Git reference identity and optional annotated-tag peel result.
gh_get_releaseARead-onlyIdempotent
Get details of a specific release.
Inputs: tag (required), repo (required), owner (required). Returns: A release.
gh_get_repoBRead-onlyIdempotent
Get details of a specific repository.
Inputs: repo (required), owner (required). Returns: A GitHub repository.
gh_get_runARead-onlyIdempotent
Get details of a specific GitHub Actions workflow run.
Inputs: repo (required), owner (required), run_id (required). Returns: A GitHub Actions workflow run.
gh_get_run_logsGet exact workflow run logsARead-onlyIdempotent
Read-only: stream bounded log evidence for one exact GitHub Actions workflow run attempt by enumerating that attempt's jobs and reading their plaintext job-log endpoints in stable job-ID order. The run-log ZIP endpoint is never used. The attempt is mandatory and is never silently replaced by the latest attempt. Supports a UTF-8 byte cap, a literal tail selection, or inclusive literal start/end markers; it exposes no regex, shell, rerun, cancel, delete, or dispatch operation. sha256 fingerprints the complete normalized aggregate before selection.
Inputs: repo (required), owner (required), run_id (required), attempt (required), +4 more. Returns: Bounded logs for one exact workflow-run attempt.
gh_get_workflowARead-onlyIdempotent
Get details of a specific GitHub Actions workflow.
Inputs: repo (required), owner (required), workflow_id (required). Returns: A GitHub Actions workflow.
gh_infoARead-onlyIdempotent
Return gh CLI version, authentication status, and active account.
Inputs: no named parameters. Returns: object
gh_list_artifact_filesList workflow artifact filesARead-onlyIdempotent
Read-only: inspect one exact, unexpired GitHub Actions artifact ZIP and return one bounded page of normalized regular-file paths and sizes. The archive is downloaded only into temporary server state, never extracted, and is rejected for traversal, absolute paths, duplicate/conflicting paths, symbolic links, special entries, encryption, or configured hard-limit violations. GitHub is never modified.
Inputs: repo (required), owner (required), artifact_id (required), page, +1 more. Returns: One bounded page of normalized artifact file metadata.
gh_list_issuesARead-onlyIdempotent
List issues in a repository.
state: open, closed, or all (default: all). labels: comma-separated label filter.
Inputs: repo (required), owner (required), state, labels, +1 more. Returns: Paginated search results.
gh_list_labelsARead-onlyIdempotent
List labels in a repository.
Inputs: repo (required), owner (required), per_page. Returns: Paginated search results.
gh_list_milestonesARead-onlyIdempotent
List milestones in a repository via the GitHub API.
state: open, closed, or all (default: all).
Inputs: repo (required), owner (required), state, per_page. Returns: Paginated search results.
gh_list_pr_commitsList pull request commitsARead-onlyIdempotent
Read-only: return one bounded page of commits in a pull request, together with its exact base and head SHAs. This tool never checks out code or modifies GitHub.
Inputs: repo (required), owner (required), number (required), page, +1 more. Returns: One bounded page of commits for an immutable pull-request snapshot.
gh_list_pr_filesList pull request filesARead-onlyIdempotent
Read-only: return one bounded page of files changed by a pull request, together with its exact base and head SHAs. A file patch may be absent or truncated by GitHub; use gh_get_pr_diff for the bounded unified diff. This tool never modifies GitHub.
Inputs: repo (required), owner (required), number (required), page, +1 more. Returns: One bounded page of files for an immutable pull-request snapshot.
gh_list_pr_reviewsList pull request reviewsARead-onlyIdempotent
Read-only: return one bounded page of typed pull-request reviews with exact commit provenance and explicit pagination completeness for an unchanged PR head snapshot.
Inputs: repo (required), owner (required), number (required), page, +1 more. Returns: One bounded page of reviews for an unchanged pull-request head snapshot.
gh_list_prsBRead-onlyIdempotent
List pull requests in a repository.
state: open, closed, or all (default: open).
Inputs: repo (required), owner (required), state, per_page. Returns: Paginated search results.
gh_list_releasesARead-onlyIdempotent
List releases in a repository.
Inputs: repo (required), owner (required), per_page. Returns: Paginated search results.
gh_list_reposCRead-onlyIdempotent
List repositories for a user or organization.
type: all, owner, member, public, private, fork.
Inputs: sort, type, per_page, username, +1 more. Returns: Paginated search results.
gh_list_run_artifactsList workflow run artifactsARead-onlyIdempotent
Read-only: return one bounded page of immutable GitHub Actions artifact metadata for an exact workflow run. Optional name filtering is exact; archives are never downloaded and GitHub is never modified.
Inputs: repo (required), owner (required), run_id (required), name, +2 more. Returns: One bounded artifact page pinned to an exact workflow-run attempt/head.
gh_list_run_jobsList workflow run jobsARead-onlyIdempotent
Read-only: return one bounded page of jobs and step metadata for an exact GitHub Actions run attempt. This downloads no logs, performs no watching or workflow dispatch, and never modifies GitHub.
Inputs: repo (required), owner (required), run_id (required), page, +2 more. Returns: One bounded page of jobs for an exact workflow-run attempt.
gh_list_runsARead-onlyIdempotent
List one authoritative, bounded page of GitHub Actions workflow runs.
Existing branch, status, and per_page callers remain supported. Exact workflow, head-SHA, event, actor, creation-range, and check-suite filters are sent to GitHub's workflow-runs REST route rather than applied locally.
Inputs: repo (required), owner (required), page, actor, +9 more. Returns: One bounded workflow-run result page with explicit completeness metadata.
gh_list_workflowsARead-onlyIdempotent
List GitHub Actions workflows in a repository.
state: active, all, disabled, disabled_inactivity, disabled_fork.
Inputs: repo (required), owner (required), state, per_page. Returns: Paginated search results.
gh_merge_prMerge pull request at exact headADestructive
Destructive write: merge exactly one pull request using the explicit merge strategy only while its head matches expected_head_sha. Ordinary write authorization and the separate PR-merge fine gate are required. The tool cannot use administrator bypass, delete the branch, force a changed revision, or blindly retry an ambiguous merge.
Inputs: repo (required), owner (required), method (required), number (required), +3 more. Returns: Authoritative outcome of one exact-head pull-request merge attempt.
gh_read_artifact_fileRead workflow artifact text fileARead-onlyIdempotent
Read-only: retrieve one exact normalized regular-file path from one exact, unexpired GitHub Actions artifact. Only valid UTF-8 text/JSON is returned. Returned content is bounded by max_bytes and the server hard cap, while sha256 fingerprints the complete validated file. The ZIP is temporary and never extracted; GitHub is never modified.
Inputs: path (required), repo (required), owner (required), artifact_id (required), +1 more. Returns: Bounded UTF-8 contents for one exact normalized artifact file.
gh_request_pr_changesRequest pull request changes at exact headA
Additive write: submit exactly one formal GitHub CHANGES_REQUESTED review for the supplied exact pull-request head through the server-configured reviewer principal. The exact expected reviewer login is a compare-only precondition and cannot select credentials. The review POST is attempted once and immutable review-ID readback verifies state, actor, head, and body. It cannot approve, merge, dismiss reviews, or replay an ambiguous mutation.
Inputs: body (required), repo (required), owner (required), number (required), +2 more. Returns: Outcome of one action-specific GitHub CHANGES_REQUESTED review attempt.
gh_run_workflow_exactDispatch workflow at exact refADestructive
Destructive write: after ordinary write authorization, exact workflow-target policy, and the separate workflow-dispatch fine gate, dispatch exactly one positive workflow ID only when GitHub immediately re-verifies the caller's exact canonical workflow path and active state. The tool also verifies the exact branch/tag ref against expected_ref_sha, rejects same-name branch/tag ambiguity and an existing workflow_dispatch run for the workflow/head, accepts only a bounded typed input object, requests return_run_details, and binds authoritative readback to the exact returned run ID. It never redispatches automatically.
Inputs: ref (required), repo (required), owner (required), workflow_id (required), +3 more. Returns: Authoritative outcome of one exact-ref guarded workflow dispatch.
gh_search_codeARead-onlyIdempotent
Search GitHub source code.
Supports all GitHub code search qualifiers (e.g. 'func name:main language:python').
Inputs: query (required), per_page. Returns: Paginated search results.
gh_search_issuesARead-onlyIdempotent
Search GitHub issues and pull requests.
Supports all GitHub search qualifiers (e.g. 'is:open label:bug author:user'). Use 'is:pr' for pull requests only, 'is:issue' for issues only.
Inputs: query (required), sort, order, per_page. Returns: Paginated search results.
gh_search_reposARead-onlyIdempotent
Search GitHub repositories.
Supports all GitHub search qualifiers (e.g. 'language:python stars:>1000'). Use 'is:fork' to exclude forks, 'archived:false' to exclude archived repos.
Inputs: query (required), sort, order, per_page. Returns: Paginated search results.
gh_server_infoGet MCP server versionARead-onlyIdempotent
Read-only local diagnostic: return this MCP server's deployed version, tool-schema version, transport, tool count, and write-policy status. This tool does not call GitHub, spawn a subprocess, request approval, or modify any state.
Inputs: no named parameters. Returns: Local MCP server version, action surface, and write-policy status.
gh_set_issue_stateSet issue state with exact preconditionADestructive
Destructive write: close or reopen exactly one issue only when its current state matches expected_state. Pull requests are rejected. Closing requires completed, not_planned, or duplicate; reopening requires reopened. The mutation is attempted once, comments remain a separate tool, and authoritative readback verifies the final state and reason.
Inputs: repo (required), owner (required), number (required), new_state (required), +2 more. Returns: Authoritative outcome of one guarded issue state transition.
gh_set_pr_draft_stateSet pull request draft state at exact headADestructive
Destructive write: transition exactly one pull request between draft and ready-for-review only when its current head SHA and draft state match the supplied preconditions. The operation changes no unrelated pull-request metadata, is attempted once, and authoritative readback verifies both unchanged head identity and the requested draft state.
Inputs: repo (required), owner (required), number (required), new_is_draft (required), +2 more. Returns: Authoritative outcome of one guarded pull-request draft-state transition.
gh_watch_runARead-onlyIdempotent
Poll a GitHub Actions workflow run until completion or timeout.
Inputs: repo (required), owner (required), run_id (required), interval, +2 more. Returns: Result of watching a workflow run until completion.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 61 tools
While descriptions are unusually detailed, several tool boundaries are genuinely unclear: gh_get_issue explicitly covers pull requests alongside gh_get_pr, gh_get_run_logs/gh_get_job_logs/gh_get_failed_run_logs all overlap on log retrieval, and gh_get_pr_review_state/gh_get_pr_review_eligibility/gh_get_merge_requirements serve similar review-status purposes. An agent selecting among these related tools faces real misselection risk.
The vast majority follow a consistent gh_verb_noun snake_case pattern: gh_list_*, gh_get_*, gh_create_*, gh_edit_*, gh_set_*. Minor deviations like gh_commit_files, gh_watch_run, and the 'exact' suffix on gh_create_release_exact/gh_run_workflow_exact are understandable but slightly break the otherwise predictable scheme.
61 tools is far beyond the well-scoped range and falls into the extreme mismatch category. Even given GitHub's breadth, many micro-specialized read-only variants (multiple log, artifact, and review-state tools) could be consolidated to reduce selection burden.
Despite the large read surface, there are significant lifecycle gaps: pull requests cannot be closed, branches cannot be listed or deleted, workflow runs cannot be cancelled, and labels/releases/milestones lack full update/delete coverage. These missing operations will cause agent dead ends in common GitHub workflows.
Maintenance
Related MCP Connectors
An MCP server that gives your AI access to the source code and docs of all public github repos
Create, deploy, and operate MCP servers directly from your GitHub repositories.
Unofficial GitHub MCP — wraps the GitHub public REST API (no auth required for public endpoints)
MCP server for siGit (sigit.si): browse repos, search code, manage PRs/issues, web search.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps around the GitHub CLI tool, allowing AI assistants to interact with GitHub repositories through commands for pull requests, issues, and repository operations.19 npm2MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the GitHub CLI to provide comprehensive access to repository management, pull requests, issues, and workflows. It enables users to perform complex GitHub operations and interact with the GitHub API through a standardized interface.1ISC
- FlicenseNot gradedqualityDmaintenanceMCP server for the GitHub REST API that enables interaction with repositories, pull requests, issues, branches, commits, reviews, and code search, with configurable write and destructive operations.-
- FlicenseNot gradedqualityDmaintenanceA read-only MCP server that exposes GitHub user profiles, repository info, and search via tools for AI assistants like Claude.-