grok-mcp

grok-mcp

Claude Code、Cursor、Cline、OpenClaw、その他あらゆる MCP ホスト内で、Grok をピアコードレビュー担当者および厳密なセカンドオピニオンの相談相手として使えます。xAI の API に直接接続する方法（XAI_API_KEY を設定するだけで、インストール不要）と、公式の Grok CLI を使う方法があります。

grok-mcp（npm：grok-cli-mcp）は、Grok 用の Model Context Protocol サーバーです。プライマリエージェント（Claude、Cursor など）に4つのツールを提供し、セッションを離れることなく、Grok に委任して質の高いセカンドオピニオンや厳密な検証を得られます。v0.3.0 以降は xAI の API に直接接続するため、grok バイナリは不要です。また、OAuth を使うユーザー向けに CLI にも引き続き対応しています。

• grok_review — 次元ごとのスコアを含む、構造化された差分レビュー
• grok_challenge — バグ、競合状態、エッジケース、セキュリティ上の問題を詳細に分析
• grok_consult — 複数ターンの相談（履歴は呼び出し元が管理）
• grok_chat — 一問一答

English | 繁體中文

grok-mcp を使う理由

多くの「Grok MCP」パッケージは、Claude が Grok を利用できるように、Grok のチャット、検索、画像機能を公開しています。grok-mcp では、メインのコーディングエージェント（Claude/Cursor/…）が、自らの作業についてGrok に厳密なセカンドオピニオンを求めることができます。異なるモデルによる詳細なレビューは、単一モデルのループでは見逃されることの多い問題を発見できます。

利用できる機能

4つのツールは、すべてステートレスで、標準出力のみを使用します。

ツール	用途
grok_chat	一問一答のプロンプト → Grok の応答
grok_review	統合差分を渡す（または git diff main...HEAD を自動取得する）と、次元ごとのコードレビューを受け取れます
grok_consult	複数ターンのやり取りのため、メッセージ履歴を再生します。スレッドは呼び出し元が管理します
grok_challenge	厳密な分析：Grok にバグ、競合状態、エッジケース、セキュリティ上の問題を洗い出すよう依頼します

前提条件

• Node.js ≥ 18
• バックエンド（サーバーが自動的に選択します。バックエンドを参照）：
  • API モード（推奨、インストール不要）： console.x.ai で取得した XAI_API_KEY。サーバーは xAI の HTTP API に直接接続するため、追加のバイナリは不要です。
  • CLI モード： XAI_API_KEY が設定されていない場合に使用される、インストール済みの Grok CLI：

    curl -fsSL https://x.ai/cli/install.sh | bash
    

    続いて、ブラウザー OAuth で認証します（対話形式で一度 grok を実行してください）。詳しくは以下の認証を参照してください。

インストール

npm install -g grok-cli-mcp
# or use npx — no install needed
npx grok-cli-mcp

npm パッケージ名が grok-mcp ではなく grok-cli-mcp なのはなぜですか？ npm の grok-mcp という名前は、無関係なプロジェクト（Grok HTTP API との統合）によってすでに使われていました。ブランド名、GitHub リポジトリ、MCP サーバーの識別名は引き続き grok-mcp です。npm のインストール識別子のみ grok-cli-mcp で、公式のGrok CLIをラップするサーバーであることを示すために選ばれました。

認証

認証方法は2つあり、それぞれバックエンドに対応しています。

方法	バックエンド	最適な用途	レート制限
API キー（XAI_API_KEY 環境変数）	API モード — grok バイナリは不要	MCP / CI / 自動化	呼び出しごとの従量課金で、サブスクリプションによる上限なし
ブラウザー OAuth（grok による対話型ログイン）	CLI モード	ローカルでの対話型利用	grok.com のプラン階層に準じます

XAI_API_KEY を設定すると、サーバーはAPI モードに切り替わります。そのため、対話型の grok 用のブラウザーログインをそのまま使いながら、MCP サーバー専用のキーを環境変数ブロックで設定できます。

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"],
      "env": {
        "XAI_API_KEY": "xai-...",
        "GROK_MCP_TIMEOUT": "600000"
      }
    }
  }
}

