Tools Reference

Read Server (gh-tooling)

Tools available via the gh-tooling MCP server. Requires gh CLI installed and authenticated.

Shared Tool Parameters

All gh-tooling MCP tools accept these parameters:

Parameter	Type	Default	Description
`suppress_errors`	boolean	`false`	Silence stderr; errors produce empty output instead of an error message
`fallback`	string	--	Return this text (successfully) when the gh command fails

Tools that produce structured JSON output also accept jq_filter (string) for filtering and transforming results with full jq expression syntax. A syntax check runs before execution to give early feedback on invalid expressions.

pr_view, pr_list, run_view, run_list, issue_view, issue_list, and search only emit JSON when fields is set; without it the underlying gh command prints a human-readable summary. On those seven, a jq_filter passed without fields is rejected before the call, with an error naming both. issue_view also emits JSON under with_field_values: true, which satisfies the requirement on its own.

Tools with large text output (run_logs, job_logs, pr_diff) additionally accept:

Parameter	Type	Description
`max_lines`	integer	Return only the first N lines (`head -n N`)
`tail_lines`	integer	Return only the last N lines (`tail -n N`)
`grep_pattern`	string	Extended regex filter (grep -E); non-matching lines removed
`grep_context_before`	integer	Lines of context before each match (-B)
`grep_context_after`	integer	Lines of context after each match (-A)
`grep_ignore_case`	boolean	Case-insensitive matching (-i)
`grep_invert`	boolean	Return non-matching lines (-v)

