grok-build-mcp-server

Un servidor MCP stdio que expone la CLI de Grok Build (grok) como herramientas que puedes invocar desde Claude Code, Cursor, VS Code o cualquier otro cliente MCP.

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

Es un envoltorio ligero de procesos. No reimplementa la lógica del agente ni se comunica directamente con la API de xAI — toda la inteligencia reside en la CLI grok. Lo que este servidor añade es una construcción fiel de argumentos, una supervisión robusta de procesos y una salida limpia con formato MCP.

Estado: 0.2.2. La superficie de herramientas está completa. El servidor ejecuta agentes Grok headless reales en primer plano o en segundo plano de forma desatendida, transmite el progreso mientras se ejecutan, detiene una ejecución cuando se solicita, revisa diferencias de git, investiga preguntas en la web, lista las sesiones que crearon esas ejecuciones, e informa sobre sesiones, uso y coste. Consulta CHANGELOG.md para ver lo publicado y ROADMAP.md para lo que se consideró y rechazó.

Progreso

Una ejecución larga de un agente es visible mientras ocurre, en lugar de una espera silenciosa que termina en un muro de texto. Cuando tu cliente envía un progressToken, el servidor ejecuta Grok con --output-format streaming-json y reenvía una notificación por evento:

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

El progreso rastrea lo que el agente está haciendo, no en qué fase se encuentra. El razonamiento y el texto de respuesta se fusionan para que un flujo de tokens no inunde tu cliente, mientras que las llamadas a herramientas se informan a medida que ocurren. Los clientes que admiten resetTimeoutOnProgress no agotarán el tiempo de espera a mitad de la ejecución.

Un cliente que no envía progressToken obtiene la ruta más económica sin streaming y no paga nada por ello.

Related MCP server: Claude Code MCP Bridge

Requisitos

• CLI de Grok Build 1.0.0 o superior, autenticada (grok models debe funcionar)

• Node.js 22 o superior

Si grok no está en tu PATH, establece GROK_BINARY con su ruta completa al registrar el servidor.

Instalación

Claude Code

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

Luego, en Claude Code:

> use the grok-build check tool

check informa el binario resuelto, la versión de la CLI, si estás autenticado y el límite de permisos activo. Si todo está correcto, el resto funcionará.

Cualquier otro cliente MCP

El servidor habla MCP a través de stdio y no acepta argumentos propios:

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

VS Code y Cursor aceptan las insignias de instalación en la parte superior de esta página, que llevan exactamente esa configuración.

Los clientes que se instalan desde el Registro MCP conocen este servidor como io.github.Nuruvala/grok-build-mcp-server. La entrada del registro se publica desde la misma etiqueta que el lanzamiento de npm y apunta al mismo paquete.

Si npx no encuentra el servidor

npx resuelve un nombre de paquete simple contra el proyecto local primero. Si el directorio de trabajo de tu cliente MCP es una copia de este repositorio — o de cualquier otro cuyo package.json se llame grok-build-mcp-server — npx -y grok-build-mcp-server ejecuta el punto de entrada local, no encuentra ninguno y falla con command not found. Instálalo en su propio lugar y registra esa ruta:

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

Permisos

Las ejecuciones de Grok lanzadas a través de este servidor son de solo lectura por defecto: --permission-mode plan con --sandbox read-only. Nada puede modificar tus archivos hasta que tú lo indiques.

El permiso es un límite máximo, establecido una vez al registrar el servidor, en lugar de una solicitud en cada llamada. Tres niveles:

Para permitir que Grok haga ediciones:

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

Usa full solo si ya ejecutas tu cliente MCP con aprobación total y deseas que la ejecución delegada de Grok esté igualmente desatendida. Concede al proceso grok generado la misma autoridad que tienes tú.

Una llamada que solicite más del límite máximo es rechazada, no degradada silenciosamente — una ejecución limitada informaría éxito sin cambiar nada, lo cual es peor que un error claro.

Variables de entorno

Las variables propias de Grok (XAI_API_KEY, GROK_HOME, GROK_DISABLE_AUTOUPDATER) se transmiten al proceso hijo sin cambios.

Herramientas

review

El diff se recopila en el proceso y se incrusta en el prompt, para que el modelo no gaste turnos redescubriendo lo que se supone que debe revisar.

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

Los objetivos son uncommitted, base: "<ref>" (un diff de base de fusión, por lo que los commits que llegaron a la base después de que creaste tu rama no se te atribuyen), o commit: "<sha>". Si no se proporciona ninguno, se detecta automáticamente: el diff ascendente cuando tu rama está adelantada, de lo contrario el árbol de trabajo — y dice cuál eligió en lugar de adivinarlo en silencio.

