Skip to content

Repository navigation

README.md

Latest commit

 

History

History
399 lines (300 loc) · 21.9 KB

README.md

File metadata and controls

399 lines (300 loc) · 21.9 KB
Raw

github-mcp

Experimental Community Project: Maintained by Shopware Labs, not an official Shopware product. Not affiliated with, endorsed by, or sponsored by GitHub, Anthropic, OpenAI, or any other platform or AI provider. Provider and product names are used only to describe compatibility. Provided as-is without warranty.

GitHub CLI tools via MCP (Model Context Protocol). Wraps the gh CLI for pull requests, issues, CI runs, jobs, commits, search, labels, projects, and repository file browsing. Two MCP servers: a read server (always active) and a write server (opt-in). Configuration-optional: works without a config file when gh is authenticated.

Features

Read Server (gh-tooling)

  • PR inspection via pr_view, pr_diff, pr_list, pr_checks
  • PR review data via pr_comments, pr_reviews, pr_files, pr_commits
  • Issue operations via issue_view, issue_list, issue_schema
  • GitHub Actions CI via run_view, run_list, run_logs, workflow_jobs
  • Job-level CI debugging via job_view, job_logs, job_annotations
  • Commit PR lookup via commit_pulls
  • Cross-repo search via search (issues and PRs), search_code, search_repos, search_commits, search_discussions
  • Repository browsing via repo_tree (directory listings) and repo_file (file content) -- use instead of WebFetch on GitHub URLs
  • Release lookup via release_list -- batch latest-version lookup across repos, semver pinning, prerelease handling, tag-to-SHA resolution
  • Labels via label_list
  • Projects via project_list, project_view
  • Read-only API access via api_read (GET only)

Write Server (gh-tooling-write)

  • PR lifecycle via pr_create, pr_edit, pr_ready, pr_merge, pr_close, pr_reopen
  • Reviews via pr_review_submit, pr_comment, pr_review_reply, comment_edit (edits an issue or PR conversation comment, an inline review comment, or a review summary by its URL)
  • Issue lifecycle via issue_create, issue_edit, issue_close, issue_reopen, issue_comment
  • Labels via label_add, label_remove
  • Assignees via assignee_add, assignee_remove
  • Sub-issues via sub_issue_add, sub_issue_remove (GraphQL)
  • Projects via project_item_add, project_status_set (name-to-ID resolution)
  • Full API access via api (all HTTP methods)

Quick Start

Claude Code

/plugin marketplace add shopwareLabs/github-agent-tools
/plugin install github-mcp@github-agent-tools

Restart Claude Code after installation for the MCP servers to initialize.

Codex

codex plugin marketplace add shopwareLabs/github-agent-tools
codex plugin add github-mcp@github-agent-tools

Start a new Codex task after installation. Open /hooks to review and trust the bundled hooks; Codex skips plugin hooks until they are trusted.

pi

See the root README for the install commands. A new pi session or /reload loads the package.

Interactive Setup (Claude Code only)

Install the plugin-setup plugin, then ask Claude to help you set up github-mcp:

/plugin install plugin-setup@github-agent-tools
Help me set up github-mcp

The github-mcp-setting-up skill verifies prerequisites (gh, jq) and optionally creates a config file with a default repository. It uses Claude Code-specific interaction and permission settings, so it is not listed in the Codex marketplace. Codex and pi users configure the plugin manually as described below.

Verification

After restarting Claude Code or starting a new Codex task, verify the MCP servers with /mcp.

You should see gh-tooling listed as a connected server. gh-tooling-write is also registered, but exposes no tools until explicitly enabled.

Configuration

.mcp-gh-tooling.json

The gh-tooling server is configuration-optional - it works without any config file as long as gh is authenticated. A config file adds a default repository so you don't need to pass repo to every tool call.

{
  "repo": "shopware/shopware"
}

With write server enabled and full enforcement:

{
  "repo": "shopware/shopware",
  "enable_write_server": true,
  "enforce_mcp_tools": true,
  "block_api_commands": true,
  "block_api_tool_read": true,
  "block_api_tool_write": true
}