A grep_pattern that grep -E rejects, such as an unbalanced (, fails the call with Error: Invalid grep_pattern before gh runs, the same as an invalid jq_filter. A pattern that matches nothing is not an error. The result is empty.

max_lines and tail_lines are also available on pr_view, pr_checks, pr_comments, pr_reviews, issue_view, api_read, label_list, project_list, and project_view for output size control.

job_logs, repo_file, and api_read remove terminal escape sequences from the text they return, so grep_pattern, max_lines, and tail_lines work on the words rather than on the colour codes wrapped around them. repo_file with download_to is the exception: it writes the file's bytes unchanged.

Repository selection

PR, issue, search, commit, and repo browsing tools accept the repository in any of these shapes — pass whichever matches the data you have:

Shape	Example	Notes
`repo`	`repo: "shopware/shopware"`	Owner/repo string. Legacy short form.
`repository`	`repository: "shopware/shopware"`	Owner/repo string. Alias of `repo`.
`owner` + `repo`	`owner: "shopware"`, `repo: "shopware"`	Split form. `repo` must be the bare name (no `/`).
`url` (repo tools only)	`url: "https://github.com/shopware/shopware/blob/..."`	Parsed for owner/repo/ref/path.

If none of the above is supplied, the default repo from .mcp-gh-tooling.json is used. PR and issue tools also fall back to the local git remote when invoked inside a clone; outside a git repository they fail with a prescriptive error rather than letting gh's native git-detection error surface.

Unknown parameters are rejected at the MCP layer (additionalProperties: false), so a misspelled or fabricated field returns an explicit error instead of being silently dropped.

`pr_view`

View pull request details.

Use gh-tooling pr_view with number 14642
Use gh-tooling pr_view with number 14642 and fields "title,body,state,reviews"
Use gh-tooling pr_view with number 14642 and comments true

Parameters:

number (integer, required): PR number.
Repository selection: see Repository selection.
fields (string, optional): Comma-separated JSON fields (e.g. title,body,state,reviews,files)
comments (boolean, optional): Append the PR's comments and reviews to the text output, after a --- comments and reviews --- line. Ignored when fields is set. max_lines counts the PR and its comments together. The limits listed under issue_view apply here too.

`pr_diff`

Get the unified diff for a pull request.

Use gh-tooling pr_diff with number 14642
Use gh-tooling pr_diff with number 14642 and file "src/Core/Migration/V6_6/Migration1720094362.php"
Use gh-tooling pr_diff with number 14642 and name_only true

Parameters:

number (integer, required): PR number.
file (string, optional): Limit diff to a specific file path.
name_only (boolean, optional): List only changed file names.
max_lines (integer, optional): Return only the first N lines.
tail_lines (integer, optional): Return only the last N lines.
grep_pattern (string, optional): Filter lines by extended regex.
grep_context_before / grep_context_after (integer, optional): Context lines around matches.
grep_ignore_case (boolean, optional): Case-insensitive grep.
grep_invert (boolean, optional): Return non-matching lines.

`pr_list`

List pull requests with filters.

Use gh-tooling pr_list with author "mitelg" and state "merged" and limit 5
Use gh-tooling pr_list with search "NEXT-3412" and state "all"
Use gh-tooling pr_list with head "feature/my-branch"

`pr_checks`

View CI status checks for a pull request.

Use gh-tooling pr_checks with number 14642

`pr_comments`

Get inline review comments (code-level) for a PR.

Use gh-tooling pr_comments with number 14642
Use gh-tooling pr_comments with number 14642 and jq_filter ".[] | {path, body, line, user: .user.login}"

`pr_reviews`

Get review decisions for a pull request.

Use gh-tooling pr_reviews with number 14642
Use gh-tooling pr_reviews with number 14642 and jq_filter ".[] | select(.state == \"CHANGES_REQUESTED\") | {user: .user.login, body}"

`pr_files`

Get changed files with patch content.

Use gh-tooling pr_files with number 13911
Use gh-tooling pr_files with number 13911 and jq_filter ".[] | select(.filename | contains(\"Migration\")) | {filename, patch}"

`pr_commits`

Get the commit history for a pull request.

Use gh-tooling pr_commits with number 14642

`issue_view`

View a GitHub issue.

Use gh-tooling issue_view with number 8498
Use gh-tooling issue_view with number 8498 and with_comments true
Use gh-tooling issue_view with number 8498 and fields "title,body,state,labels,comments"
Use gh-tooling issue_view with number 8498 and with_field_values true

with_comments: true appends the issue's comments to the text output, after a --- comments --- line. It is ignored when fields is set, and rejected together with with_field_values. max_lines counts the issue and its comments together, so a long body can leave the comments out.

The issue and its comments come from two gh calls. If the comments call fails, the whole call fails, or returns fallback; the tool never returns the issue without its comments. Known limits, which apply to pr_view with comments too:

A comment posted or deleted between the two calls makes the issue's comments: count disagree with the list that follows.
gh leaves hidden (minimized) comments out of the list, so an issue whose only comments are hidden shows a count but no separator.
The separator is plain text: a body that contains the same line reads as the start of the comments.

with_field_values returns the issue's type and its field values keyed by field name, which gh issue view exposes for neither:

{"type": "Bug", "field_values": {"Priority": "Low", "Effort": "Low"}}

The field_values object is the shape issue_field_set takes, so it can be read, edited, and passed straight back. Output is always JSON; combine it with fields to add gh's own fields to the same document, and request comments separately.

`issue_list`

List issues with filters.

Use gh-tooling issue_list with search "TODO label:component/core" and limit 20

`issue_schema`

List an organization's issue types and issue fields, including each single-select field's options. The organization comes from org, owner, a repository parameter, the configured default repo, or the current clone's remote. When none of them supplies one, the error says org is required and, when reading the clone's remote failed, includes gh's message unless suppress_errors is set.

Types and fields are independent. GitHub lets an organization pin fields to a type, but that pinning only drives the web UI: any organization field can be set on an issue of any type, so this tool reports the two lists side by side instead of nesting fields under types.

type and field match one name exactly, case-insensitively, and each narrows only its own list. A name that matches nothing is an error rather than an empty list.

Use gh-tooling issue_schema with repo "shopware/shopware"
Use gh-tooling issue_schema with org "shopware" and type "Bug"
Use gh-tooling issue_schema with field "Priority" and jq_filter "[.fields[0].options[].name]"

`run_view`

View the status of a GitHub Actions workflow run.

Use gh-tooling run_view with run_id 21534190745
Use gh-tooling run_view with run_id 21534190745 and fields "status,conclusion"

`run_list`

List recent GitHub Actions runs with optional filters.

Use gh-tooling run_list with branch "tests/content-system-unit-tests" and limit 5
Use gh-tooling run_list with workflow "CI" and status "failure" and limit 10
Use gh-tooling run_list with workflow "CI" and branch "main" and event "push"
Use gh-tooling run_list with user "mitelg" and created ">2024-01-01"
Use gh-tooling run_list with commit "abc1234" and fields "databaseId,status,conclusion"

Parameters:

repo (string, optional): Repository in owner/repo format.
branch (string, optional): Filter by branch name.
workflow (string, optional): Filter by workflow name or filename (e.g. CI, build.yml).
status (string, optional): Filter by status (e.g. completed, failure, success).
event (string, optional): Filter by trigger event (e.g. push, pull_request, schedule).
user (string, optional): Filter by GitHub username who triggered the workflow.
created (string, optional): Filter by creation date range (e.g. >2024-01-01).
commit (string, optional): Filter by commit SHA.
limit (integer, optional): Max results. Default: 20.
fields (string, optional): Comma-separated JSON fields.

`run_logs`

Get CI workflow run logs (failed steps by default).

Use gh-tooling run_logs with run_id 22245862281
Use gh-tooling run_logs with run_id 22245862281 and failed_only false and max_lines 500
Use gh-tooling run_logs with run_id 22245862281 and grep_pattern "FAILED|Error" and grep_context_after 3
Use gh-tooling run_logs with run_id 22245862281 and tail_lines 100

Parameters:

run_id (integer, required): Workflow run ID.
failed_only (boolean): Return only failed step logs. Default: true.
max_lines (integer, optional): Return only the first N lines.
tail_lines (integer, optional): Return only the last N lines.
grep_pattern (string, optional): Filter lines by extended regex.
grep_context_before / grep_context_after (integer, optional): Context lines around matches.
grep_ignore_case (boolean, optional): Case-insensitive grep.
grep_invert (boolean, optional): Return non-matching lines.

`workflow_jobs`

Aggregate jobs across workflow runs in a single call. Reduces N+1 tool calls (run_list + N x job_view) to one invocation. Fetches runs for a workflow, then retrieves jobs for each run. If the jobs of any run cannot be fetched, the call fails, or returns fallback when set, rather than returning the jobs of the other runs.

Use gh-tooling workflow_jobs with workflow "CI" and repo "shopware/shopware" and job "PHPStan" and limit 3
Use gh-tooling workflow_jobs with workflow "CI" and repo "shopware/shopware" and conclusion "failure"
Use gh-tooling workflow_jobs with workflow "CI" and repo "shopware/shopware" and job "unit" and step "Run tests" and limit 5
Use gh-tooling workflow_jobs with workflow "CI" and repo "shopware/shopware" and run_status "failure" and branch "main"

Parameters:

workflow (string, required): Workflow name or filename (e.g. CI, build.yml).
repo (string, required): Repository in owner/repo format (pass explicitly or configure default).
job (string, optional): Filter jobs by name (case-insensitive substring).
conclusion (string, optional): Filter by job conclusion (e.g. failure, success).
step (string, optional): Filter and include steps by name. Steps are excluded unless this is set.
limit (integer, optional): Max workflow runs to fetch (each = 1 API call). Default: 5.
run_status (string, optional): Filter runs by status.
branch (string, optional): Filter runs by branch.
event (string, optional): Filter runs by trigger event.
jq_filter (string, optional): jq expression to filter the final output.
max_lines (integer, optional): Return only the first N lines.

`job_view`

Get details for a specific CI job including step statuses.

Use gh-tooling job_view with job_id 62056364818
Use gh-tooling job_view with job_id 62056364818 and jq_filter ".steps[] | select(.conclusion == \"failure\") | {name, number}"

`job_logs`

Get log output for a specific CI job, with terminal escape sequences removed.

Use gh-tooling job_logs with job_id 62056364818
Use gh-tooling job_logs with job_id 62056364818 and max_lines 200
Use gh-tooling job_logs with job_id 62056364818 and grep_pattern "Fatal|Exception" and grep_context_after 5
Use gh-tooling job_logs with job_id 62056364818 and tail_lines 50

Parameters:

job_id (integer, required): GitHub Actions job ID.
max_lines (integer, optional): Return only the first N lines.
tail_lines (integer, optional): Return only the last N lines.
grep_pattern (string, optional): Filter lines by extended regex.
grep_context_before / grep_context_after (integer, optional): Context lines around matches.
grep_ignore_case (boolean, optional): Case-insensitive grep.
grep_invert (boolean, optional): Return non-matching lines.

`job_annotations`

Get inline error annotations from a CI check run.

Use gh-tooling job_annotations with check_run_id 62056364818

`commit_pulls`

List GitHub pull requests associated with a pushed commit SHA. GitHub-only -- for local commit metadata (files changed, commit message) use git show <sha> via Bash.

Use gh-tooling commit_pulls with sha "15a7c2bb86"
Use gh-tooling commit_pulls with sha "15a7c2bb86" and jq_filter ".[].number"

Parameters:

sha (string, required): Commit SHA (7-40 hex characters). Must be pushed to GitHub.
repo (string, optional): Repository in owner/repo format.
jq_filter (string, optional): jq expression to filter/transform the PR list.

`search`

Search for issues or pull requests.

Use gh-tooling search with search "NEXT-3412" and type "prs"
Use gh-tooling search with search "custom field translation" and type "issues" and limit 20
Use gh-tooling search with search "attribute entity" and state "closed"
Use gh-tooling search with search "\"custom field\" label:\"good first issue\"" and type "issues"

Search expressions (search, search_repos, search_commits): each word is its own keyword, so a result has to match all of them, in any order. Double quotes keep a phrase together ("custom field"), also as a qualifier value (label:"good first issue"). A search with an unmatched " fails before gh runs. gh cannot pass three forms through: a negated phrase (-"exact phrase" becomes a phrase that starts with -; use NOT "exact phrase"), a quoted single word ("OR" becomes the operator), and a phrase containing :.

`search_code`

Search for code across GitHub repositories. Uses the legacy code search engine (no regex, no symbol search, no path globs). Rate limit: 10 requests/minute.

Use gh-tooling search_code with search "addClass" and repo "shopware/shopware"
Use gh-tooling search_code with search "extends AbstractController" and language "php" and limit 10
Use gh-tooling search_code with search "composer.json" and match "path" and owner "shopware"
Use gh-tooling search_code with search "addClass" and repo "shopware/shopware" and download_to "/tmp/results"

Parameters:

search (string, required): Code search expression, matched as exact text (no regex). Unlike the other search tools, the whole value is one phrase.
owner (string, optional): Limit to repositories owned by this user/org, instead of the configured default repo. With a bare repo name in repo, the two form owner/repo.
repo (string, optional): Limit to this repository, as owner/repo or as a bare name together with owner. An owner passed with an owner/repo value must name the same owner.
language (string, optional): Filter by language (e.g. php, typescript).
extension (string, optional): Filter by file extension (e.g. php, ts).
filename (string, optional): Filter by filename (e.g. composer.json).
match (string, optional): Restrict matches to file contents or path.
limit (integer, optional): Max results. Default: 30.
download_to (string, optional): Local directory. Downloads matching files instead of returning results.
Supports all grep parameters and max_lines/tail_lines.

`search_repos`

Search for repositories by search expression, owner, topic, language, license, or star count. search is optional -- filters alone suffice.

Use gh-tooling search_repos with owner "shopware" and language "php"
Use gh-tooling search_repos with search "ecommerce" and stars ">100" and sort "stars"
Use gh-tooling search_repos with topic "shopware" and limit 10

Parameters:

search (string, optional): Search expression; see Search expressions. A value with no words searches by the filters alone.
owner (string, optional): Filter by owner.
topic (string, optional): Filter by topic tag.
language (string, optional): Filter by language.
license (string, optional): Filter by SPDX license (e.g. mit).
stars (string, optional): Star count range (e.g. >100, 50..200).
sort (string, optional): stars, forks, help-wanted-issues, or updated.
limit (integer, optional): Max results. Default: 20.

`search_commits`

Search for commits by message text, author, date range, or hash.

Use gh-tooling search_commits with search "NEXT-1234" and repo "shopware/shopware"
Use gh-tooling search_commits with search "fix cart" and author "mitelg" and author_date ">2024-01-01"

Parameters:

search (string, required): Commit message search expression; see Search expressions.
repo (string, optional): Limit to this repository, as owner/repo or as a bare name together with owner. An owner passed with an owner/repo value must name the same owner.
owner (string, optional): Limit to repositories owned by this user/org, instead of the configured default repo. With a bare repo name in repo, the two form owner/repo.
author (string, optional): Filter by commit author username.
committer (string, optional): Filter by committer username.
author_date (string, optional): Date range (e.g. >2024-01-01, 2024-01-01..2024-06-30).
committer_date (string, optional): Committer date range.
hash (string, optional): Filter by SHA prefix.
merge (boolean, optional): Filter merge commits.
sort (string, optional): author-date or committer-date.
limit (integer, optional): Max results. Default: 20.

`search_discussions`

Search for GitHub discussions via GraphQL. Discussions are only available via GraphQL.

Use gh-tooling search_discussions with search "RFC" and repo "shopware/shopware"
Use gh-tooling search_discussions with search "authentication" and category "Q&A" and with_comments true

Parameters:

search (string, required): Discussion search text.
repo (string, optional): Limit to this repository in owner/repo format.
category (string, optional): Filter by category name (e.g. RFC, Q&A).
author (string, optional): Filter by author username.
state (string, optional): State qualifier (e.g. is:answered, is:open).
with_comments (boolean, optional): Include comment bodies and replies. Default: false.
limit (integer, optional): Max results. Default: 20.
jq_filter (string, optional): Applied to full GraphQL response. Default: .data.search.nodes.

`repo_tree`

Browse repository directory contents or get the full recursive file tree. Accepts GitHub URLs. Use instead of WebFetch on GitHub tree URLs.

Use gh-tooling repo_tree with url "https://github.com/shopware/shopware/tree/main/src/Core"
Use gh-tooling repo_tree with repository "shopware/shopware" and path "src/Core"
Use gh-tooling repo_tree with repository "shopware/shopware" and recursive true

Parameters:

owner (string, optional): Repository owner. Used with repo.
repo (string, optional): Repository name. Used with owner.
repository (string, optional): owner/repo format.
path (string, optional): Directory path. Default: root.
ref (string, optional): Branch, tag, or SHA.
recursive (boolean, optional): Get full recursive tree. Default: false.
url (string, optional): GitHub URL to parse. Explicit params override URL values. Note: URLs with slashed refs (e.g. feature/my-branch) are not parsed correctly -- use explicit ref param instead.

`repo_file`

Fetch a single file from a GitHub repository as raw text. Accepts GitHub URLs. Use instead of WebFetch on GitHub blob URLs.

Use gh-tooling repo_file with url "https://github.com/shopware/shopware/blob/main/composer.json"
Use gh-tooling repo_file with repository "shopware/shopware" and path "composer.json"
Use gh-tooling repo_file with repository "shopware/shopware" and path "src/Core/Kernel.php" and line_start 1 and line_end 20
Use gh-tooling repo_file with repository "shopware/shopware" and path "composer.json" and download_to "/tmp/composer.json"

Parameters:

owner (string, optional): Repository owner. Used with repo.
repo (string, optional): Repository name. Used with owner.
repository (string, optional): owner/repo format.
path (string, required unless from URL): File path within the repository.
ref (string, optional): Branch, tag, or SHA.
url (string, optional): GitHub URL to parse. Explicit params override URL values. Note: URLs with slashed refs (e.g. feature/my-branch) are not parsed correctly -- use explicit ref param instead.
line_start (integer, optional): First line to return (1-indexed).
line_end (integer, optional): Last line to return (inclusive).
download_to (string, optional): Local path. Saves file content instead of returning it.
Supports all grep parameters and max_lines/tail_lines.

`release_list`

Look up release versions for one or more repositories. Built for dependency-update tasks: pass a repos array to get the latest version of each in a single call instead of one api_read per repo. Releases are sorted by semantic version descending (not by publish date), so the highest version is treated as latest.

Use gh-tooling release_list with repos ["actions/checkout", "actions/setup-node", "docker/build-push-action"] and fields ["repo", "tag_name"]
Use gh-tooling release_list with repo "docker/setup-buildx-action" and jq_filter ".[].tag_name"
Use gh-tooling release_list with repo "docker/build-push-action" and constraint "4" and latest false
Use gh-tooling release_list with repo "actions/setup-python" and resolve_sha true and fields ["tag_name", "commit_sha"]
Use gh-tooling release_list with repo "nodejs/node" and include_prereleases true and limit 50 and latest false

Parameters:

repos (array of strings, optional): Batch mode -- repositories in owner/repo format. When set, the single-repo parameters are ignored and one entry is returned per repo.
repo (string, optional): Single repository in owner/repo format. Also accepts owner+repo, repository, or url. Falls back to the configured default repo.
latest (boolean, optional): Return only the highest-version release per repo. Default true. Set false for the full filtered list.
constraint (string, optional): Restrict to a version line by prefix -- a major (4/v4) or major.minor (4.2/v4.2). Range operators (^, ~, >=, <) are not supported. Filtering applies within the fetched window, so increase limit to reach older major lines.
include_prereleases (boolean, optional): Consider prereleases. Default false (matches GitHub's releases/latest behavior).
include_drafts (boolean, optional): Consider draft releases. Default false.
limit (integer, optional): Releases fetched per repo before filtering. Default 30, capped at 100.
resolve_sha (boolean, optional): Add a commit_sha field by resolving each tag to its commit (lightweight and annotated tags both resolve correctly). One extra API call per result. Useful for pinning GitHub Actions to an immutable SHA.
fields (array of strings, optional): Restrict each result object to these keys. Allowed: repo, tag_name, name, published_at, html_url, prerelease, draft, commit_sha. Example: ["tag_name"] for just version numbers.
jq_filter (string, optional): jq expression applied to the final result array. Output is JSON; .[].tag_name reduces it to the (JSON-quoted) version strings.
suppress_errors (boolean, optional): In batch mode, skip a repo whose lookup fails instead of failing the whole call.
fallback (string, optional): Text to return if a lookup fails.

`label_list`

List labels for a repository. Returns label names, descriptions, and colors.

Use gh-tooling label_list
Use gh-tooling label_list with repo "shopware/shopware"
Use gh-tooling label_list with filter "bug"
Use gh-tooling label_list with jq_filter ".[] | {name, description}"

Parameters:

repo (string, optional): Repository in owner/repo format.
filter (string, optional): Filter labels by name substring (case-insensitive).
jq_filter (string, optional): jq expression to filter/transform the JSON output.
max_lines (integer, optional): Return only the first N lines.

`project_list`

List GitHub Projects (v2) for a user or organization. Returns project numbers, titles, and URLs.

Use gh-tooling project_list
Use gh-tooling project_list with owner "shopware"
Use gh-tooling project_list with jq_filter ".[] | {number, title}"

Parameters:

owner (string, optional): Owner (user or org) to list projects for. Defaults to the owner from the configured default repo.
jq_filter (string, optional): jq expression to filter/transform the JSON output.
max_lines (integer, optional): Return only the first N lines.

`project_view`

View details of a GitHub Project (v2), including field definitions and status options. Use to discover available status values before setting them.

Use gh-tooling project_view with number 5
Use gh-tooling project_view with number 5 and owner "shopware"
Use gh-tooling project_view with number 5 and jq_filter ".fields[] | select(.name == \"Status\")"

Parameters:

number (integer, required): Project number.
owner (string, optional): Owner (user or org). Defaults to the owner from the configured default repo.
jq_filter (string, optional): jq expression to filter/transform the JSON output.
max_lines (integer, optional): Return only the first N lines.

`api_read`

Read-only GitHub REST API call (GET only). Use the gh-tooling-write server's api tool for POST, PATCH, PUT, or DELETE requests.

Use gh-tooling api_read with endpoint "repos/shopware/shopware/issues/8498/timeline"
Use gh-tooling api_read with endpoint "repos/shopware/shopware/pulls/14642/comments" and paginate true
Use gh-tooling api_read with endpoint "search/issues" and jq_filter ".items[] | {number, title, state}"

Parameters:

endpoint (string, required): GitHub API endpoint, relative to https://api.github.com/.
method (string, optional): HTTP method. Enum: GET, POST, PATCH, PUT, DELETE. Default: GET.
jq_filter (string, optional): jq expression to filter/transform the JSON response.
paginate (boolean, optional): Fetch all pages of paginated results. Default: false.
fields (string, optional): Comma-separated fields for --jq selection.
max_lines (integer, optional): Return only the first N lines of output.
tail_lines (integer, optional): Return only the last N lines of output.

Write Server (gh-tooling-write)

Tools available via the gh-tooling-write MCP server. Requires enable_write_server: true in .mcp-gh-tooling.json.

Shared Tool Parameters

All gh-tooling-write MCP tools except comment_edit accept these parameters. comment_edit declares neither, so a failed edit always returns an error:

Parameter	Type	Default	Description
`suppress_errors`	boolean	`false`	Silence stderr; errors produce empty output instead of an error message
`fallback`	string	--	Return this text (successfully) when the gh command fails

Unknown parameters are rejected at the MCP layer (additionalProperties: false), the same as on the read server. A misspelled or unsupported field (e.g. body_file on pr_edit) returns an error naming the allowed parameters instead of being silently dropped from the write.

PR Write Tools

`pr_create`

Create a new pull request. Opens a PR from the current or specified branch. Use draft to create a draft PR that is not ready for review.

Use gh-tooling-write pr_create with title "Fix cart calculation" and body "Resolves NEXT-1234"
Use gh-tooling-write pr_create with title "Add feature" and base "main" and head "feature/my-feature" and draft true
Use gh-tooling-write pr_create with title "Bug fix" and labels ["bug", "priority/high"] and assignees ["mitelg"]

Parameters:

title (string, required): Title of the pull request.
body (string, optional): Body text (description) of the pull request.
base (string, optional): Base branch to merge into (e.g. main). Defaults to the repository's default branch.
head (string, optional): Head branch containing the changes. Defaults to the current branch.
draft (boolean, optional): Create as a draft pull request. Default: false.
labels (array of strings, optional): Labels to apply to the pull request.
assignees (array of strings, optional): GitHub usernames to assign.
reviewers (array of strings, optional): GitHub usernames to request reviews from.
milestone (string, optional): Milestone name or number.
repo (string, optional): Repository in owner/repo format.

`pr_edit`

Edit an existing pull request's metadata: title, body, base branch, labels, assignees, or milestone. Labels and assignees are added (not replaced). Use the GitHub API tool to remove labels or assignees.

Use gh-tooling-write pr_edit with number 14642 and title "Updated title"
Use gh-tooling-write pr_edit with number 14642 and labels ["needs-review"] and assignees ["reviewer1"]
Use gh-tooling-write pr_edit with number 14642 and body "Updated description with more context"

Parameters:

number (integer, required): Pull request number.
title (string, optional): New title.
body (string, optional): New body text.
base (string, optional): New base branch.
labels (array of strings, optional): Labels to add.
assignees (array of strings, optional): Usernames to add as assignees.
milestone (string, optional): Milestone name or number.
repo (string, optional): Repository in owner/repo format.

`pr_ready`

Mark a draft pull request as ready for review. Transitions the PR from draft state to open/reviewable state.

Use gh-tooling-write pr_ready with number 14642

Parameters:

number (integer, required): Pull request number.
repo (string, optional): Repository in owner/repo format.

`pr_merge`

Merge a pull request immediately. Supports merge commit, squash, and rebase strategies. Optionally deletes the head branch after merging.

Use gh-tooling-write pr_merge with number 14642
Use gh-tooling-write pr_merge with number 14642 and method "squash" and delete_branch true
Use gh-tooling-write pr_merge with number 14642 and method "squash" and subject "fix: resolve cart calculation"

Parameters:

number (integer, required): Pull request number.
method (string, optional): Merge strategy. Enum: merge, squash, rebase. Default: merge.
delete_branch (boolean, optional): Delete the head branch after merging. Default: false.
subject (string, optional): Subject line for the merge commit (used with merge and squash methods).
body (string, optional): Body text for the merge commit message.
repo (string, optional): Repository in owner/repo format.

`pr_close`

Close a pull request without merging. Optionally posts a comment explaining why the PR is being closed.

Use gh-tooling-write pr_close with number 14642
Use gh-tooling-write pr_close with number 14642 and comment "Superseded by #14650"

Parameters:

number (integer, required): Pull request number.
comment (string, optional): Comment to post when closing.
repo (string, optional): Repository in owner/repo format.

`pr_reopen`

Reopen a previously closed pull request.

Use gh-tooling-write pr_reopen with number 14642

Parameters:

number (integer, required): Pull request number.
repo (string, optional): Repository in owner/repo format.

Review Write Tools

`pr_review_submit`

Submit a review on a pull request, optionally batching inline code comments in a single call. Mirrors the web UI flow: start a review, attach line comments, submit with an event.

When comments is omitted, acts as a plain event-only review submission (uses gh pr review). When comments is provided, posts the full review via the REST reviews endpoint; commit_id is auto-fetched from the PR head if not given. Use ```suggestion blocks inside a comment body for one-click suggested changes.

Use gh-tooling-write pr_review_submit with number 14642 and event "approve"
Use gh-tooling-write pr_review_submit with number 14642 and event "request_changes" and body "A few blockers inline."
Use gh-tooling-write pr_review_submit with number 14642, event "comment", body "Overall LGTM, notes inline.", and comments [{"path": "src/Core/Cart/Calculator.php", "line": 42, "body": "Use strict comparison here."}, {"path": "src/Core/Cart/Calculator.php", "line": 50, "body": "```suggestion\n    return $this->resolve($foo);\n```"}]

Parameters:

number (integer, required): Pull request number.
event (string, optional): Review event type. Enum: approve, request_changes, comment. Default: comment.
body (string, optional): Overall review body text (the top-level summary). Required for request_changes.
comments (array, optional): Inline review comments. Each item: path (string), line (integer), body (string), side (LEFT|RIGHT, default RIGHT), start_line (integer, for multi-line ranges), start_side (LEFT|RIGHT).
commit_id (string, optional): Commit SHA the review is anchored to. Only used when comments is non-empty. Defaults to the PR's current head SHA (auto-fetched).
repo (string, optional): Repository in owner/repo format.

`pr_comment`

Add a general (conversation-tab) comment to a pull request. Not tied to any line or review.

Use gh-tooling-write pr_comment with number 14642 and body "CI is green, ready to merge"

Parameters:

number (integer, required): Pull request number.
body (string, required): Comment body text.
repo (string, optional): Repository in owner/repo format.

`pr_review_reply`

Reply to an existing review comment thread. Posts a threaded reply to a prior review comment (by comment_id), continuing the same conversation thread. Use pr_review_submit to start a new review with inline comments; use this to respond to someone else's existing thread.

Use gh-tooling-write pr_review_reply with number 14642 and comment_id 1234567 and body "Fixed in b8f9a8c, thanks for catching this."

Parameters:

number (integer, required): Pull request number.
comment_id (integer, required): ID of the parent review comment to reply to. Obtain from pr_comments or pr_reviews.
body (string, required): Reply body text.
repo (string, optional): Repository in owner/repo format.

`comment_edit`

Replace the body of one existing comment. Supported: a conversation comment on an issue or a PR, an inline review comment (including one in your own pending review), and a review's summary body. Commit comments and Discussions comments are not supported. The kind comes from the anchor of url, so pass the URL exactly as issue_comment or pr_comment returned it, as the url of a comment from issue_view or pr_view with fields=comments, or as the html_url from pr_comments, pr_reviews, or pr_review_reply. The body replaces the whole comment text; send the full new text, not a diff. Returns the updated comment's URL.

Use gh-tooling-write comment_edit with url "https://github.com/shopware/shopware/pull/14642#issuecomment-2001" and body "CI is green, ready to merge"
Use gh-tooling-write comment_edit with url "shopware/shopware/pull/14642#discussion_r1234567" and body "Fixed in b8f9a8c."

Accepted url forms, each with or without a leading https://github.com/ (http://github.com/ and https://www.github.com/ also work; the scheme and host match without regard to case, so https://GitHub.com/ works too; any other scheme or host is rejected). A ?query before the #, such as ?notification_referrer_id=NT_x, is ignored. OWNER is letters, digits, -, and _ (an Enterprise Managed User account such as mona_octocorp has one). N and ID are digits only. SHA is 7 to 40 hex characters:

`url` form	Edits	Request
`OWNER/REPO/issues/N#issuecomment-ID`	Issue conversation comment	`PATCH repos/OWNER/REPO/issues/comments/ID`
`OWNER/REPO/pull/N#issuecomment-ID`	PR conversation comment	`PATCH repos/OWNER/REPO/issues/comments/ID`
`OWNER/REPO/pull/N#discussion_rID`	Inline review comment	`PATCH repos/OWNER/REPO/pulls/comments/ID` (see below)
`OWNER/REPO/pull/N/files#rID`, `.../changes#rID`, `.../files/SHA#rID`, `.../files/SHA..SHA#rID`, `.../changes/SHA#rID`, `.../changes/SHA..SHA#rID`, or `.../commits/SHA#rID`	Inline review comment	`PATCH repos/OWNER/REPO/pulls/comments/ID` (see below)
`OWNER/REPO/pull/N#pullrequestreview-ID`	Review summary body	`PUT repos/OWNER/REPO/pulls/N/reviews/ID`

Before editing, the tool reads the comment (GET). For a conversation comment or an inline review comment it checks that the comment belongs to the issue or PR N in the URL: the comment's issue_url must end in /issues/N (PR conversation comments also use /issues/N), or its pull_request_url in /pulls/N. A comment of another issue or PR is an error naming both numbers, and nothing is edited. A review summary is read from GET repos/OWNER/REPO/pulls/N/reviews/ID, which carries the PR number in its path. A failed read, including a 404 on a conversation comment or a review summary, is an error with gh's message and no edit.

For the two inline review comment forms, a 404 on that read means the comment is not a submitted one, or the token has no access to the repository. The comment can still be in your own unsubmitted (pending) review, which the REST endpoint does not return. The tool then reads the pending reviews of PR N through GraphQL (the first 100 reviews, each with its first 100 comments) and searches every returned review for the comment's fullDatabaseId. When none matches, it reads further comment pages of a review that reports more, up to 50 pages (5,000 comments) in all. It edits a match with the updatePullRequestReviewComment mutation and returns the comment's url. No author check runs for a match: GitHub refuses to edit another user's comment, and that refusal is the mutation's error. When the lookup finds no match or fails, the error states both facts: Error: comment_edit: GET repos/OWNER/REPO/pulls/comments/ID returned 404 (not found, or no access to the repository); pending-review lookup on PR N: <the lookup's error, or "no matching comment in your pending review">. A failed page and reaching the page limit are lookup errors. A mutation that fails is an error that starts with the same 404 statement, followed by pending-review comment edit failed: ...; a mutation that succeeds without a URL is the same 404 statement followed by the sent-but-no-URL message described below. A read that fails with anything other than a 404 is an error too. A failed read, lookup page, or mutation makes no further call.

Author check: unless allow_other_author is true, the tool takes the node_id from the read of the comment or review summary and asks GitHub, in one GraphQL query (node(id: ID) { ... on Comment { viewerDidAuthor } }), whether the authenticated user wrote it. Any answer other than viewerDidAuthor: true (false, or no value) is an error that names the author (the read's user.login, or "a deleted user" when the read names no login) and says to pass allow_other_author: true, and nothing is edited. A read without a node_id, or a failed query, is an error and nothing is edited. With allow_other_author: true the tool sends no query and skips the check. A comment found through the pending-review lookup is not checked and sends no author query: the lookup searches every pending review it returns for the comment's ID, and GitHub's mutation refuses another author's comment.

Every failure is returned as a tool error, and its message names what failed. When the edit request succeeds but GitHub's response holds no URL, the call is an error too: the message says the edit was sent and GitHub reported success but returned no URL, so the comment may already hold the new body. Output that a successful gh call writes to stderr, such as a warning, does not fail the edit. Any other URL fails before the request: no anchor, an unknown anchor, a non-numeric number or ID, #discussion_rID, #rID, or #pullrequestreview-ID on an issues/N URL, #rID without /files, /changes, /files/SHA, /files/SHA..SHA, /changes/SHA, /changes/SHA..SHA, or /commits/SHA, a malformed SHA segment, a query string after the #, and extra path segments. The repository comes from the URL, so the tool takes no repo parameter.

Parameters:

url (string, required): URL of the comment to edit, with its anchor.
body (string, required): New comment text. Replaces the whole existing text.
allow_other_author (boolean, optional, default false): Editing a comment written by someone else, for example for moderation, requires true.

Issue Write Tools

`issue_create`

Create a new GitHub issue. Supports labels, assignees, milestone, and project.

Use gh-tooling-write issue_create with title "Cart calculation bug" and body "Steps to reproduce..."
Use gh-tooling-write issue_create with title "Feature request" and labels ["enhancement"] and assignees ["mitelg"]
Use gh-tooling-write issue_create with title "Task" and project "Sprint Board"

Parameters:

title (string, required): Title of the issue.
body (string, optional): Body text (description).
labels (array of strings, optional): Labels to apply.
assignees (array of strings, optional): GitHub usernames to assign.
milestone (string, optional): Milestone name or number.
project (string, optional): Project name or URL to add the issue to.
repo (string, optional): Repository in owner/repo format.

`issue_edit`

Edit an existing issue's metadata: title, body, labels, assignees, or milestone. Labels and assignees are added (not replaced). Use the GitHub API tool to remove labels or assignees.

Use gh-tooling-write issue_edit with number 8498 and title "Updated issue title"
Use gh-tooling-write issue_edit with number 8498 and labels ["priority/high"] and assignees ["reviewer1"]

Parameters:

number (integer, required): Issue number.
title (string, optional): New title.
body (string, optional): New body text.
labels (array of strings, optional): Labels to add.
assignees (array of strings, optional): Usernames to add as assignees.
milestone (string, optional): Milestone name or number.
repo (string, optional): Repository in owner/repo format.

`issue_close`

Close an issue. Optionally specify a reason (completed or not_planned) and post a comment when closing.

Use gh-tooling-write issue_close with number 8498
Use gh-tooling-write issue_close with number 8498 and reason "completed" and comment "Fixed in #14642"
Use gh-tooling-write issue_close with number 8498 and reason "not_planned" and comment "Won't fix: out of scope"

Parameters:

number (integer, required): Issue number.
reason (string, optional): Reason for closing. Enum: completed, not_planned.
comment (string, optional): Comment to post when closing.
repo (string, optional): Repository in owner/repo format.

`issue_reopen`

Reopen a previously closed issue.

Use gh-tooling-write issue_reopen with number 8498

Parameters:

number (integer, required): Issue number.
repo (string, optional): Repository in owner/repo format.

`issue_comment`

Issue Type and Field Write Tools

Both tools take names, not IDs, and resolve them against the organization's schema before calling the API, so an unknown name fails with the valid ones listed. Use issue_schema to see what is available. Issue types and issue fields apply to issues only, not pull requests.

`issue_type_set`

Set or clear an issue's type. The name replaces whatever the issue carried before, and null clears it, so repeating the same call leaves the issue in the same state.

Use gh-tooling-write issue_type_set with number 19952 and type "Bug"
Use gh-tooling-write issue_type_set with number 19952 and type null

Parameters:

number (integer, required): Issue number.
type (string or null, required): Issue type name, matched case-insensitively, or null to clear.
repo (string, optional): Repository in owner/repo format.

`issue_field_set`

Replace an issue's field values. The values object becomes the issue's complete set: a field left out is cleared, and {} clears them all. To change one field without dropping the others, read the current values with issue_view and with_field_values true, edit the entry you want, and pass the whole object back — its field_values object and this values object are the same shape, and so is this tool's own response.

Values are typed by the field: a single-select takes an option name, a multi-select takes an array of option names, a date takes YYYY-MM-DD, a number takes a number, and a text field takes a string.

Use gh-tooling-write issue_field_set with number 19952 and values {"Priority": "High", "Effort": "Low"}
Use gh-tooling-write issue_field_set with number 19952 and values {}

Parameters:

number (integer, required): Issue number.
values (object, required): Complete set of field values keyed by field name. {} clears every value.
repo (string, optional): Repository in owner/repo format.

Label Write Tools

`label_add`

Add labels to a pull request or issue by name.

Use gh-tooling-write label_add with number 14642 and type "pr" and labels ["bug", "priority/high"]
Use gh-tooling-write label_add with number 8498 and type "issue" and labels ["needs-triage"]

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
labels (array of strings, required): Label names to add.
repo (string, optional): Repository in owner/repo format.

`label_remove`

Remove labels from a pull request or issue by name.

Use gh-tooling-write label_remove with number 14642 and type "pr" and labels ["needs-triage"]
Use gh-tooling-write label_remove with number 8498 and type "issue" and labels ["bug"]

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
labels (array of strings, required): Label names to remove.
repo (string, optional): Repository in owner/repo format.

Assignee Write Tools

`assignee_add`

Assign users to a pull request or issue.

Use gh-tooling-write assignee_add with number 14642 and type "pr" and assignees ["mitelg", "reviewer1"]
Use gh-tooling-write assignee_add with number 8498 and type "issue" and assignees ["developer1"]

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
assignees (array of strings, required): GitHub usernames to assign.
repo (string, optional): Repository in owner/repo format.

`assignee_remove`

Remove assigned users from a pull request or issue.

Use gh-tooling-write assignee_remove with number 14642 and type "pr" and assignees ["reviewer1"]
Use gh-tooling-write assignee_remove with number 8498 and type "issue" and assignees ["developer1"]

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
assignees (array of strings, required): GitHub usernames to remove.
repo (string, optional): Repository in owner/repo format.

Sub-Issue Write Tools

`sub_issue_add`

Add a sub-issue to a parent issue. Both must exist in the same repository. Uses GitHub's GraphQL sub-issues API.

Use gh-tooling-write sub_issue_add with issue_number 100 and sub_issue_number 101
Use gh-tooling-write sub_issue_add with issue_number 100 and sub_issue_number 101 and repo "shopware/shopware"

Parameters:

issue_number (integer, required): Parent issue number.
sub_issue_number (integer, required): Issue number to add as sub-issue.
repo (string, optional): Repository in owner/repo format.

`sub_issue_remove`

Remove a sub-issue from a parent issue. Uses GitHub's GraphQL sub-issues API.

Use gh-tooling-write sub_issue_remove with issue_number 100 and sub_issue_number 101

Parameters:

issue_number (integer, required): Parent issue number.
sub_issue_number (integer, required): Sub-issue number to remove.
repo (string, optional): Repository in owner/repo format.

Project Write Tools

`project_item_add`

Add an issue or PR to a GitHub Project by project name. The server resolves the project name to its ID.

Use gh-tooling-write project_item_add with number 14642 and type "pr" and project "Sprint Board"
Use gh-tooling-write project_item_add with number 8498 and type "issue" and project "Backlog"

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
project (string, required): Project name (human-readable). Server resolves to project number.
repo (string, optional): Repository in owner/repo format.

`project_status_set`

Set the Status field of an issue or PR in a GitHub Project. Both project and status are specified by name -- the server resolves to IDs. The item must already be in the project (use project_item_add first).

Use gh-tooling-write project_status_set with number 14642 and type "pr" and project "Sprint Board" and status "In Progress"
Use gh-tooling-write project_status_set with number 8498 and type "issue" and project "Sprint Board" and status "Done"

Parameters:

number (integer, required): PR or issue number.
type (string, required): Whether this is a PR or issue. Enum: pr, issue.
project (string, required): Project name. Server resolves to project number.
status (string, required): Status value name (e.g. In Progress, Done). Server resolves to option ID.
repo (string, optional): Repository in owner/repo format.

Write API

`api`

Execute a GitHub API call using gh api. Supports all HTTP methods (GET, POST, PATCH, PUT, DELETE). Use this as an escape hatch when specific write tools don't cover your use case.

Use gh-tooling-write api with endpoint "repos/shopware/shopware/pulls/14642/requested_reviewers" and method "POST"
Use gh-tooling-write api with endpoint "repos/shopware/shopware/issues/8498/labels" and method "DELETE"
Use gh-tooling-write api with endpoint "repos/shopware/shopware/issues/8498/timeline" and jq_filter ".[] | {event, actor: .actor.login}"

Parameters:

endpoint (string, required): GitHub API endpoint, relative to https://api.github.com/.
method (string, optional): HTTP method. Enum: GET, POST, PATCH, PUT, DELETE. Default: GET.
jq_filter (string, optional): jq expression to filter/transform the output.
paginate (boolean, optional): Enable pagination. Default: false.
fields (string, optional): jq expression for --jq flag on the gh api call.
max_lines (integer, optional): Return only the first N lines of output.
tail_lines (integer, optional): Return only the last N lines of output.

Shares the implementation of api_read, including its escape-sequence handling — see Read Server §Shared Tool Parameters.

FilesExpand file tree

REFERENCE.md

Latest commit

History

REFERENCE.md

File metadata and controls

Tools Reference

Read Server (gh-tooling)

Shared Tool Parameters

Repository selection

pr_view

pr_diff

pr_list

pr_checks

pr_comments

pr_reviews

pr_files

pr_commits

issue_view

issue_list

issue_schema

run_view

run_list

run_logs

workflow_jobs

job_view

job_logs

job_annotations

commit_pulls

search

search_code

search_repos

search_commits

search_discussions

repo_tree

repo_file

release_list

label_list

project_list

project_view

api_read

Write Server (gh-tooling-write)

Shared Tool Parameters

PR Write Tools

pr_create

pr_edit

pr_ready

pr_merge

pr_close

pr_reopen

Review Write Tools

pr_review_submit

pr_comment

pr_review_reply

comment_edit

Issue Write Tools

issue_create

issue_edit

issue_close

issue_reopen

issue_comment

Issue Type and Field Write Tools

issue_type_set

issue_field_set

Label Write Tools

label_add

label_remove

Assignee Write Tools

assignee_add

assignee_remove

Sub-Issue Write Tools

sub_issue_add

sub_issue_remove

Project Write Tools

project_item_add

project_status_set

Write API

api

`pr_view`

`pr_diff`

`pr_list`

`pr_checks`

`pr_comments`

`pr_reviews`

`pr_files`

`pr_commits`

`issue_view`

`issue_list`

`issue_schema`

`run_view`

`run_list`

`run_logs`

`workflow_jobs`

`job_view`

`job_logs`

`job_annotations`

`commit_pulls`

`search`

`search_code`

`search_repos`

`search_commits`

`search_discussions`

`repo_tree`

`repo_file`

`release_list`

`label_list`

`project_list`

`project_view`

`api_read`

`pr_create`

`pr_edit`

`pr_ready`

`pr_merge`

`pr_close`

`pr_reopen`

`pr_review_submit`

`pr_comment`

`pr_review_reply`

`comment_edit`

`issue_create`

`issue_edit`

`issue_close`

`issue_reopen`

`issue_comment`

`issue_type_set`

`issue_field_set`

`label_add`

`label_remove`

`assignee_add`

`assignee_remove`

`sub_issue_add`

`sub_issue_remove`

`project_item_add`

`project_status_set`

`api`