grok-build-mcp-server

Ein MCP stdio-Server, der die Grok Build-CLI (grok) als Tools bereitstellt, die Sie von Claude Code, Cursor, VS Code oder jedem anderen MCP-Client aus aufrufen können.

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

Es ist ein dünner Prozess-Wrapper. Es implementiert keine Agentenlogik neu und kommuniziert nicht direkt mit der xAI-API – die gesamte Intelligenz bleibt in der grok-CLI. Was dieser Server hinzufügt, ist eine getreue Argumentkonstruktion, robuste Prozessüberwachung und saubere, MCP-förmige Ausgabe.

Status: 0.2.2. Die Tool-Oberfläche ist vollständig. Der Server führt echte kopflose Grok-Agenten im Vordergrund oder abgekoppelt im Hintergrund aus, streamt Fortschritte während sie laufen, stoppt einen Lauf auf Anfrage, überprüft Git-Diffs, recherchiert Fragen im Web, listet die Sitzungen, die diese Läufe erstellt haben, und meldet Sitzung, Nutzung und Kosten. Siehe CHANGELOG.md für das, was ausgeliefert wurde, und ROADMAP.md für das, was in Betracht gezogen und abgelehnt wurde.

Fortschritt

Ein langer Agentenlauf ist sichtbar, während er stattfindet, anstatt eines stillen Wartens, das in einer Textwand endet. Wenn Ihr Client einen progressToken sendet, führt der Server Grok mit --output-format streaming-json aus und leitet eine Benachrichtigung pro Ereignis weiter:

#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)

Der Fortschritt verfolgt, was der Agent tut, nicht in welcher Phase er sich befindet. Reasoning- und Antworttext werden zusammengefasst, sodass ein Token-Stream Ihren Client nicht überflutet, während Tool-Aufrufe gemeldet werden, sobald sie auftreten. Clients, die resetTimeoutOnProgress unterstützen, werden während des Laufs nicht auslaufen.

Ein Client, der keinen progressToken sendet, erhält den günstigeren Nicht-Streaming-Pfad und zahlt nichts dafür.

Related MCP server: Claude Code MCP Bridge

Anforderungen

• Grok Build CLI 1.0.0 oder neuer, authentifiziert (grok models sollte erfolgreich sein)

• Node.js 22 oder neuer

Wenn grok nicht in Ihrem PATH ist, setzen Sie GROK_BINARY auf den vollständigen Pfad, wenn Sie den Server registrieren.

Installieren

Claude Code

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

Dann, in Claude Code:

> use the grok-build check tool

check meldet das aufgelöste Binary, die CLI-Version, ob Sie authentifiziert sind, und die aktive Berechtigungsobergrenze. Wenn es zufrieden ist, funktioniert der Rest.

Jeder andere MCP-Client

Der Server spricht MCP über stdio und akzeptiert keine eigenen Argumente:

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

VS Code und Cursor akzeptieren die Installations-Badges oben auf dieser Seite, die genau diese Konfiguration enthalten.

Clients, die aus der MCP Registry installieren, kennen diesen Server als io.github.Nuruvala/grok-build-mcp-server. Der Registry-Eintrag wird vom selben Tag wie die npm-Veröffentlichung veröffentlicht und zeigt auf dasselbe Paket.

Wenn npx den Server nicht finden kann

npx löst einen bloßen Paketnamen zuerst gegen das lokale Projekt auf. Wenn das Arbeitsverzeichnis Ihres MCP-Clients ein Checkout dieses Repositorys ist – oder von irgendetwas anderem, dessen package.json grok-build-mcp-server heißt – führt npx -y grok-build-mcp-server den lokalen Einstiegspunkt aus, findet keinen und schlägt mit command not found fehl. Installieren Sie es an einem eigenen Ort und registrieren Sie diesen Pfad:

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

Berechtigungen

Grok-Läufe, die über diesen Server gestartet werden, sind standardmäßig schreibgeschützt: --permission-mode plan mit --sandbox read-only. Nichts kann Ihre Dateien ändern, bis Sie es sagen.

Die Berechtigung ist eine Obergrenze, die einmal beim Registrieren des Servers gesetzt wird, anstatt einer Aufforderung bei jedem Aufruf. Drei Stufen:

Um Grok Änderungen vornehmen zu lassen:

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

Verwenden Sie full nur, wenn Sie Ihren MCP-Client bereits mit vollständiger Genehmigung ausführen und möchten, dass der delegierte Grok-Lauf ebenso unbeaufsichtigt ist. Es gewährt dem gestarteten grok-Prozess dieselbe Autorität, die Sie haben.

Ein Aufruf, der mehr als die Obergrenze anfordert, wird abgelehnt, nicht stillschweigend herabgestuft – ein begrenzter Lauf würde Erfolg melden, während er nichts ändert, was schlimmer ist als ein klarer Fehler.

Umgebungsvariablen

Grok's eigene Variablen (XAI_API_KEY, GROK_HOME, GROK_DISABLE_AUTOUPDATER) werden unverändert an den Kindprozess weitergegeben.

Tools

review

Der Diff wird prozessintern gesammelt und in den Prompt eingebettet, sodass das Modell keine Züge damit verbringt, wiederzuentdecken, was es überprüfen soll.

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

Ziele sind uncommitted, base: "<ref>" (ein Merge-Base-Diff, sodass Commits, die nach Ihrem Branch auf der Basis gelandet sind, nicht Ihnen zugeschrieben werden), oder commit: "<sha>". Ohne Angabe erkennt es automatisch: den Upstream-Diff, wenn Ihr Branch voraus ist, ansonsten den Arbeitsbaum – und es sagt, welches es gewählt hat, anstatt still zu raten.

review ist immer schreibgeschützt, unabhängig davon, was GROK_MCP_PERMISSION_CEILING erlaubt. Es akzeptiert kein permission-, write- oder yolo-Argument, denn eine Überprüfung, die den überprüften Code bearbeitet, ist nie das, was gewünscht war.

Übergeben Sie structured: true für maschinenlesbare Ergebnisse (severity, file, line, summary, rationale) auf _meta.findings, validiert bevor Sie sie sehen.

Zwei verschiedene Dinge können schiefgehen, und sie werden unterschiedlich gemeldet, anstatt verschwommen zu werden:

• Der Lauf wurde nie beendet – er wurde abgebrochen oder endete, ohne seine Ergebnisse zu liefern. Es gibt keine Überprüfung, also ist der Aufruf isError: true und _meta.findingsComplete ist false. Der Text beginnt mit dem Warum, zitiert den eigenen Grund der CLI und nennt die Lösung, die zur tatsächlichen Ursache passt.

• Der Lauf wurde beendet, aber seine Ausgabe wird nicht validieren. Der Aufruf ist trotzdem erfolgreich und gibt den Rohtext plus einen _meta.parseError zurück – eine degradierte Überprüfung ist besser als eine fehlgeschlagene.

Was Sie nie bekommen werden, ist ein plausibel aussehendes Ergebnis, das das Modell erfunden hat. --json-schema schränkt jede Nachricht ein, die das Modell ausgibt, sodass es während des Lesens keine Möglichkeit hat, "Ich arbeite" zu sagen, außer in Form eines Ergebnisses – und wenn man es nicht kontrolliert, tut es genau das. Das Schema trägt ein erforderliches status-Feld, um diese Erzählung aus Ihren Ergebnissen herauszuhalten, und nichts wird jemals durch Mustervergleich aus einer Teilantwort gerettet.

Strukturierte Überprüfungen großer Ziele scheitern auf diese Weise mit einiger Regelmäßigkeit. Der Fehler ist absichtlich laut.

Eine Überprüfung, die nach einer Shell greift, wird verweigert, nicht getötet. Im kopflosen Modus bricht eine nicht genehmigbare Tool-Anfrage den gesamten Lauf ab, während die CLI immer noch mit 0 beendet wird, also verweigert review die Shell- und Bearbeitungstools direkt – dem Modell wird Nein gesagt und es beendet seine Überprüfung, anstatt mitten im Satz zu sterben.

websearch

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

numResults (1–50) und searchDepth (basic oder full) formen den Prompt – die grok-CLI hat keine Flags für beides, und keiner der Parameter tut so, als ob. Sie funktionieren: Dieselbe Frage, bei basic gestellt, führte eine Suche über zwei Seiten durch, und bei full sechs Suchen über drei, für zweieinhalb Mal die Kosten.