With label semantics:

{
  "repo": "shopware/shopware",
  "enable_write_server": true,
  "labels": {
    "bug": "Confirmed bug in existing functionality",
    "enhancement": "New feature or improvement request",
    "needs-triage": "Issue requires team review and classification"
  }
}

With enforcement disabled:

{
  "repo": "shopware/shopware",
  "enforce_mcp_tools": false
}

Configuration Options

Field Type Default Description
repo string -- Default repository in owner/repo format. Used when repo is not passed to a tool call, and for search_code and search_commits only when owner is not passed either.
enforce_mcp_tools boolean true Blocks high-level gh subcommands (gh pr view, gh issue view, gh run view, gh search, gh pr create, gh label list, gh project view, etc.) and redirects to MCP tools. Set to false to disable all gh hook enforcement.
block_api_commands boolean false When true (and enforce_mcp_tools is also true), additionally blocks gh api calls for endpoints that have a dedicated MCP tool: comment and review edits (PATCH issues/comments/ID, PATCH pulls/comments/ID, PUT pulls/N/reviews/ID), pulls/N/comments, pulls/N/reviews, pulls/N/files, pulls/N/commits, actions/jobs/N/logs, actions/jobs/N, check-runs/N/annotations, commits/SHA, releases. Other gh api calls remain unblocked.
enable_write_server boolean false When true, the write MCP server exposes write tools (PR creation, issue editing, reviews, etc.). When false (default), the write server returns an empty tools list.
block_api_tool_read boolean false When true, the read server's api_read tool blocks requests to endpoints that have a dedicated read MCP tool, suggesting the dedicated tool instead.
block_api_tool_write boolean false When true, the write server's api tool blocks requests to endpoints that have a dedicated write MCP tool, suggesting the dedicated tool instead.
labels object -- Label name to description mapping. Injected into the SessionStart prompt so the model understands label semantics when adding, removing, or suggesting labels.
log_file string -- Additional log file path. Relative paths resolve against the project root.

Configuration Priority

Configuration is loaded in the following priority order:

  1. Environment variable: MCP_GH_TOOLING_CONFIG
  2. Config file discovery (checked in order, last found wins):
    • .mcp-gh-tooling.json (project root, base config)
    • .aiassistant/.mcp-gh-tooling.json (JetBrains AI Assistant)
    • .amazonq/.mcp-gh-tooling.json (Amazon Q Developer)
    • .cline/.mcp-gh-tooling.json (Cline)
    • .cursor/.mcp-gh-tooling.json (Cursor AI)
    • .kiro/.mcp-gh-tooling.json (Kiro)
    • .windsurf/.mcp-gh-tooling.json (Windsurf/Codeium)
    • .zed/.mcp-gh-tooling.json (Zed editor)
    • Host override directories: .claude/.mcp-gh-tooling.json, .codex/.mcp-gh-tooling.json, and .pi/.mcp-gh-tooling.json. The active host's directory has the highest priority, followed by the others in the fixed order .claude/, .codex/, .pi/. The servers take the host from GITHUB_MCP_HOST (pi or codex; any other value or none means Claude Code). The enforcement hooks use the same order, then the project root, and take the first match.

Prerequisites:

Tools Reference

31 read tools + 26 write tools organized by category. See REFERENCE.md for full parameter docs and examples.

Read Server (gh-tooling) -- 31 tools

Category Tools
PR inspection pr_view, pr_diff, pr_list, pr_checks
PR review data pr_comments, pr_reviews, pr_files, pr_commits
Issues issue_view, issue_list, issue_schema
CI runs run_view, run_list, run_logs, workflow_jobs
CI jobs job_view, job_logs, job_annotations
Commits commit_pulls
Search search, search_code, search_repos, search_commits, search_discussions
Repository repo_tree, repo_file
Releases release_list
Labels label_list
Projects project_list, project_view
Raw API api_read (GET only)

Write Server (gh-tooling-write) -- 26 tools