キーのファイルは秘密情報として扱ってください。MCP ホストの設定（例：~/.claude.json）に保存されますが、これはディスク上にプレーンな JSON として置かれます。

MCP ホストに接続する

Claude Code

推奨 — add-json を使うと、env ブロックを正しく解析できます。

claude mcp add-json -s user grok '{
  "command": "npx",
  "args": ["-y", "grok-cli-mcp"],
  "env": { "XAI_API_KEY": "xai-...", "GROK_MCP_TIMEOUT": "600000" }
}'

claude mcp add -e ... ではなく add-json を使う理由は？ -e KEY=val フラグは可変長引数のため、複数指定するとサーバー名まで別の環境変数の値として取り込まれてしまいます。add-json なら、この問題を完全に回避できます。

または、~/.claude.json を直接編集します。最小構成（OAuth フォールバック）：

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"]
    }
  }
}

Cursor

.cursor/mcp.json（プロジェクト）または ~/.cursor/mcp.json（グローバル）を作成します。

{
  "mcpServers": {
    "grok": {
      "command": "npx",
      "args": ["-y", "grok-cli-mcp"]
    }
  }
}

Cline（VS Code）

設定 → Cline → MCP Servers：

{
  "grok": {
    "command": "npx",
    "args": ["-y", "grok-cli-mcp"]
  }
}

Claude Desktop（ローカル、ホスティング不要）

Claude Desktop は引き続きローカルの stdio サーバーをサポートしています。Settings → Developer → Edit Config（claude_desktop_config.json）を開き、上記の Claude Code と同じ JSON ブロックを貼り付けます。

Claude Web / Claude Desktop コネクター（リモート、v0.4+）

Claude の Settings → Connectors → Add custom connector ダイアログではコマンドではなく HTTPS URL が必要です。そのため、同梱の Streamable HTTP サーバーをデプロイし、その URL を貼り付けます。

# 1. Generate a path secret (keeps strangers from spending your xAI credits)
openssl rand -base64 32 | tr '+/' '-_'

# 2. Deploy anywhere that runs Node (Railway / Fly / Render / a VPS).
#    A multi-stage Dockerfile ships in the repo:
docker build -t grok-mcp . && docker run \
  -e XAI_API_KEY=xai-... \
  -e GROK_MCP_PATH_SECRET=<secret-from-step-1> \
  -p 3000:3000 grok-mcp

# ...or without Docker:
XAI_API_KEY=xai-... GROK_MCP_PATH_SECRET=<secret> npx -y -p grok-cli-mcp grok-mcp-http

次に、URL を指定して Claude にコネクターを追加します。

https://your-host.example.com/mcp/<secret-from-step-1>

OAuth は不要です。Client ID/Secret フィールドは空欄のままにしてください。サーバーから要求された場合にのみ、Claude は OAuth フローを開始します。

リモートモードに関する注意事項：

• URL は認証情報として扱ってください。 パスのシークレットが、インターネットから xAI の利用料金を守る役割を果たします。環境変数を変更してローテーションしてください。
• grok_review を HTTP 経由で使う場合は、diff を明示的に指定する必要があります。 サーバーはローカルリポジトリを参照できないため、リモートモードでは git diff の自動実行が無効になります。
• GROK_MCP_TIMEOUT はプラットフォームのリクエストタイムアウトより短く設定してください（また、ゼロスケーリングを無効にしてください）。grok-4 の推論には数分かかることがあります。
• プラットフォームのヘルスチェックには GET /health を利用できます。すべての設定項目（GROK_MCP_ALLOWED_HOSTS、GROK_MCP_CORS_ORIGINS、…）については .env.example を参照してください。

その他の MCP ホスト