Das Ergebnis sagt Ihnen, was tatsächlich nachgeschlagen wurde, nicht nur, was das Modell geschrieben hat:

[1 web search, 9 sources]

mit _meta, das webSearches, webToolCalls, searchQueries, sources, sourceCount, pagesOpened und searchPerformed enthält. Das ist wichtiger, als es klingt. Grok kann über Websuche oder über X recherchieren, und wenn das Web nicht verfügbar ist, wird es leise das Zweite tun – selbstbewusst antworten, x.com zitieren, erfolgreich beenden. Der Text gibt Ihnen keine Möglichkeit, das zu erkennen. Ein Lauf, der X und nicht das Web durchsucht hat, sagt das in seiner ersten Zeile und meldet xSearches separat, und ein Lauf, bei dem nichts zurückkam, ist ein Fehler, anstatt einer selbstbewusst aussehenden Antwort aus dem eigenen Gedächtnis des Modells:

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

searchPerformed bedeutet, dass Quellen zurückkamen – nicht, dass eine Suche versucht wurde. Eine Suche, die begann und nie zurückkehrte, oder eine leere Ergebnismenge zurückgab, wird als das gemeldet, was sie war.

Wie review ist websearch immer schreibgeschützt und akzeptiert weder permission, write noch yolo als Argument. Es übergibt nie --disable-web-search.

Hintergrundläufe, status und stop

Ein langer Agentenlauf muss nicht Ihren Client belegen. Übergeben Sie background: true an grok, review oder websearch, und der Aufruf gibt sofort eine runId zurück, während ein abgetrennter Worker-Prozess den Auftrag bis zum Ende ausführt:

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

Der Lauf gehört zum Rechner, nicht zu diesem Server: Er läuft weiter, wenn Ihr MCP-Client die Verbindung trennt, wenn der Server neu startet oder wenn Sie Ihren Editor schließen. Aufzeichnungen liegen unter GROK_MCP_STATE_DIR, ein Verzeichnis pro Lauf.

status auf einem abgeschlossenen Lauf gibt das zurück, was der synchrone Aufruf zurückgegeben hätte – derselbe Text, dieselben Metadaten, dasselbe Fehlerflag. Hintergrund ist ein Transportmittel für einen Tool-Aufruf, nicht eine zweite Implementierung. Solange ein Lauf aktiv ist, erhalten Sie seinen Status, die verstrichene Zeit, beide Prozess-IDs und das Ende seines Fortschrittslogs; waitMs blockiert für bis zu zwei Minuten und leitet Fortschrittsmeldungen weiter, sobald sie eintreffen. Ein abgelaufenes Warten ist kein Fehler.

Zwei Arten von Unehrlichkeit sind von vornherein ausgeschlossen. Ein Lauf, dessen Worker-Prozess nicht mehr existiert, wird als abandoned gemeldet und nicht als noch laufend – der Rechner wurde neu gestartet oder etwas hat ihn beendet. Und ein Lauf, der frühzeitig beendet wurde, wird als solcher gekennzeichnet:

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

Die Validierung erfolgt immer noch, bevor Sie eine runId erhalten: Eine Anfrage über GROK_MCP_PERMISSION_CEILING oder ein widersprüchliches Paar von Session-Flags wird als fehlgeschlagener Aufruf abgelehnt, anstatt angenommen und dann in einem Prozess, den niemand beobachtet, zum Scheitern gebracht zu werden.

stop beendet einen Lauf vorzeitig. Es sendet der gesamten Prozessgruppe des Workers – dem Worker und dem von ihm gestarteten grok-Prozess – ein SIGTERM, dann SIGKILL, falls das nicht ausreicht. Das Stoppen eines bereits beendeten Laufs ist kein Fehler, ebenso wenig wie das Stoppen eines Laufs, der kurz vor Ihrem Aufruf beendet wurde.

Ein Stopp, der den Prozessbaum nicht beenden konnte, wird als Fehler gemeldet, nicht als gestoppter Lauf. Wenn es nichts zu signalisieren gibt, oder der Kill verweigert wird, oder der Baum SIGKILL überlebt, bleibt der Lauf auf running und der Aufruf gibt einen Fehler mit der PID zurück. Ein cancelled-Eintrag neben einem laufenden Prozess wäre die aufgeräumtere Antwort und die nutzlose.

