grok-build-mcp-server

これは、Grok Build CLI（grok）を、Claude Code、Cursor、VS Code、その他のMCPクライアントから呼び出せるツールとして公開するMCP stdioサーバーです。

Claude Code  ──stdio/MCP──▶  grok-build-mcp-server  ──spawn──▶  grok CLI  ──▶  xAI API

これは軽量なプロセスラッパーです。エージェントロジックを再実装するものではなく、xAI APIと直接通信することもありません。すべてのインテリジェンスはgrok CLIに委ねられています。このサーバーが追加するのは、忠実な引数構築、堅牢なプロセス監視、そしてクリーンなMCP形式の出力です。

ステータス: 0.2.2. ツールの表面は完成しています。このサーバーは、フォアグラウンドまたはバックグラウンドでデタッチされた実際のヘッドレスGrokエージェントを実行し、実行中に進捗をストリーミングし、リクエストに応じて実行を停止し、git差分をレビューし、Web上で質問を調査し、それらの実行によって作成されたセッションを一覧表示し、セッション、使用量、コストを報告します。出荷された内容についてはCHANGELOG.mdを、検討されて却下された内容についてはROADMAP.mdを参照してください。

進捗

長時間のエージェント実行は、画面上で実際に進行状況が確認できるため、沈黙の待機が一気にテキストの壁で終わることはありません。クライアントがprogressTokenを送信すると、サーバーはGrokを--output-format streaming-jsonで実行し、イベントごとに通知を転送します。

#5  list_dir .
#6  read_file README.md
#7  read_file — completed
#8  thinking: the user asked me to list files, read README.md, then …
#10 writing: DONE
#11 finished: end_turn (2 turns)

進捗は、エージェントがどのフェーズにいるかではなく、何をしているかを追跡します。推論と応答テキストは統合されるため、トークンストリームがクライアントにあふれることはなく、ツール呼び出しは発生時に報告されます。resetTimeoutOnProgressをサポートするクライアントは、実行中にタイムアウトしません。

progressTokenを送信しないクライアントは、より安価な非ストリーミングパスを取得し、これに対して何も支払いません。

Related MCP server: Claude Code MCP Bridge

必要条件

• Grok Build CLI 1.0.0以上、認証済み（grok modelsが成功すること）

• Node.js 22以上

grokがPATHにない場合は、サーバーを登録する際にGROK_BINARYをフルパスに設定してください。

インストール

Claude Code

claude mcp add grok-build -- npx -y grok-build-mcp-server

次に、Claude Code内で:

> use the grok-build check tool

checkは、解決されたバイナリ、CLIバージョン、認証されているかどうか、アクティブな許可上限を報告します。正常であれば、残りも機能します。

その他のMCPクライアント

サーバーはstdio経由でMCPを話し、それ自体の引数は取りません。

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

VS CodeとCursorは、このページ上部のインストールバッジを受け付けます。これらのバッジには、まさにその構成が含まれています。

MCP Registryからインストールするクライアントは、このサーバーをio.github.Nuruvala/grok-build-mcp-serverとして認識します。レジストリエントリはnpmリリースと同じタグから公開され、同じパッケージを指しています。

npxがサーバーを見つけられない場合

npxは、ベアパッケージ名をローカルプロジェクトから最初に解決します。MCPクライアントの作業ディレクトリがこのリポジトリのチェックアウト、またはpackage.jsonがgrok-build-mcp-serverという名前の他の何かである場合、npx -y grok-build-mcp-serverはローカルのエントリポイントを実行しようとし、それを見つけられず、command not foundで失敗します。独自の場所にインストールし、そのパスを登録してください。

npm install --prefix ~/.local/share/grok-build-mcp grok-build-mcp-server
claude mcp add grok-build -- ~/.local/share/grok-build-mcp/node_modules/.bin/grok-build-mcp-server

権限

このサーバーを介して起動されたGrok実行は、デフォルトで読み取り専用です: --permission-mode planと--sandbox read-only。あなたが許可するまで、何もファイルを変更できません。

