# ghcli-mcp-connector [Health: Active]
**Category:** ๐ Version Control
**Repository:** https://github.com/FerhatDundar/ghcli-mcp-connector
**GitHub Stars:** 0
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/ghcli-mcp-connector
## Description
MCP server for the GitHub CLI (gh). Read-only by default; single Go binary.
## Claude Desktop Quick Installation
Heuristic fallback โ verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"ghcli-mcp-connector": {
"command": "npx",
"args": ["-y","ghcli-mcp-connector"]
}
}
```
## Documentation & README
# ๐ ghcli-mcp-connector
**Talk to the GitHub CLI (`gh`) from an MCP-speaking agent.**
[](https://github.com/FerhatDundar/ghcli-mcp-connector/actions/workflows/ci.yml)
[](https://github.com/FerhatDundar/ghcli-mcp-connector/actions/workflows/codeql.yml)
[](https://github.com/FerhatDundar/ghcli-mcp-connector/releases/latest)
[](https://registry.modelcontextprotocol.io/?q=ghcli-mcp-connector)
[](https://go.dev/)
[](LICENSE)
[](https://modelcontextprotocol.io/)
[](https://www.conventionalcommits.org/)
[](CONTRIBUTING.md)
---
A single static Go binary that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)
and lets an agent run GitHub CLI commands: any `gh `
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](https://github.com/FerhatDundar/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. 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 [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](https://github.com/FerhatDundar/ghcli-mcp-connector/releases/latest) โ
download `ghcli-mcp-connector-plugin---.zip`, unzip it,
and point Cowork/Claude at the `plugin/` folder inside (see step 4 of
[SETUP.md](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](Makefile) for every shortcut
(`test`, `vet`, `fmt`, `lint`, `tidy`).
Full walkthrough โ including wiring this up as a Claude/Cowork plugin โ is
in **[SETUP.md](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](https://golangci-lint.run/)** (govet, staticcheck, errcheck, gosec, and more)
- โ
**[govulncheck](https://go.dev/blog/vuln)** โ no known vulnerabilities in the dependency graph
- โ
**[CodeQL](https://codeql.github.com/)** static security analysis on every push
- โ
**End-to-end verified** against real GitHub during development โ not mocks
- โ
**[Dependabot](.github/dependabot.yml)** keeps Go modules and Actions current
All of it runs in [CI](.github/workflows/ci.yml) on every push and PR.
## ๐ท๏ธ Releases & versioning
Versions follow [semver](https://semver.org/) and are cut automatically by
[release-please](https://github.com/googleapis/release-please) from
[Conventional Commits](https://www.conventionalcommits.org/) 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](CHANGELOG.md). Merging that PR:
1. tags the release and publishes it on GitHub
2. builds and attaches zipped, ready-to-install plugin bundles for
linux/darwin/windows ร amd64/arm64
3. regenerates `server.json` from those exact assets (fresh version +
SHA-256 hashes) and publishes it to the
[official MCP Registry](https://registry.modelcontextprotocol.io/) via
`mcp-publisher`, authenticated with GitHub OIDC โ no stored secrets
See [.github/workflows/release-please.yml](.github/workflows/release-please.yml)
and [.github/workflows/publish-mcp-registry.yml](.github/workflows/publish-mcp-registry.yml)
(also runnable by hand for an existing tag via `workflow_dispatch`).
## ๐ Layout
```
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](CONTRIBUTING.md)**
for the full guide (setup, coding conventions, how to add a new tool) and
the **[Code of Conduct](CODE_OF_CONDUCT.md)**.
`main` is protected: every change, including the maintainer's, lands via
pull request with CI green. PR titles must follow
[Conventional Commits](https://www.conventionalcommits.org/) โ that's what
drives the automatic versioning above.
Found a security issue? Please follow **[SECURITY.md](SECURITY.md)**
instead of opening a public issue.
## ๐ License
[MIT](LICENSE) ยฉ FerhatDundar