Category Tools
PR lifecycle pr_create, pr_edit, pr_ready, pr_merge, pr_close, pr_reopen
Reviews pr_review_submit, pr_comment, pr_review_reply, comment_edit
Issues issue_create, issue_edit, issue_close, issue_reopen, issue_comment
Issue schema issue_type_set, issue_field_set
Labels label_add, label_remove
Assignees assignee_add, assignee_remove
Sub-issues sub_issue_add, sub_issue_remove
Projects project_item_add, project_status_set
Raw API api (all HTTP methods)

Write Server

The write server is disabled by default. To enable it, set enable_write_server to true in your config:

{
  "enable_write_server": true
}

When disabled, the write server starts but returns an empty tools list, so the agent cannot discover or invoke write tools. This provides a safe default where read operations work out of the box while write operations require explicit opt-in.

After enabling, restart Claude Code or start a new Codex task. /mcp should show tools for gh-tooling-write alongside gh-tooling.

Label Semantics

When a labels map is configured, the label names and descriptions are injected into the SessionStart prompt. This gives the model context about what each label means, enabling it to:

  • Suggest appropriate labels when creating PRs or issues
  • Understand label semantics when filtering or searching
  • Apply labels correctly based on the nature of changes
{
  "labels": {
    "bug": "Confirmed bug in existing functionality",
    "enhancement": "New feature or improvement request",
    "breaking-change": "Change that breaks backward compatibility",
    "needs-triage": "Issue requires team review and classification"
  }
}

The label descriptions appear in the session context only -- they do not modify the labels themselves in GitHub.

MCP Tool Enforcement

This plugin enforces MCP tool usage through three layers:

Layer 1: SessionStart Hook

Injects a directive at the start of every conversation listing all available MCP tools and instructing the agent to use them instead of bash gh commands. The prompt is assembled dynamically from a template, with conditional sections for write tools and label semantics. Maintained in hooks/prompts/mcp-tool-directives.md.

Layer 2: Bash Command Blocking (PreToolUse)

Blocks bash commands that match known gh subcommands and redirects to the corresponding MCP tool. Acts as a safety net when the SessionStart directive is not followed. Covers both read and write commands.

Layer 3: MCP API Tool Blocking (PreToolUse)

Optionally blocks the api_read and api tools when they target endpoints that have dedicated MCP tools. Configured separately via block_api_tool_read and block_api_tool_write. Implemented in hooks/scripts/check-api-tools.sh.

On pi, the extension's tool_call handler runs check-gh-tools.sh and check-api-tools.sh and blocks the call when a script exits 2.

A gate script blocks only by exiting 2. Any other outcome — a crash, a timeout, a missing script — lets the call through, on every host.

All hook layers respect the enforce_mcp_tools setting and are disabled when set to false.

Disabling Enforcement

To allow direct CLI invocations, set enforce_mcp_tools to false in your config:

{
  "enforce_mcp_tools": false
}

Blocked Commands

Read Commands

Bash Command Dedicated Tool
gh pr view pr_view
gh pr diff pr_diff
gh pr list pr_list
gh pr checks pr_checks
gh issue view issue_view
gh issue list issue_list
gh run view run_view / run_logs
gh run list run_list
gh search code search_code
gh search repos search_repos
gh search commits search_commits
gh search (issues/prs) search
gh release list release_list
gh release view release_list
gh label list label_list
gh project list project_list
gh project view project_view

Write Commands

Bash Command Dedicated Tool
gh pr create pr_create
gh pr edit pr_edit
gh pr ready pr_ready
gh pr merge pr_merge
gh pr close pr_close
gh pr reopen pr_reopen
gh pr review pr_review_submit
gh pr comment pr_comment / comment_edit
gh issue create issue_create
gh issue edit issue_edit
gh issue close issue_close
gh issue reopen issue_reopen
gh issue comment issue_comment / comment_edit
gh project item-add project_item_add
gh project item-edit project_status_set

Optional: gh api Bash Command Blocking

With block_api_commands: true, additionally blocks gh api bash calls for endpoints with dedicated MCP tools:

Endpoint Pattern MCP Tool
PATCH issues/comments/ID, PATCH pulls/comments/ID, PUT pulls/N/reviews/ID comment_edit
pulls/N/comments pr_comments
pulls/N/reviews pr_reviews
pulls/N/files pr_files
pulls/N/commits pr_commits
actions/jobs/N/logs job_logs
actions/jobs/N job_view
check-runs/N/annotations job_annotations
commits/SHA/pulls commit_pulls
releases, releases/latest, releases/tags/TAG release_list
git/trees/... repo_tree
contents/... repo_tree / repo_file

Optional: MCP API Tool Blocking

With block_api_tool_read: true and/or block_api_tool_write: true, the api_read and api MCP tools themselves will reject requests to endpoints that have dedicated MCP tools. This prevents the model from bypassing purpose-built tools by using the raw API tool within MCP.

Commands NOT Blocked

  • gh auth login (setup commands)
  • gh run download (no dedicated MCP tool)
  • gh api calls for endpoints without a dedicated tool (when block_api_commands is false)

Integration with Other Plugins

The raw server IDs stay gh-tooling and gh-tooling-write, but each host renders model-visible tool identifiers differently:

Host Read tool example Write tool example
Claude Code mcp__plugin_github-mcp_gh-tooling__pr_view mcp__plugin_github-mcp_gh-tooling-write__pr_create
Codex mcp__gh_tooling__pr_view mcp__gh_tooling_write__pr_create
pi mcp__gh_tooling__pr_view mcp__gh_tooling_write__pr_create

Use the identifiers exposed by the active host rather than copying the other host's spelling.

pi

  • Both servers are registered with exposure: "deferred": pi lists gh-tooling and gh-tooling-write in its system prompt's mcp_servers section, and a tool is undeclared — so the model does not see it as a direct tool call option — until tool_search loads it. A codemode script can call a deferred tool whether or not it has been declared.
  • An MCP result over 20 KB reaches the model with the middle cut out. Pass max_lines, fields, or jq_filter to keep a result under that limit.
  • A gh-tooling entry in pi's mcp.json (~/.pi/agent/mcp.json or a trusted project's .pi/mcp.json) overrides the extension's registration — this is how to change the exposure pi gives the server. The entry needs its own command, since it does not inherit the extension's, and must set env: {"GITHUB_MCP_HOST": "pi"}; without it the server uses the Claude Code config order while the hooks use pi's.
  • The servers need bash 4.1+ and jq 1.7+ on the PATH pi runs with.
  • pi support covers macOS and Linux.

Troubleshooting

MCP Server Not Starting

  1. Restart Claude Code or start a new Codex task, or start a new pi session or run /reload, after plugin installation
  2. Check /mcp for connection status; under pi, gh-tooling and gh-tooling-write show the extension as their source
  3. In Codex, open /hooks and confirm the plugin hooks are trusted if enforcement is missing
  4. Verify jq is installed: which jq
  5. Verify gh is installed and authenticated: gh auth status

gh Not Authenticated

  1. Run gh auth login and follow the prompts
  2. Verify with gh auth status

jq_filter Rejected Without fields

Seven read tools need fields before a filter has JSON to run on, and issue_view also accepts with_field_values in its place. Pass one of them alongside the filter -- see REFERENCE.md §Shared Tool Parameters.

Write Server Not Showing Tools

  1. Verify enable_write_server is set to true in .mcp-gh-tooling.json
  2. Restart Claude Code or start a new Codex task after changing the config
  3. Check /mcp -- gh-tooling-write should be listed with tools

Dependencies

  • bash (4.1+) — the MCP servers refuse to start below this and say so on stderr. macOS ships 3.2 as /bin/bash and no install replaces it, so a Mac needs a newer bash on the PATH the host launches the server with.
  • jq (1.7+) — below this, tool argument validation is skipped, so the servers refuse to start rather than validate less than they claim.
  • gh CLI (GitHub CLI, authenticated)

License

MIT