grok-mcp はプレーンな stdio MCP を使用します。任意のクライアントで npx -y grok-cli-mcp を指定すれば動作します。HTTP ホストの場合は、代わりに上記のリモートエンドポイントを指定できます。

ツールのリファレンス

grok_chat

{ "prompt": "Explain consistent hashing in two sentences." }

任意の設定項目として、デフォルトの Grok モデルを上書きする model と、grok-4 の長時間の推論に備えて呼び出しごとの制限時間を延長する timeout（秒）があります。4 つすべてのツールで timeout を指定できます。

grok_review

{ "base_ref": "main", "focus": "security" }

diff を省略すると、cwd（デフォルトではホストの作業ディレクトリ）で git diff <base_ref>...HEAD を実行します。デフォルトでは、判定、各観点のスコア（正確性／読みやすさ／アーキテクチャ／セキュリティ／パフォーマンス）、具体的な修正項目を含む Markdown のレビューを返します。

CI のゲートに適した機械解析可能な出力を得るには、"format": "json" を指定してください。PR ゲートとして使うを参照してください。

grok_consult

{
  "messages": [
    { "role": "system", "content": "You are a senior backend engineer." },
    { "role": "user", "content": "How would you cache this query?" },
    { "role": "assistant", "content": "Two options..." },
    { "role": "user", "content": "What's the failure mode of option 2?" }
  ]
}

サーバーはステートレスです。呼び出し側は毎回、スレッド全体を渡します。ほとんどの MCP ホストでは、これが自然に処理されます。

grok_challenge

{
  "code": "function transfer(from, to, amount) { from.balance -= amount; to.balance += amount; }",
  "context": "Node.js, called concurrently from HTTP handlers"
}

重大度（Critical／High／Medium／Low）の高い順に、具体的な再現手順とパッチを含む問題を返します。

設定

環境変数	デフォルト	用途
XAI_API_KEY	(未設定 — OAuth にフォールバック)	console.x.ai から取得した API キーです。設定すると、サーバーは API モード（直接 HTTP）を使用し、サブスクリプションのレート上限なしで呼び出しごとに課金されます。認証を参照してください。
GROK_MCP_BACKEND	auto	使用するバックエンドです。api（直接 HTTP）、cli（シェル経由で grok を実行）、auto（XAI_API_KEY が設定されていれば API、そうでなければ CLI）から選択します。バックエンドを参照してください。
GROK_MCP_MODEL	grok-4	API モードで使用するモデルです。（CLI モードでは ~/.grok/config.toml を読み込みます。）
GROK_MCP_BASE_URL	https://api.x.ai/v1	API のベース URL です。API モードでは、プロキシまたは互換性のあるゲートウェイを指定できます。
GROK_MCP_BIN	grok	grok バイナリへのパスです（CLI モードのみ）。
GROK_MCP_TIMEOUT	300000	呼び出しごとのデフォルトのタイムアウト（ミリ秒）です。

バックエンド

サーバーは2つの方法で Grok に接続でき、起動時にどちらかを選択します（選択した方法は stderr に記録されます）。

• API モード — Node の組み込み fetch を使用して、xAI の OpenAI 互換 /chat/completions エンドポイントを直接呼び出します。grok バイナリは不要で、エラーがわかりやすく、呼び出しごとの従量課金です。XAI_API_KEY が設定されている場合に選択されます。または GROK_MCP_BACKEND=api で強制できます。
• CLI モード — インストール済みの grok バイナリをシェル経由で実行します（ブラウザー OAuth に対応）。XAI_API_KEY が設定されていない場合に選択されます。または GROK_MCP_BACKEND=cli で強制できます。

GROK_MCP_BACKEND でモードを指定します。API モードでは GROK_MCP_MODEL でモデルを設定します。CLI モードでは、モデルのデフォルト設定は ~/.grok/config.toml にあります。

タイムアウト

grok-4 は推論モデルであり、長いプロンプトの処理には通常2分以上かかります。サーバーのデフォルトの呼び出しごとの制限は 300s（5分） です。次の3つの方法で変更できます。