権限は上限であり、呼び出しごとにプロンプトを表示するのではなく、サーバーを登録するときに一度だけ設定します。3つのレベルがあります。

Grokに編集を許可するには:

claude mcp add grok-build \
  -e GROK_MCP_PERMISSION_CEILING=write \
  -e GROK_MCP_DEFAULT_PERMISSION=write \
  -- npx -y grok-build-mcp-server

fullは、すでにMCPクライアントを完全承認で実行しており、委任されたGrok実行も同様に無人にしたい場合にのみ使用してください。これにより、起動されたgrokプロセスに、あなたと同じ権限が付与されます。

上限を超えるリクエストは、黙ってダウングレードされるのではなく、拒否されます。制限された実行は成功を報告しながら何も変更しないため、明確なエラーよりも悪質です。

環境変数

Grok自身の変数（XAI_API_KEY、GROK_HOME、GROK_DISABLE_AUTOUPDATER）は、子プロセスにそのまま渡されます。

ツール

review

差分はプロセス内で収集され、プロンプトに埋め込まれるため、モデルは何をレビューしようとしているのかを再発見するためにターンを費やす必要がありません。

> review my working tree with grok-build
> review the diff against origin/main

ターゲットはuncommitted、base: "<ref>"（マージベースの差分。ブランチ作成後にベースに取り込まれたコミットはあなたのものとして扱われない）、またはcommit: "<sha>"です。何も指定しない場合は自動検出されます。ブランチが先行している場合は上流の差分、それ以外の場合はワーキングツリーが使用され、黙って推測するのではなく、どちらを選択したかを明示します。

reviewは、GROK_MCP_PERMISSION_CEILINGで許可されている設定に関わらず、常に読み取り専用です。レビュー対象のコードを編集するレビューが必要とされることは決してないため、permission、write、yoloの引数は取りません。

structured: trueを渡すと、_meta.findingsに機械可読な調査結果（severity、file、line、summary、rationale）が、検証後に表示されます。

2つの異なる問題が発生する可能性があり、それらは混同されることなく、異なる方法で報告されます。

• 実行が完了しなかった — 中断されたか、調査結果を生成せずに終了した。レビューがないため、呼び出しはisError: trueとなり、_meta.findingsCompleteはfalseです。本文は原因を先頭に、CLI自身の理由を引用し、実際の原因に適合する修正方法を挙げます。

• 実行は完了したが、出力が検証に合格しない。 呼び出しは依然として成功し、生のテキストに加えて_meta.parseErrorを返します。品質が低下したレビューは、失敗したレビューよりも優れています。

絶対に発生しないのは、モデルがでっち上げたもっともらしい調査結果です。--json-schemaはモデルが発するすべてのメッセージを制約するため、モデルがまだ読み取り中の間は、調査結果の形以外で「作業中」と言う方法はありません。そして、チェックを怠ると、まさにそれをやってしまいます。スキーマには必須のstatusフィールドがあり、その説明を結果から除外します。部分的な応答からパターンマッチングで何かを救出することは決してありません。

大規模なターゲットに対する構造化レビューは、この方法でかなりの頻度で失敗します。この失敗は設計上明白です。

シェルに手を伸ばすレビューは拒否され、強制終了されるのではありません。ヘッドレスモードでは、承認不可能なツールリクエストはCLIが終了コード0で終了する間に実行全体をキャンセルするため、reviewはシェルおよび編集ツールを完全に拒否します。モデルには「いいえ」と伝えられ、文の途中で死ぬ代わりにレビューを完了します。

websearch

> websearch: what changed in the latest Bun release?
> search the web for how Postgres handles advisory lock contention, in depth

numResults（1～50）とsearchDepth（basicまたはfull）はプロンプトを形成します。grok CLIにはこれらのフラグはなく、どちらのパラメータもそのように偽装しません。これらは実際に機能します。同じ質問をbasicで行うと2ページにわたって1回の検索が行われ、fullで行うと3ページにわたって6回の検索が行われ、コストは2.5倍になりました。

