Grok Build

grok-build-mcp-server

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

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

これは薄いプロセスラッパーです。エージェントのロジックを再実装したり、xAI API に直接アクセスしたりすることはありません。すべてのインテリジェンスは grok CLI にあります。このサーバーが追加するのは、忠実な引数の組み立て、堅牢なプロセスの監視、そして MCP に適した明瞭な出力です。

ステータス：0.2.2。 ツール群は完成しています。サーバーは実際のヘッドレス Grok エージェントをフォアグラウンドまたはバックグラウンドでデタッチして実行し、実行中に進捗をストリーミングし、リクエストに応じて実行を停止し、git の差分をレビューし、ウェブ上で質問を調査し、実行によって作成されたセッションを一覧表示して、セッション、使用量、コストを報告します。リリース内容は 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 を送信しないクライアントには、より低コストな非ストリーミング経路が使われます。

要件

• Grok Build CLI 1.0.0 以降。認証済みであること（grok models が成功する必要があります）
• Node.js 22 以降

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

インストール

Claude Code

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

-s user を指定すると、現在のディレクトリではなくアカウント全体にサーバーが登録されます。これを指定しないと、そのプロジェクトだけが対象になります。一般的なコーディングアシスタントでは、通常これは望ましくありません。別の場所で Claude Code を起動したときにサーバーが見つからない場合は、この設定が原因です。

次に、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 -s user -- ~/.local/share/grok-build-mcp/node_modules/.bin/grok-build-mcp-server

権限

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

権限は、呼び出しごとに確認するのではなく、サーバー登録時に一度設定する上限です。レベルは 3 段階あります。

レベル	--permission-mode	--sandbox	許可される操作
read-only（デフォルト）	plan	read-only	読み取りと推論。編集はできません
write	auto	workspace	作業ディレクトリー内の編集
full	bypassPermissions	off	無人での完全な承認

サンドボックスの設定は単なる目安ではなく、拒否は警告ではありません。write では、実行中に cwd の外部へ書き込むことはできません。拒否されたツール呼び出しがあると、実行全体が終了します。CLI は stopReason: cancelled を報告して 0 で終了し、拒否される前にモデルが出力した内容だけを返します。その場合、サーバーは拒否された呼び出しとそのパスを示すため、ツールの拒否をモデルが諦めたものと取り違えることはありません。サーバーにわかるのは、どの呼び出しが失敗したかであり、CLI が拒否した理由ではありません。リポジトリー外にレポートを書き出すなど、実行中に別の場所への書き込みが必要な場合は、cwd 内のパスを指定するか、full を使用してください。

write では acceptEdits ではなく --permission-mode auto を使用します。名前から推測される動作ではなく、実際の挙動に基づく選択です。ヘッドレス Grok には編集を承認する人間がいないため、acceptEdits、dontAsk、default のいずれを使っても、どちらのサンドボックスプロファイルでもファイルの変更がすべて拒否され、実行が終了します。auto と bypassPermissions はどちらも機能します。より制限が厳しいのは auto であり、ワークスペース外への書き込みは引き続き拒否されます。そのため、full は単なる別名ではなく、実際に権限が一段階上がります。

Grok に編集を許可するには、次のようにします。

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

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

上限を超える権限を要求する呼び出しは、暗黙に引き下げられるのではなく、拒否されます。権限が制限された実行が何も変更していないのに成功を報告するのは、明確なエラーを返すよりも問題が大きいためです。

環境変数

変数	デフォルト	用途
GROK_BINARY	grok	grok 実行ファイルのパス
GROK_MCP_PERMISSION_CEILING	read-only	各呼び出しで要求できる最高レベル
GROK_MCP_DEFAULT_PERMISSION	read-only	呼び出しで指定されない場合に使用するレベル
GROK_MCP_DEFAULT_MODEL	grok-4.6	呼び出しでモデルが省略された場合に使用するモデル。none の場合は CLI に委ねます
GROK_MCP_DEFAULT_EFFORT	high	呼び出しで省略された場合に使用する推論の労力。none の場合は CLI に委ねます
GROK_MCP_TIMEOUT_MS	1800000	1 回の実行に許される実時間
GROK_MCP_STATE_DIR	$XDG_STATE_HOME/grok-mcp	バックグラウンドジョブの記録
GROK_MCP_MAX_CONCURRENT_RUNS	4	同時に実行できるバックグラウンド実行の数。上限なしの場合は off
GROK_MCP_LOG_LEVEL	info	debug、info、warn、error。ログは stderr に出力されます
STRUCTURED_CONTENT_ENABLED	off	_meta に加えて structuredContent も出力します

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

ツール

ツール	読み取り専用	用途
grok	上限に従う	ヘッドレス Grok エージェントを実行します。プロンプト、セッションの再開／続行／フォーク、モデル、労力、ツールの許可／拒否
review	常時	git diff をレビューします。作業ツリー、参照との merge-base diff、または単一コミットに対応します
websearch	常時	Web で質問を調査し、実際に使用した検索と情報源を報告します
status	常時	バックグラウンド実行の状態を確認するか、最近の実行を一覧表示します
stop	いいえ	バックグラウンド実行のプロセスツリーを終了します
sessions	常時	このマシン上の Grok セッションを一覧表示、検索、参照します
check	はい	サーバーのバージョン、解決されたバイナリ、grok version、認証、権限の上限、実行時のデフォルトを確認します
help	はい	grok --help の内容をそのまま表示します

review

差分はプロセス内で収集され、プロンプトに埋め込まれるため、モデルがレビュー対象を再発見するためにターンを費やすことはありません。

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

対象には uncommitted、base: "<ref>"（マージベースの差分です。ブランチ作成後にベースに取り込まれたコミットは、あなたの変更として扱われません）、または commit: "<sha>" を指定できます。何も指定しない場合は自動検出されます。ブランチが先行していれば上流との差分、それ以外は作業ツリーが対象になります。黙って推測するのではなく、どちらを選んだかを伝えます。

GROK_MCP_PERMISSION_CEILING で許可されている内容にかかわらず、review は常に読み取り専用です。レビュー対象のコードを編集するレビューなど望まれていないため、permission、write、yolo 引数は受け付けません。

機械可読な指摘事項（severity、file、line、summary、rationale）を _meta.findings に含めるには、structured: true を指定してください。結果を確認する前に検証されます。

問題が起きるケースは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 にはどちらのフラグもなく、どちらのパラメーターも、CLI にその機能があるかのようには振る舞いません。ただし、実際に効果はあります。同じ質問でも、basic では2ページにまたがる検索が1回行われ、full では3ページにまたがる検索が6回行われました。コストは2.5倍です。

結果からは、モデルが何を書いたかだけでなく、実際に何を調べたかがわかります。

[1 web search, 9 sources]

_meta には webSearches、webToolCalls、searchQueries、sources、sourceCount、pagesOpened、searchPerformed が含まれます。これは想像以上に重要です。Grok はウェブ検索または X を使って調査できます。ウェブを利用できない場合、ひそかに後者を使うことがあり、自信たっぷりに回答し、x.com を引用して、正常に終了します。文章だけではその違いを見分けられません。そのため、ウェブではなく X を検索した実行は、最初の行でそのことを伝え、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 で、どちらの ID かを確認できます。同じディレクトリ内の複数の実行が該当する可能性がある場合は、 候補の 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 を参照してください。