🔌 ghcli-mcp-connector

Talk to the GitHub CLI (gh) from an MCP-speaking agent.

A single static Go binary that speaks the Model Context Protocol and lets an agent run GitHub CLI commands: any gh <command> <subcommand> invocation — repo, issue, pr, release, gist, workflow, run, secret, variable, project, ruleset, codespace, extension, api, and more — with a read-only-by-default safety gate on anything that changes state on GitHub.

No Python, no uv, no runtime dependency to install — just a binary and an .mcp.json. It shells out to the gh binary already installed and authenticated on the host (gh auth login, stored in the OS keychain, or GH_TOKEN/GITHUB_TOKEN) instead of reimplementing a GitHub API client, so it gets the full breadth of the CLI for free rather than a hand-curated subset of endpoints.

Note: this is a sibling of github-mcp-connector, not a replacement. That one talks to the GitHub REST API directly via google/go-github with a curated set of 18 tools. This one shells out to the gh CLI itself — same trade-off as aws-mcp-connector vs. a hand-written AWS SDK client: broader coverage (gh extensions, gh's own filters/formatting, workflow/run/codespace/project/ruleset management) through a single ghcli_exec escape hatch, instead of a curated surface.

✨ Why this exists

An agent that only has a narrow, hand-picked set of GitHub tools hits a wall the moment you need something outside that set. This connector instead wraps the gh CLI itself, so an agent can run gh pr list, gh issue create, gh workflow run, gh api repos/owner/repo/issues — anything the CLI can do — without waiting on a new tool to be written for it. State-changing commands are blocked by default and require both a server-level opt-in and a per-call confirm=true, so exploring/ reading is safe out of the box.

🧰 Tools

Tool	What it does	Write?
`ghcli_exec`	Run any `gh <command> <subcommand> ...` command. Read-only by default — commands that change GitHub state need `GHCLI_MCP_ALLOW_WRITE=true` on the server and `confirm=true` on the call.	✅ (gated)
`ghcli_help`	Show `gh <command> [subcommand] --help` text — always safe, use it to check exact syntax before calling `ghcli_exec`.
`ghcli_whoami`	Show the GitHub identity (login, name, profile URL) the configured auth resolves to.

Every tool accepts an optional response_format: markdown (default, readable for a chat UI) or json (for programmatic use).

This server has no working-directory git repo, so repo-scoped commands need an explicit -R/--repo owner/repo rather than relying on gh's cwd-based repo detection.

🚀 Quickstart

Fastest path: grab a prebuilt bundle from the latest release — download ghcli-mcp-connector-plugin-<version>-<os>-<arch>.zip, unzip it, and point Cowork/Claude at the plugin/ folder inside (see step 4 of SETUP.md). No Go toolchain required.

From source:

bash

# 1. Build
cd go-server
go mod tidy
go build -o ghcli-connector-server .
cp ghcli-connector-server ../plugin/servers/go/

# 2. Set up auth — needs the gh CLI itself installed and logged in
#    (gh auth login) — see SETUP.md
gh auth status   # should succeed before running the server

# 3. Run
./go-server/ghcli-connector-server   # serves MCP over stdio

Or make build — see the Makefile for every shortcut (test, vet, fmt, lint, tidy).

Full walkthrough — including wiring this up as a Claude/Cowork plugin — is in SETUP.md.

🔐 Configuration

Everything is environment variables, passed through by the plugin's .mcp.json:

Variable	Purpose	Default
`GH_TOKEN` / `GITHUB_TOKEN`	gh CLI's own token env vars. Leave unset to use whatever `gh auth login` already configured.	unset (keychain auth)
`GH_HOST`	Target a GitHub Enterprise hostname instead of github.com.	unset (github.com)
`GHCLI_MCP_ALLOW_WRITE`	`"true"` to permit state-changing commands at all (still needs `confirm=true` per call).	`false` (read-only)
`GHCLI_MCP_ALLOWED_REPOS`	Comma-separated allowlist of `owner/repo` values, e.g. `"me/proj,me/other"`. Only enforced when a call passes an explicit `-R`/`--repo` flag.	unset (unrestricted)
`GHCLI_MCP_CLI_PATH`	Path to the `gh` binary.	`gh` resolved via `PATH`

🧪 Quality bar

This isn't a toy script — it's got the same checks you'd expect from a production Go service:

✅ Unit tests for every input-validation path (go test ./...)
✅ go vet + gofmt clean
✅ golangci-lint (govet, staticcheck, errcheck, gosec, and more)
✅ govulncheck — no known vulnerabilities in the dependency graph
✅ CodeQL static security analysis on every push
✅ End-to-end verified against real GitHub during development — not mocks
✅ Dependabot keeps Go modules and Actions current

All of it runs in CI on every push and PR.

🏷️ Releases & versioning

Versions follow semver and are cut automatically by release-please from Conventional Commits on main:

fix: ... → patch (v0.1.0 → v0.1.1)
feat: ... → minor (v0.1.1 → v0.2.0)
feat!: ... / BREAKING CHANGE: footer → major (v0.2.0 → v1.0.0)

Every merged PR updates a standing "chore(main): release vX.Y.Z" PR with an auto-generated CHANGELOG.md. Merging that PR:

tags the release and publishes it on GitHub
builds and attaches zipped, ready-to-install plugin bundles for linux/darwin/windows × amd64/arm64
regenerates server.json from those exact assets (fresh version + SHA-256 hashes) and publishes it to the official MCP Registry via mcp-publisher, authenticated with GitHub OIDC — no stored secrets

See .github/workflows/release-please.yml and .github/workflows/publish-mcp-registry.yml (also runnable by hand for an existing tag via workflow_dispatch).

📁 Layout

Code

ghcli-mcp-connector/
├── README.md                  ← you are here
├── SETUP.md                   ← step-by-step setup guide
├── CONTRIBUTING.md             ← how to contribute
├── CODE_OF_CONDUCT.md
├── SECURITY.md                 ← vulnerability reporting
├── CODEOWNERS
├── LICENSE                     ← MIT
├── Makefile                    ← build / test / lint shortcuts
├── .golangci.yml                ← lint rules
├── release-please-config.json  ← semver/changelog automation config
├── .release-please-manifest.json
├── server.json                  ← MCP Registry manifest (regenerated fresh per release by CI)
├── scripts/
│   └── render-server-json.sh    ← rebuilds server.json from a release's zip assets
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                     ← build, vet, test, lint, govulncheck
│   │   ├── codeql.yml                 ← security scanning
│   │   ├── pr-title.yml               ← Conventional Commits PR title check
│   │   ├── release-please.yml         ← version PRs, tagging, GitHub releases
│   │   ├── publish-mcp-registry.yml   ← publishes server.json to the MCP Registry
│   │   └── rebuild-release-assets.yml ← manual re-attach fallback
│   ├── ISSUE_TEMPLATE/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml
├── go-server/                  ← the MCP server source
│   ├── main.go
│   ├── main_test.go
│   ├── go.mod / go.sum
│   └── README.md
└── plugin/                     ← installable Cowork/Claude plugin
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                ← holds credentials locally — never commit real ones
    ├── skills/ghcli-mcp/SKILL.md ← teaches Claude when/how to use the tools
    └── servers/go/              ← compiled binary goes here

🤝 Contributing

PRs and issues are very welcome — see CONTRIBUTING.md for the full guide (setup, coding conventions, how to add a new tool) and the Code of Conduct.

main is protected: every change, including the maintainer's, lands via pull request with CI green. PR titles must follow Conventional Commits — that's what drives the automatic versioning above.

Found a security issue? Please follow SECURITY.md instead of opening a public issue.

Ghcli MCP Connector README