• 呼び出しごと — 任意のツールに timeout（秒）を渡します：{ "prompt": "...", "timeout": 600 }。
• サーバーごと — MCP サーバーの環境変数で GROK_MCP_TIMEOUT（ミリ秒）を設定します。
• ホスト側 — MCP ホストには独自のリクエストタイムアウトがあり、サーバーのタイムアウトより先に発生することがあります。上記の値を増やしてもタイムアウトする場合は、ホスト側の制限も増やしてください。Claude Code では、どちらもミリ秒単位で、MCP_TIMEOUT（サーバー起動時）と MCP_TOOL_TIMEOUT（ツール呼び出しごと）を設定します。

タイムアウト時のエラーには、期限までに Grok が生成した部分的な出力が含まれるため、ほぼ完成した回答を失わずに済みます。

PR のゲートとして使用（CI）

grok-mcp には grok-review-ci バイナリと複合型 GitHub Action が付属しており、Grok にすべての PR をレビューさせ、判定が block の場合にチェックを失敗させることができます。

リポジトリの .github/workflows/grok-review.yml に次の内容を追加します。

name: Grok review
on: { pull_request: { branches: [main] } }
permissions: { contents: read, pull-requests: write }
jobs:
  grok:
    runs-on: ubuntu-latest
    if: ${{ github.event.pull_request.head.repo.full_name == github.repository }}
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: howardpen9/grok-mcp/.github/actions/grok-review@main
        with:
          xai-api-key: ${{ secrets.XAI_API_KEY }}
          gate-on: block      # also accepts: block,request_changes
          # focus: security   # optional
          # min-score: 6      # optional — fail any dimension below this

この Action は、判定、各評価項目のスコア、具体的なブロッカーを含む固定 PR コメントを投稿し、判定が gate-on と一致するとゼロ以外の終了コードを返します（チェックは失敗します）。コメント付きの完全な例はこちらです：examples/workflows/grok-review.yml。

ツールから JSON を直接取得したい場合は、grok_review に format: "json" を渡します。バイナリが出力するものと同じスキーマで、あらゆるパイプラインに適しています。

{
  "verdict": "block",
  "summary": "Unparameterised SQL query in src/db.ts.",
  "scores": { "correctness": 4, "readability": 7, "architecture": 5, "security": 2, "performance": 8 },
  "blockers": [
    { "severity": "critical", "title": "SQL injection", "file": "src/db.ts", "line": 42,
      "reason": "User input concatenated directly into the query.",
      "fix": "Use the parameterised form `db.query(sql, [userId])`." }
  ],
  "notes": []
}

ロードマップ

• v0.1 — ステートレスツール4つ、stdio トランスポート
• 発見しやすさの向上（v0.1.3、リリース済み） — 命名の統一、MCP Registry、Smithery、glama.ai、より明確な位置付け。詳細は docs/improvement-plan.md と CHANGELOG.md を参照してください。
• v0.2（リリース済み） — grok_review の JSON モード、grok-review-ci バイナリ、PR ゲート用 GitHub Action。
• v0.3（リリース済み） — xAI API への直接接続バックエンド（grok CLI 不要）、GROK_MCP_BACKEND の api/cli/auto。
• v0.4（現行） — リモート MCP モード：Claude Web / Claude Desktop のカスタムコネクター向け grok-mcp-http Streamable HTTP サーバー。パスシークレット認証、Dockerfile、.env.example を備えています。
• v0.5 — サーバー側のセッション永続化により、grok_consult で conversation_id を受け取れるようにする
• v0.6 — MCP progress 通知によるストリーミング応答、共有ホスト型インスタンス向けの OAuth とユーザーごとのキー保存領域

開発

git clone https://github.com/howardpen9/grok-mcp.git
cd grok-mcp
npm install
npm test
npm run build

お問い合わせ

バグ報告と機能リクエスト → GitHub のイシュー。 X の DM も歓迎します： @0xHoward_Peng。

ライセンス

MIT