onprem-gh-cli-mcp-server

オンプレPCにインストールされたGitHub CLI (gh)を、MCPクライアントから安全に利用するためのstdio MCPサーバーです。APIの認証情報をMCPクライアントへ渡さず、ローカルのgh auth認証を利用します。

[!IMPORTANT] 現在はPhase 2aです。読み取り操作に加え、型付きツールによるIssueの作成・更新・コメントを提供します。Repository削除、PRマージ、Secret変更などの破壊・管理操作は未実装です。

提供ツール

読み取り

• get_auth_status: トークンを表示せず認証状態を確認
• list_organizations: 認証ユーザーから見える所属Organization一覧
• list_repositories: Repository一覧
• list_issues: Issue一覧
• list_pull_requests: Pull Request一覧
• list_workflow_runs: GitHub Actions実行一覧
• run_gh: 許可された読み取り専用ghコマンド

Issue書き込み

• create_issue: Issueを作成
• update_issue: Issueのタイトル、本文、open/closed状態を更新
• comment_issue: Issueへコメントを追加

Issue本文とコメントはコマンドライン引数へ載せず、gh api --input -の標準入力としてJSONで渡します。書き込み操作は型付きツールだけに限定し、run_ghは読み取り専用のままです。

必要環境

• Node.js 20以上
• GitHub CLI
• 事前にgh auth loginが完了していること

Issue書き込みには、対象RepositoryへのIssue書き込み権限を持つGitHub CLI認証が必要です。

起動

公開後は、レビュー済みバージョンを固定して起動します。

npx.cmd --yes --prefer-offline @ma-nakaya/onprem-gh-cli-mcp@0.1.0

ローカル開発時:

npm install
npm run build
node dist/cli.js

設定

変数	既定値	説明
GH_MCP_GH_PATH	Windows: gh.exe	GitHub CLIの固定パス
GH_MCP_ALLOWED_HOSTS	github.com	許可ホスト（カンマ区切り）
GH_MCP_ALLOWED_OWNERS	制限なし	許可Owner/Organization
GH_MCP_ALLOWED_REPOSITORIES	制限なし	許可Repository (owner/name)
GH_MCP_TIMEOUT_MS	30000	コマンドのタイムアウト
GH_MCP_MAX_OUTPUT_BYTES	1000000	最大出力サイズ
GH_MCP_AUDIT_LOG_PATH	OS別のユーザー領域	JSONL監査ログの固定パス

監査ログの既定パス:

• Windows: %LOCALAPPDATA%\onprem-gh-cli-mcp\audit.jsonl
• Linux/macOS: $XDG_STATE_HOME/onprem-gh-cli-mcp/audit.jsonl、未設定時は~/.local/state/onprem-gh-cli-mcp/audit.jsonl

本番利用ではGH_MCP_ALLOWED_OWNERSまたはGH_MCP_ALLOWED_REPOSITORIESを必ず設定してください。監査ログパスはMCPツール入力から変更できず、環境変数または既定値で固定されます。

監査ログ

Issue書き込みの開始と完了をJSON Lines形式で記録します。

記録対象:

• timestamp
• tool
• hostname
• repository
• issueNumber（対象が存在する場合）
• outcome (started / succeeded / failed)
• durationMs

次の情報は記録しません。

• Issueタイトル
• Issue本文
• コメント本文
• Token、Secret
• GitHub CLIの標準出力・標準エラー全文

開始レコードを書けない場合、書き込み操作は実行しません。完了レコードの書き込みに失敗した場合は、MCPレスポンスのaudit.completedがfalseになります。

Secure MCP Tunnel設定例

mcp:
  transport: stdio
  command: npx.cmd
  args:
    - --yes
    - --prefer-offline
    - "@ma-nakaya/onprem-gh-cli-mcp@0.1.0"

セキュリティ

• shell: falseでgh.exeを直接起動
• gh auth tokenと--show-tokenを拒否
• run_ghでは書き込み系サブコマンドを拒否
• 書き込み操作は入力スキーマを持つ専用ツールだけに限定
• Issue本文とコメントは標準入力で渡し、プロセス引数へ載せない
• 子プロセスへ渡す環境変数を限定
• GitHub Tokenらしい出力をマスク
• 実行時間と出力量を制限
• Repository/Owner/Hostの許可リストに対応
• 監査ログへIssue本文、コメント本文、Token、Secretを保存しない

現在の実装範囲

• Phase 1: 基盤、読み取り、Organization一覧、許可リスト、CI、実機確認
• Phase 2a: Issue作成・更新・コメント、JSONL監査ログ
• 未実装: PR・Release作成、Workflow Dispatch、Project、削除、PRマージ、Secret、二段階承認

開発

npm install
npm run check
npm test
npm run build

License

MIT