review es siempre de solo lectura, independientemente de lo que permita GROK_MCP_PERMISSION_CEILING. No acepta ningún argumento permission, write o yolo, porque una revisión que edita el código bajo revisión nunca es lo que se deseaba.

Pasa structured: true para obtener hallazgos legibles por máquina (severity, file, line, summary, rationale) en _meta.findings, validados antes de que los veas.

Dos cosas diferentes pueden salir mal, y se informan de manera diferente en lugar de difuminarse:

• La ejecución nunca terminó — se interrumpió o finalizó sin producir sus hallazgos. No hay revisión, por lo que la llamada es isError: true y _meta.findingsComplete es false. El cuerpo comienza con el motivo, citando la razón de la propia CLI, y nombra la solución que se ajusta a la causa real.

• La ejecución terminó pero su salida no se validará. La llamada aún tiene éxito, devolviendo el texto sin procesar más un _meta.parseError — una revisión degradada es mejor que una fallida.

Lo que nunca obtendrás es un hallazgo de apariencia plausible que el modelo inventó. --json-schema restringe cada mensaje que el modelo emite, por lo que mientras aún está leyendo no tiene forma de decir "estoy trabajando" excepto en la forma de un hallazgo — y sin control, hace exactamente eso. El esquema lleva un campo status requerido para mantener esa narración fuera de tus resultados, y nunca se recupera nada de una respuesta parcial mediante coincidencia de patrones.

Las revisiones estructuradas de objetivos grandes fallan de esta manera con cierta regularidad. El fallo es ruidoso por diseño.

Una revisión que intenta acceder a un shell es rechazada, no terminada. En modo headless, una solicitud de herramienta no aprobable cancela toda la ejecución mientras la CLI aún sale con 0, por lo que review niega las herramientas de shell y edición directamente — se le dice no al modelo y termina su revisión en lugar de morir a mitad de la frase.

websearch

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

numResults (1–50) y searchDepth (basic o full) dan forma al prompt — la CLI grok no tiene banderas para ninguno, y ningún parámetro finge lo contrario. Funcionan: la misma pregunta hecha en basic hizo una búsqueda en dos páginas, y en full hizo seis búsquedas en tres, por dos veces y media el coste.

El resultado te dice lo que realmente se consultó, no solo lo que el modelo escribió:

[1 web search, 9 sources]

con _meta que lleva webSearches, webToolCalls, searchQueries, sources, sourceCount, pagesOpened y searchPerformed. Eso importa más de lo que parece. Grok puede investigar a través de la búsqueda web o a través de X, y cuando la web no está disponible, hará silenciosamente lo segundo — respondiendo con confianza, citando x.com, saliendo con éxito. La prosa no te da forma de saberlo. Por lo tanto, una ejecución que buscó en X y no en la web lo dice en su primera línea e informa xSearches por separado, y una ejecución donde no volvió nada en absoluto es un error en lugar de una respuesta de apariencia confiada de la propia memoria del modelo:

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

searchPerformed significa que volvieron fuentes — no que se intentó una búsqueda. Una búsqueda que comenzó y nunca regresó, o que devolvió un conjunto de resultados vacío, se informa como lo que fue.

Al igual que review, websearch es siempre de solo lectura y no acepta argumentos permission, write ni yolo. Nunca pasa --disable-web-search.

Ejecuciones en segundo plano, status y stop

Una ejecución larga del agente no tiene por qué ocupar tu cliente. Pasa background: true a grok, review o websearch y la llamada devuelve un runId de inmediato, mientras un proceso trabajador independiente ejecuta el trabajo hasta completarlo:

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

La ejecución pertenece a la máquina, no a este servidor: continúa si tu cliente MCP se desconecta, si el servidor se reinicia o si cierras tu editor. Los registros viven en GROK_MCP_STATE_DIR, un directorio por ejecución.

status sobre una ejecución finalizada devuelve lo que habría devuelto la llamada síncrona — mismo texto, mismos metadatos, mismo indicador de error. El segundo plano es un transporte para una llamada a herramienta, no una segunda implementación de la misma. Mientras una ejecución está activa obtienes su estado, tiempo transcurrido, ambos identificadores de proceso y la cola de su registro de progreso; waitMs bloquea hasta dos minutos y reenvía las notificaciones de progreso a medida que llegan. Una espera agotada no es un error.