Ein Lauf, den Sie mittendrin stoppen, hat normalerweise bereits etwas Nützliches hervorgebracht, und sowohl das Teilergebnis als auch die Session-ID bleiben erhalten:

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 meldet eine Session-ID nur, wenn ein Lauf sein Ende erreicht, was ein gestoppter Lauf nie tut – daher wird diese ID aus dem eigenen Session-Store der CLI ausgelesen, anstatt rekonstruiert zu werden. _meta.sessionIdSource sagt Ihnen, welche Sie haben. Wenn zwei Läufe im selben Verzeichnis beide passen könnten, erhalten Sie die Kandidaten-IDs und keinen Wiederaufnahmebefehl: Die Wiederaufnahme der falschen Session setzt die Arbeit einer anderen Person fort.

sessions

Jeder Grok-Lauf hinterlässt eine Session auf der Festplatte, und jede Session-ID, die dieser Server meldet, kann später fortgesetzt werden – von jedem Verzeichnis aus, von Ihnen im Terminal oder durch einen anderen Tool-Aufruf.

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

Sessions werden aus $GROK_HOME/sessions (Standard ~/.grok/sessions) gelesen, dem eigenen Store der CLI, sodass sie Neustarts dieses Servers, Ihres MCP-Clients und Ihres Rechners überleben. Übergeben Sie id für eine einzelne Session, query für eine groß-/kleinschreibungsunabhängige Suche über Titel, erste Prompts und IDs, cwd zur Eingrenzung auf ein Projekt und limit zur Begrenzung der Liste.

Ein gerade abgeschlossener Lauf hat noch keinen Titel – Grok füllt diese später nach, falls überhaupt – daher fallen Zeilen auf den ersten Prompt der Session zurück, und titleSource sagt Ihnen, was Sie gerade sehen. Jede Zeile trägt resumeCommand, ebenso wie jedes grok- und review-Ergebnis:

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

Die Suche ist nur lokal. grok sessions search konsultiert auch ein entferntes Index; dieses Tool tut das nicht, daher wird eine Session, die nur serverseitig existiert, nicht angezeigt.

Entwicklung

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 – Parameter jedes Tools, Ergebnistext, _meta-Schlüssel und die genauen Bedingungen, unter denen jeder gesetzt wird.

• docs/security.md – Was die Registrierung dieses Servers autorisiert, was jede Berechtigungsstufe tatsächlich gewährt und was Ihren Rechner verlässt.

• docs/engineering.md – Wie Code hier geschrieben wird: Architektur, funktionale TypeScript-Regeln, Fehler- und Effekt-Disziplin, Test- und Coverage-Richtlinie, Commit-Workflow.

• CLAUDE.md – Projekthintergrund und das verifizierte grok-CLI-Verhalten, auf das dieser Server angewiesen ist.

• ROADMAP.md – Meilensteine, Akzeptanzkriterien und die Ideen, die gemessen und verworfen wurden.

Veröffentlichung

Erhöhen Sie die version in package.json, verschieben Sie den Abschnitt Unreleased von CHANGELOG.md unter die neue Versionsüberschrift, committen Sie, dann:

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

.github/workflows/release.yml führt das vollständige Gate aus, verweigert die Veröffentlichung, wenn Tag und package.json nicht übereinstimmen, installiert das gepackte Tarball in ein temporäres Verzeichnis und führt eine echte initialize gegen die installierte Binärdatei aus, veröffentlicht dann dieselbe Datei und erstellt ein GitHub-Release.

Es gibt keine zu verwaltenden Veröffentlichungsanmeldeinformationen. Die Authentifizierung erfolgt über npm Trusted Publishing: Der Workflow tauscht ein kurzlebiges OIDC-Token aus, und npm generiert die Herkunftsbestätigung selbstständig. Die Vertrauensstellung ist gegen dieses Repository und den Dateinamen dieses Workflows registriert, sodass die Umbenennung von release.yml die Veröffentlichung unterbricht – und npm prüft die Konfiguration erst, wenn eine Veröffentlichung versucht wird, wobei das Symptom ENEEDAUTH ist, nichts, das die Ursache benennt.

Lizenz

MIT – siehe LICENSE.