結果は、モデルが書いたものだけでなく、実際に何が検索されたかを示します。

[1 web search, 9 sources]

_metaにはwebSearches、webToolCalls、searchQueries、sources、sourceCount、pagesOpened、searchPerformedが含まれます。これは聞こえ以上に重要です。GrokはWeb検索またはXを通じて調査を行うことができ、Webが利用できない場合は静かに後者を行います。自信満々に答え、x.comを引用し、正常終了します。散文ではそれを見分ける方法がありません。したがって、Xを検索してWebを検索しなかった実行は、最初の行でその旨を述べ、xSearchesを別途報告します。また、何も返ってこなかった実行は、モデル自身の記憶から得た自信満々に見える回答ではなく、エラーとして扱われます。

No search ran. The answer below is the model's own prior knowledge, not current sources.

searchPerformedは、ソースが返ってきたことを意味します。検索が試行されたことではありません。開始されたが何も返ってこなかった検索、または空の結果セットを返した検索は、そのまま報告されます。

review と同様に、websearch は常に読み取り専用であり、permission、write、yolo のいずれの引数も受け取りません。--disable-web-search を渡すこともありません。

バックグラウンド実行、status、stop

長いエージェント実行はクライアントを占有する必要はありません。grok、review、 または websearch に background: true を渡すと、呼び出しはすぐに runId を返し、その間、切り離されたワーカープロセスが ジョブを完了まで実行します:

> have grok refactor the parser in the background
> status
> status the run from a minute ago and wait 30s for it
> stop that run

実行はこのサーバーではなくマシンに属します。MCP クライアントが切断しても、 サーバーが再起動しても、またはエディタを閉じても実行は継続します。レコードは GROK_MCP_STATE_DIR 配下、 実行ごとに 1 つのディレクトリに格納されます。

完了した実行に対する status は、同期呼び出しが返したであろうものを返します — 同じテキスト、 同じメタデータ、同じエラーフラグ。バックグラウンドはツール呼び出しのためのトランスポートであり、 別の実装ではありません。実行が進行中の場合、その状態、経過時間、両方のプロセス ID、および 進行ログの末尾を取得できます。waitMs は最大 2 分間ブロックし、進行通知が届くたびに転送します。 待機がタイムアウトしてもエラーではありません。

2 種類の偽りは構造的に排除されています。ワーカープロセスが存在しなくなった実行は、 まだ実行中としてではなく abandoned として報告されます — マシンが再起動したか、何かがそれを 強制終了したかのいずれかです。そして、早期に終了した実行はそのようにラベル付けされます:

mfk2p1x9-3ac71f0b  completed (cut off: cancelled)  grok  4m 12s  refactor the parser

runId を受け取る前に検証は依然として行われます:GROK_MCP_PERMISSION_CEILING を超えるリクエスト、 または矛盾するセッションフラグの組み合わせは、受け入れられてから誰も監視していないプロセスで 失敗するのではなく、失敗した呼び出しとして拒否されます。

stop は実行を早期に終了します。ワーカーのプロセスグループ全体 — ワーカーとそれが起動した grok プロセス — に SIGTERM を送信し、それで不十分な場合は SIGKILL を送信します。すでに終了した 実行を停止してもエラーにはなりません。呼び出しが届く直前に終了した実行を停止しても同様です。

プロセスツリーを強制終了できなかった停止は、停止した実行としてではなく、失敗として報告されます。 シグナルを送る対象がない場合、強制終了が拒否された場合、またはツリーが SIGKILL を生き延びた場合、 実行は running のままとなり、呼び出しは pid を名指ししたエラーを返します。生存中のプロセスの隣に cancelled レコードがあるのは、よりすっきりした答えであり、役に立たない答えでもあります。

途中で停止した実行は、通常すでに保存する価値のあるものを生成しており、部分的な結果と セッション ID の両方が保持されます:

Stopped run msxji60o-8f5e27c4 (grok, ran 20s).
Signalled SIGTERM to process group 1703005; the tree exited.

The run was cancelled mid-flight, but it recorded a session before it ended:
  grok -r 01a010e2-478c-73d2-bce9-23552245c64d

Grok は実行が終了に達したときのみセッション ID を報告しますが、停止された実行は終了に達することはありません — そのため、その ID は再構築されるのではなく、CLI 自身のセッションストアから読み戻されます。_meta.sessionIdSource はどちらの方法で取得したかを示します。同じディレクトリ内の 2 つの実行が両方とも一致する可能性がある場合、 候補 ID が返され、再開コマンドは返されません:誤ったセッションを再開すると、他人の作業を継続することになります。

sessions

すべての Grok 実行はディスク上にセッションを残し、このサーバーが報告するすべてのセッション ID は 後で再開できます — 任意のディレクトリから、ターミナルで直接、または別のツール呼び出しによって。

> list my recent grok sessions
> what grok sessions did I run in this repo?
> find the grok session about the rate limiter

セッションは $GROK_HOME/sessions (デフォルトは ~/.grok/sessions) から読み取られます。これは CLI 自身の ストアであり、このサーバー、MCP クライアント、マシンの再起動後も存続します。1 つのセッションには id を、 タイトル、最初のプロンプト、ID に対する大文字小文字を区別しない検索には query を、1 つのプロジェクトに スコープを絞るには cwd を、リストの上限を設定するには limit を渡します。

終了したばかりの実行にはまだタイトルがありません — Grok は後で埋めることもあります — そのため、行は セッションの最初のプロンプトにフォールバックし、titleSource はどちらを見ているかを示します。すべての 行に resumeCommand が含まれ、すべての grok と review の結果にも含まれます:

grok -r 01a00c8d-970c-7531-8a12-31dac582c22b

検索はローカルのみです。grok sessions search はリモートインデックスも参照しますが、このツールは 参照しないため、サーバー側にのみ存在するセッションは表示されません。

開発

npm install
npm run build          # tsc -> dist/
npm run dev            # tsx src/index.ts
npm test               # node --test via tsx
npm run test:coverage  # same, with enforced coverage floors
npm run lint
npm run typecheck
npm run format

• docs/api-reference.md — 各ツールのパラメータ、結果テキスト、_meta キー、およびそれぞれが設定される正確な条件。

• docs/security.md — このサーバーを登録することで何が許可されるか、各権限レベルが 実際に何を付与するか、そして何がマシンから外部に出るか。

• docs/engineering.md — ここでのコードの書き方:アーキテクチャ、関数型 TypeScript のルール、エラーとエフェクトの規律、テストとカバレッジの方針、コミットワークフロー。

• CLAUDE.md — プロジェクトの背景と、このサーバーが依存する検証済みの grok CLI の動作。

• ROADMAP.md — マイルストーン、受け入れ基準、そして評価され却下されたアイデア。

リリース

package.json の version を上げ、CHANGELOG.md の Unreleased セクションを 新しいバージョンの見出しの下に移動し、コミットしてから:

git tag -a v0.2.0 -m v0.2.0 && git push origin v0.2.0

.github/workflows/release.yml は完全なゲートを実行し、タグと package.json が一致しない場合は公開を拒否し、パッケージ化された tarball をスクラッチディレクトリに インストールし、インストールされたバイナリに対して実際の initialize を実行してから、その同じファイル を 公開し、GitHub リリースを作成します。

管理すべき公開用の資格情報はありません。認証は npm trusted publishing です:ワークフローは 短命の OIDC トークンを交換し、npm は独自に来歴証明を生成します。信頼は このリポジトリとこのワークフローの ファイル名 に対して登録されているため、release.yml の名前を変更すると公開が壊れます — そして npm は公開が試行されるまで設定をチェックせず、そのときの 症状は原因を特定できるものではなく ENEEDAUTH です。

ライセンス

MIT — LICENSE を参照してください。