Dos tipos de deshonestidad quedan descartados por construcción. Una ejecución cuyo proceso trabajador ya no existe se reporta como abandoned en lugar de como aún en ejecución — la máquina se reinició o algo la mató. Y una ejecución que terminó temprano se etiqueta como tal:

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

La validación sigue ocurriendo antes de que obtengas un runId: una solicitud por encima de GROK_MCP_PERMISSION_CEILING, o un par contradictorio de indicadores de sesión, se rechaza como una llamada fallida en lugar de aceptarse y luego fallar en un proceso que nadie está observando.

stop termina una ejecución anticipadamente. Envía una señal al grupo de procesos completo del trabajador — el trabajador y el proceso grok que generó — con SIGTERM, y luego SIGKILL si eso no es suficiente. Detener una ejecución ya finalizada no es un error, ni tampoco lo es detener una que terminó justo antes de que llegara tu llamada.

Una parada que no pudo matar el árbol de procesos se reporta como un fallo, no como una ejecución detenida. Si no hay nada a lo que enviar señal, o el asesinato es rechazado, o el árbol sobrevive a SIGKILL, la ejecución sigue marcada como running y la llamada devuelve un error que nombra el pid. Un registro cancelled junto a un proceso vivo sería la respuesta más ordenada, pero inútil.

Una ejecución que detienes a medio vuelo normalmente ya ha producido algo que vale la pena conservar, y tanto el resultado parcial como el identificador de sesión se conservan:

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 solo reporta un identificador de sesión cuando una ejecución llega a su fin, cosa que una detenida nunca hace — así que ese id se lee del propio almacén de sesiones de la CLI en lugar de reconstruirse. _meta.sessionIdSource te indica cuál tienes. Si dos ejecuciones en el mismo directorio pudieran coincidir, obtienes los ids candidatos y ningún comando de reanudación: reanudar la sesión incorrecta continúa el trabajo de otra persona.

sessions

Cada ejecución de Grok deja una sesión en disco, y cada identificador de sesión que reporta este servidor puede reanudarse después — desde cualquier directorio, por ti en una terminal o mediante otra llamada a herramienta.

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

Las sesiones se leen de $GROK_HOME/sessions (por defecto ~/.grok/sessions), que es el propio almacén de la CLI, por lo que sobreviven a reinicios de este servidor, de tu cliente MCP y de tu máquina. Pasa id para una sesión, query para una búsqueda que no distingue mayúsculas sobre títulos, primeros avisos e ids, cwd para limitar a un proyecto, y limit para acotar la lista.

Una ejecución que acaba de terminar aún no tiene título — Grok los completa después, si acaso — así que las filas recurren al primer aviso de la sesión, y titleSource te indica cuál estás viendo. Cada fila lleva resumeCommand, y también lo lleva cada resultado de grok y review:

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

La búsqueda es solo local. grok sessions search también consulta un índice remoto; esta herramienta no lo hace, por lo que una sesión que solo exista del lado del servidor no aparecerá.

Desarrollo

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 — parámetros de cada herramienta, texto de resultado, claves _meta y las condiciones exactas bajo las que se establece cada una.

• docs/security.md — qué autoriza registrar este servidor, qué otorga realmente cada nivel de permiso y qué sale de tu máquina.

• docs/engineering.md — cómo se escribe el código aquí: arquitectura, reglas de TypeScript funcional, disciplina de errores y efectos, política de pruebas y cobertura, flujo de trabajo de confirmaciones.

• CLAUDE.md — antecedentes del proyecto y el comportamiento verificado de la CLI grok del que depende este servidor.

• ROADMAP.md — hitos, criterios de aceptación e ideas que se midieron y rechazaron.

Publicación

Incrementa version en package.json, mueve la sección Unreleased de CHANGELOG.md bajo el nuevo encabezado de versión, confirma, luego:

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

.github/workflows/release.yml ejecuta la compuerta completa, se niega a publicar si la etiqueta y package.json no coinciden, instala el tarball empaquetado en un directorio temporal y ejecuta un initialize real contra el binario instalado, luego publica ese mismo archivo y crea un lanzamiento en GitHub.

No hay credenciales de publicación que gestionar. La autenticación es npm trusted publishing: el flujo de trabajo intercambia un token OIDC de corta duración, y npm genera la atestación de procedencia por su cuenta. La confianza está registrada contra este repositorio y el nombre del archivo de este flujo de trabajo, por lo que renombrar release.yml rompe la publicación — y npm no verifica la configuración hasta que se intenta publicar, donde el síntoma es ENEEDAUTH en lugar de algo que nombre la causa.

Licencia

MIT — consulta LICENSE.