ghcli-mcp-connector

---

Model Context Protocol に対応した単一の静的 Go バイナリです。エージェントから GitHub CLI コマンドを実行できます。repo、issue、pr、release、gist、workflow、run、secret、variable、project、ruleset、codespace、extension、api など、あらゆる gh <command> <subcommand> の呼び出しに対応し、GitHub の状態を変更する操作はデフォルトで読み取り専用の安全策によって制限されます。

Python も uv も、インストールが必要なランタイム依存関係も不要です。必要なのはバイナリと .mcp.json だけです。ホストにすでにインストールされ、認証済みの gh バイナリ（gh auth login によるログイン、OS のキーチェーンへの保存、または GH_TOKEN／GITHUB_TOKEN）を呼び出します。GitHub API クライアントを再実装することなく、手作業で選定した一部のエンドポイントに限定されず、CLI の機能をすべて活用できます。

注記： これは github-mcp-connector と同系列のプロジェクトであり、その代替ではありません。github-mcp-connector は google/go-github を使って GitHub REST API を直接呼び出し、厳選された 18 個のツールを提供します。一方、こちらは gh CLI 自体を呼び出します。手書きの AWS SDK クライアントに対する aws-mcp-connector と同様のトレードオフで、厳選された機能に限定する代わりに、単一の ghcli_exec エスケープハッチから、より幅広い機能（gh 拡張機能、gh 独自のフィルターや書式設定、workflow／run／codespace／project／ruleset の管理）を利用できます。

✨ このプロジェクトの目的

厳選された限られた GitHub ツールしか持たないエージェントは、その範囲外の操作が必要になると行き詰まります。このコネクターは gh CLI 自体をラップするため、エージェントは新しいツールの実装を待たずに、gh pr list、gh issue create、gh workflow run、gh api repos/owner/repo/issues など、CLI で実行できるあらゆる操作を行えます。状態を変更するコマンドはデフォルトでブロックされ、サーバーレベルでのオプトインと、呼び出しごとの confirm=true の両方が必要です。そのため、すぐに安全に調査や読み取りを始められます。

🧰 ツール

ツール	機能	書き込み？
ghcli_exec	任意の gh <command> <subcommand> ... コマンドを実行します。デフォルトでは読み取り専用です。GitHub の状態を変更するコマンドには、サーバーで GHCLI_MCP_ALLOW_WRITE=true を設定し、呼び出し時に confirm=true を指定する必要があります。	✅（制限あり）
ghcli_help	gh <command> [subcommand] --help のテキストを表示します。常に安全に使用できるため、ghcli_exec を呼び出す前に正確な構文を確認するために使用してください。
ghcli_whoami	設定された認証情報で解決される GitHub の ID（ログイン名、名前、プロフィール URL）を表示します。

すべてのツールは、任意の response_format を受け取ります。チャット UI で読みやすい markdown（デフォルト）または、プログラムでの利用向けの json です。

このサーバーには有効な作業ディレクトリの git リポジトリがないため、リポジトリを対象とするコマンドでは、gh のカレントディレクトリに基づくリポジトリ検出に頼らず、明示的に -R／--repo owner/repo を指定する必要があります。

🚀 クイックスタート

最短の方法：最新リリースからビルド済みバンドルをダウンロードします。ghcli-mcp-connector-plugin-<version>-<os>-<arch>.zip をダウンロードして解凍し、その中にある plugin/ フォルダーを Cowork／Claude に指定します（SETUP.md の手順 4 を参照してください）。Go ツールチェーンは不要です。

ソースから：

# 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

または make build を実行します。すべてのショートカット（test、vet、fmt、lint、tidy）については Makefile を参照してください。

Claude／Cowork プラグインとして接続する方法も含めた詳しい手順は、SETUP.md を参照してください。

🔐 設定

すべて環境変数で設定し、プラグインの .mcp.json から渡します。

変数	用途	デフォルト
GH_TOKEN / GITHUB_TOKEN	gh CLI 独自のトークン環境変数です。gh auth login で設定済みの認証情報を使用する場合は、設定しないでください。	未設定（キーチェーン認証）
GH_HOST	github.com の代わりに、GitHub Enterprise のホスト名を指定します。	未設定（github.com）
GHCLI_MCP_ALLOW_WRITE	状態を変更するコマンドを許可するには "true" を指定します（呼び出しごとに confirm=true も必要です）。	false（読み取り専用）
GHCLI_MCP_ALLOWED_REPOS	owner/repo 値をカンマ区切りで指定する許可リストです。例："me/proj,me/other"。明示的に -R／--repo フラグを指定した呼び出しにのみ適用されます。	未設定（制限なし）
GHCLI_MCP_CLI_PATH	gh バイナリへのパスです。	PATH 経由で解決される gh

🧪 品質基準

これはおもちゃのようなスクリプトではありません。本番環境の Go サービスに求められるものと同じチェックを備えています。

• ✅ すべての入力検証パスに対するユニットテスト（go test ./...）
• ✅ go vet と gofmt のチェックに合格
• ✅ golangci-lint（govet、staticcheck、errcheck、gosec など）
• ✅ govulncheck — 依存関係グラフに既知の脆弱性がありません
• ✅ CodeQL による、プッシュごとの静的セキュリティ分析
• ✅ 開発中に実際の GitHub を使ってエンドツーエンドで検証済み — モックではありません
• ✅ Dependabot が Go モジュールと Actions を最新の状態に保ちます

これらはすべて、プッシュおよび PR ごとに CI で実行されます。

🏷️ リリースとバージョン管理

バージョンはセマンティックバージョニングに準拠しており、main の Conventional Commits に基づいて、release-please により自動的に作成されます。

• fix: ... → パッチ（v0.1.0 → v0.1.1）
• feat: ... → マイナー（v0.1.1 → v0.2.0）
• feat!: ... ／ BREAKING CHANGE: フッター → メジャー（v0.2.0 → v1.0.0）

マージされた PR ごとに、自動生成された CHANGELOG.md を含む、常設の "chore(main): release vX.Y.Z" PR が更新されます。この PR をマージすると、次の処理が行われます。

1. リリースにタグを付け、GitHub で公開します
2. linux/darwin/windows × amd64/arm64 向けの、すぐにインストールできるプラグインバンドルを ZIP 形式でビルドして添付します
3. それらのアセットをもとに server.json を再生成し（最新バージョンと SHA-256 ハッシュを反映）、GitHub OIDC で認証して mcp-publisher 経由で公式 MCP Registry に公開します。シークレットの保存は不要です

.github/workflows/release-please.yml と .github/workflows/publish-mcp-registry.yml を参照してください（既存のタグを指定して workflow_dispatch から手動で実行することもできます）。

📁 ディレクトリ構成

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

🤝 貢献

PR や Issue は大歓迎です。詳しいガイド（セットアップ、コーディング規約、新しいツールの追加方法）は CONTRIBUTING.md を、行動規範 もご確認ください。

main は保護されています。メンテナーによる変更も含め、すべての変更は CI が成功した状態でプルリクエスト経由で反映されます。PR のタイトルは Conventional Commits に準拠する必要があります。これは上記の自動バージョン管理に使用されます。

セキュリティ上の問題を発見した場合は、公開 Issue を作成せず、SECURITY.md に従ってください。

📄 ライセンス

MIT © FerhatDundar