{
"markdown": "\n\n# ๐ ghcli-mcp-connector\n\n**Talk to the GitHub CLI (`gh`) from an MCP-speaking agent.**\n\n[](https://github.com/FerhatDundar/ghcli-mcp-connector/actions/workflows/ci.yml)\n[](https://github.com/FerhatDundar/ghcli-mcp-connector/actions/workflows/codeql.yml)\n[](https://github.com/FerhatDundar/ghcli-mcp-connector/releases/latest)\n[](https://registry.modelcontextprotocol.io/?q=ghcli-mcp-connector)\n[](https://go.dev/)\n[](LICENSE)\n[](https://modelcontextprotocol.io/)\n[](https://www.conventionalcommits.org/)\n[](CONTRIBUTING.md)\n\n
\n\n---\n\nA single static Go binary that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)\nand lets an agent run GitHub CLI commands: any `gh `\ninvocation โ `repo`, `issue`, `pr`, `release`, `gist`, `workflow`, `run`,\n`secret`, `variable`, `project`, `ruleset`, `codespace`, `extension`, `api`,\nand more โ with a read-only-by-default safety gate on anything that\nchanges state on GitHub.\n\nNo Python, no `uv`, no runtime dependency to install โ just a binary and\nan `.mcp.json`. It shells out to the `gh` binary already installed and\nauthenticated on the host (`gh auth login`, stored in the OS keychain, or\n`GH_TOKEN`/`GITHUB_TOKEN`) instead of reimplementing a GitHub API client,\nso it gets the full breadth of the CLI for free rather than a hand-curated\nsubset of endpoints.\n\n> **Note:** this is a sibling of [github-mcp-connector](https://github.com/FerhatDundar/github-mcp-connector),\n> not a replacement. That one talks to the GitHub REST API directly via\n> `google/go-github` with a curated set of 18 tools. This one shells out to\n> the `gh` CLI itself โ same trade-off as `aws-mcp-connector` vs. a\n> hand-written AWS SDK client: broader coverage (gh extensions, gh's own\n> filters/formatting, workflow/run/codespace/project/ruleset management)\n> through a single `ghcli_exec` escape hatch, instead of a curated surface.\n\n## โจ Why this exists\n\n> An agent that only has a narrow, hand-picked set of GitHub tools hits a\n> wall the moment you need something outside that set. This connector\n> instead wraps the `gh` CLI itself, so an agent can run `gh pr list`,\n> `gh issue create`, `gh workflow run`, `gh api repos/owner/repo/issues` โ\n> anything the CLI can do โ without waiting on a new tool to be written\n> for it. State-changing commands are blocked by default and require both\n> a server-level opt-in and a per-call `confirm=true`, so exploring/\n> reading is safe out of the box.\n\n## ๐งฐ Tools\n\n| Tool | What it does | Write? |\n|---|---|:---:|\n| `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) |\n| `ghcli_help` | Show `gh [subcommand] --help` text โ always safe, use it to check exact syntax before calling `ghcli_exec`. | |\n| `ghcli_whoami` | Show the GitHub identity (login, name, profile URL) the configured auth resolves to. | |\n\nEvery tool accepts an optional `response_format`: `markdown` (default,\nreadable for a chat UI) or `json` (for programmatic use).\n\nThis server has no working-directory git repo, so repo-scoped commands\nneed an explicit `-R`/`--repo owner/repo` rather than relying on gh's\ncwd-based repo detection.\n\n## ๐ Quickstart\n\n**Fastest path:** grab a prebuilt bundle from the [latest release](https://github.com/FerhatDundar/ghcli-mcp-connector/releases/latest) โ\ndownload `ghcli-mcp-connector-plugin---.zip`, unzip it,\nand point Cowork/Claude at the `plugin/` folder inside (see step 4 of\n[SETUP.md](SETUP.md)). No Go toolchain required.\n\n**From source:**\n\n```bash\n# 1. Build\ncd go-server\ngo mod tidy\ngo build -o ghcli-connector-server .\ncp ghcli-connector-server ../plugin/servers/go/\n\n# 2. Set up auth โ needs the gh CLI itself installed and logged in\n# (gh auth login) โ see SETUP.md\ngh auth status # should succeed before running the server\n\n# 3. Run\n./go-server/ghcli-connector-server # serves MCP over stdio\n```\n\nOr `make build` โ see the [Makefile](Makefile) for every shortcut\n(`test`, `vet`, `fmt`, `lint`, `tidy`).\n\nFull walkthrough โ including wiring this up as a Claude/Cowork plugin โ is\nin **[SETUP.md](SETUP.md)**.\n\n## ๐ Configuration\n\nEverything is environment variables, passed through by the plugin's\n`.mcp.json`:\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `GH_TOKEN` / `GITHUB_TOKEN` | gh CLI's own token env vars. Leave unset to use whatever `gh auth login` already configured. | unset (keychain auth) |\n| `GH_HOST` | Target a GitHub Enterprise hostname instead of github.com. | unset (github.com) |\n| `GHCLI_MCP_ALLOW_WRITE` | `\"true\"` to permit state-changing commands at all (still needs `confirm=true` per call). | `false` (read-only) |\n| `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) |\n| `GHCLI_MCP_CLI_PATH` | Path to the `gh` binary. | `gh` resolved via `PATH` |\n\n## ๐งช Quality bar\n\nThis isn't a toy script โ it's got the same checks you'd expect from a\nproduction Go service:\n\n- โ
**Unit tests** for every input-validation path (`go test ./...`)\n- โ
**`go vet`** + **`gofmt`** clean\n- โ
**[golangci-lint](https://golangci-lint.run/)** (govet, staticcheck, errcheck, gosec, and more)\n- โ
**[govulncheck](https://go.dev/blog/vuln)** โ no known vulnerabilities in the dependency graph\n- โ
**[CodeQL](https://codeql.github.com/)** static security analysis on every push\n- โ
**End-to-end verified** against real GitHub during development โ not mocks\n- โ
**[Dependabot](.github/dependabot.yml)** keeps Go modules and Actions current\n\nAll of it runs in [CI](.github/workflows/ci.yml) on every push and PR.\n\n## ๐ท๏ธ Releases & versioning\n\nVersions follow [semver](https://semver.org/) and are cut automatically by\n[release-please](https://github.com/googleapis/release-please) from\n[Conventional Commits](https://www.conventionalcommits.org/) on `main`:\n\n- `fix: ...` โ patch (`v0.1.0` โ `v0.1.1`)\n- `feat: ...` โ minor (`v0.1.1` โ `v0.2.0`)\n- `feat!: ...` / `BREAKING CHANGE:` footer โ major (`v0.2.0` โ `v1.0.0`)\n\nEvery merged PR updates a standing **\"chore(main): release vX.Y.Z\"** PR\nwith an auto-generated [CHANGELOG.md](CHANGELOG.md). Merging that PR:\n\n1. tags the release and publishes it on GitHub\n2. builds and attaches zipped, ready-to-install plugin bundles for\n linux/darwin/windows ร amd64/arm64\n3. regenerates `server.json` from those exact assets (fresh version +\n SHA-256 hashes) and publishes it to the\n [official MCP Registry](https://registry.modelcontextprotocol.io/) via\n `mcp-publisher`, authenticated with GitHub OIDC โ no stored secrets\n\nSee [.github/workflows/release-please.yml](.github/workflows/release-please.yml)\nand [.github/workflows/publish-mcp-registry.yml](.github/workflows/publish-mcp-registry.yml)\n(also runnable by hand for an existing tag via `workflow_dispatch`).\n\n## ๐ Layout\n\n```\nghcli-mcp-connector/\nโโโ README.md โ you are here\nโโโ SETUP.md โ step-by-step setup guide\nโโโ CONTRIBUTING.md โ how to contribute\nโโโ CODE_OF_CONDUCT.md\nโโโ SECURITY.md โ vulnerability reporting\nโโโ CODEOWNERS\nโโโ LICENSE โ MIT\nโโโ Makefile โ build / test / lint shortcuts\nโโโ .golangci.yml โ lint rules\nโโโ release-please-config.json โ semver/changelog automation config\nโโโ .release-please-manifest.json\nโโโ server.json โ MCP Registry manifest (regenerated fresh per release by CI)\nโโโ scripts/\nโ โโโ render-server-json.sh โ rebuilds server.json from a release's zip assets\nโโโ .github/\nโ โโโ workflows/\nโ โ โโโ ci.yml โ build, vet, test, lint, govulncheck\nโ โ โโโ codeql.yml โ security scanning\nโ โ โโโ pr-title.yml โ Conventional Commits PR title check\nโ โ โโโ release-please.yml โ version PRs, tagging, GitHub releases\nโ โ โโโ publish-mcp-registry.yml โ publishes server.json to the MCP Registry\nโ โ โโโ rebuild-release-assets.yml โ manual re-attach fallback\nโ โโโ ISSUE_TEMPLATE/\nโ โโโ PULL_REQUEST_TEMPLATE.md\nโ โโโ dependabot.yml\nโโโ go-server/ โ the MCP server source\nโ โโโ main.go\nโ โโโ main_test.go\nโ โโโ go.mod / go.sum\nโ โโโ README.md\nโโโ plugin/ โ installable Cowork/Claude plugin\n โโโ .claude-plugin/plugin.json\n โโโ .mcp.json โ holds credentials locally โ never commit real ones\n โโโ skills/ghcli-mcp/SKILL.md โ teaches Claude when/how to use the tools\n โโโ servers/go/ โ compiled binary goes here\n```\n\n## ๐ค Contributing\n\nPRs and issues are very welcome โ see **[CONTRIBUTING.md](CONTRIBUTING.md)**\nfor the full guide (setup, coding conventions, how to add a new tool) and\nthe **[Code of Conduct](CODE_OF_CONDUCT.md)**.\n\n`main` is protected: every change, including the maintainer's, lands via\npull request with CI green. PR titles must follow\n[Conventional Commits](https://www.conventionalcommits.org/) โ that's what\ndrives the automatic versioning above.\n\nFound a security issue? Please follow **[SECURITY.md](SECURITY.md)**\ninstead of opening a public issue.\n\n## ๐ License\n\n[MIT](LICENSE) ยฉ FerhatDundar\n",
"bytes": 10326,
"sha": "806356295546873e6fcf2c722c62cef41efa3b796417324bbfe260a249632a96",
"repo_slug": "ferhatdundar/ghcli-mcp-connector",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ferhatdundar_ghcli_mcp_connect_4d1f2ad9/readme"
}