grok-build-mcp-server

Сервер MCP stdio, который предоставляет CLI Grok Build (grok) в виде инструментов, которые можно вызывать из Claude Code, Cursor, VS Code или любого другого MCP-клиента.

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

Это тонкая обёртка процесса. Она не перереализует логику агента и не общается напрямую с xAI API — весь интеллект остаётся в CLI grok. Что добавляет этот сервер — это точное построение аргументов, надёжный контроль процессов и чистый вывод в формате MCP.

Статус: 0.2.2. Поверхность инструментов завершена. Сервер запускает реальных безголовых агентов Grok в фоновом режиме или в фоне, передаёт прогресс во время их работы, останавливает выполнение по запросу, просматривает git-диффы, исследует вопросы в интернете, выводит список сессий, созданных этими запусками, и сообщает о сессиях, использовании и стоимости. См. CHANGELOG.md о том, что было выпущено, и ROADMAP.md о том, что было рассмотрено и отклонено.

Progress

Длительный запуск агента виден в процессе, а не молчаливое ожидание, заканчивающееся стеной текста. Когда ваш клиент отправляет 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

Requirements

• CLI Grok Build 1.0.0 или новее, аутентифицирован (grok models должен выполняться успешно)

• Node.js 22 или новее

Если grok нет в вашем PATH, установите GROK_BINARY на полный путь при регистрации сервера.

Install

Claude Code

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

Затем в Claude Code:

> use the grok-build check tool

check сообщает разрешённый бинарник, версию CLI, аутентифицированы ли вы, и активный потолок разрешений. Если он доволен, остальное будет работать.

Any other MCP client

Сервер говорит на MCP через stdio и не принимает собственных аргументов:

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

VS Code и Cursor принимают значки установки в верхней части этой страницы, которые несут именно эту конфигурацию.

Клиенты, устанавливающие из MCP Registry, знают этот сервер как io.github.Nuruvala/grok-build-mcp-server. Запись в реестре публикуется с того же тега, что и npm-релиз, и указывает на тот же пакет.

If npx cannot find the server

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

Permissions

Запуски Grok через этот сервер по умолчанию только для чтения: --permission-mode plan с --sandbox read-only. Ничто не может изменить ваши файлы, пока вы не разрешите.

Разрешение — это потолок, устанавливаемый один раз при регистрации сервера, а не запрос при каждом вызове. Три уровня:

Чтобы разрешить 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 те же полномочия, что и у вас.

Вызов, запрашивающий больше потолка, отклоняется, а не молча понижается — ограниченный запуск сообщил бы об успехе, ничего не меняя, что хуже, чем чёткая ошибка.

Environment variables

Собственные переменные Grok (XAI_API_KEY, GROK_HOME, GROK_DISABLE_AUTOUPDATER) передаются дочернему процессу без изменений.

Tools

review

Дифф собирается в процессе и встраивается в подсказку, чтобы модель не тратила шаги на повторное обнаружение того, что она должна просмотреть.

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

Цели: uncommitted, base: "<ref>" (дифф merge-base, так что коммиты, попавшие на базу после вашего ответвления, не приписываются вам) или commit: "<sha>". Если не указано, определяется автоматически: дифф с upstream, когда ваша ветка впереди, иначе рабочее дерево — и он сообщает, что выбрал, а не угадывает молча.

review всегда только для чтения, независимо от того, что разрешает GROK_MCP_PERMISSION_CEILING. Он не принимает аргументов permission, write или yolo, потому что ревью, которое редактирует просматриваемый код, никогда не является желаемым.

Передайте structured: true для машиночитаемых результатов (severity, file, line, summary, rationale) в _meta.findings, проверенных перед тем, как вы их увидите.

Две разные вещи могут пойти не так, и они сообщаются по-разному, а не смешиваются:

• Запуск никогда не завершился — он был прерван или закончился без выдачи результатов. Ревью нет, поэтому вызов имеет 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) формируют подсказку — CLI grok не имеет флагов ни для того, ни для другого, и ни один параметр не притворяется иначе. Они работают: один и тот же вопрос, заданный на basic, выполнил один поиск по двум страницам, а на full — шесть поисков по трём, что в два с половиной раза дороже.

Результат сообщает вам, что было фактически найдено, а не только то, что написала модель:

[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

Длительный запуск агента не обязан занимать ваш клиент. Передайте background: true в grok, review или websearch, и вызов сразу вернёт 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, по одному каталогу на запуск.

status для завершённого запуска возвращает то же, что вернул бы синхронный вызов — тот же текст, те же метаданные, тот же флаг ошибки. Фоновый режим — это транспорт для вызова инструмента, а не вторая реализация. Пока запуск активен, вы получаете его состояние, прошедшее время, оба идентификатора процесса и хвост журнала прогресса; waitMs блокирует до двух минут и пересылает уведомления о прогрессе по мере поступления. Тайм-аут ожидания не является ошибкой.

Два вида нечестности исключены архитектурно. Запуск, чей рабочий процесс больше не существует, помечается как abandoned, а не как всё ещё работающий — машина перезагрузилась или кто-то его убил. А запуск, завершившийся раньше времени, помечается соответствующим образом:

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

Валидация всё ещё выполняется до того, как вы получите runId: запрос, превышающий GROK_MCP_PERMISSION_CEILING, или противоречивая пара флагов сессии отклоняется как неудачный вызов, а не принимается, а затем терпит неудачу в процессе, за которым никто не наблюдает.

stop завершает запуск досрочно. Он отправляет сигнал SIGTERM всей группе процессов рабочего — рабочему и порождённому им процессу grok, а затем SIGKILL, если этого недостаточно. Остановка уже завершённого запуска не является ошибкой, равно как и остановка того, который завершился за мгновение до вашего вызова.

Остановка, которая не смогла убить дерево процессов, сообщается как сбой, а не как остановленный запуск. Если нечего сигнализировать, или убийство отклонено, или дерево переживает SIGKILL, запуск остаётся в статусе running, а вызов возвращает ошибку с указанием pid. Запись cancelled рядом с живым процессом была бы более аккуратным ответом, но бесполезным.

Запуск, который вы остановили на полпути, обычно уже произвёл что-то стоящее, и частичный результат, и идентификатор сессии сохраняются:

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 сообщает идентификатор сессии только когда запуск достигает своего конца, чего остановленный запуск никогда не делает — поэтому этот идентификатор читается из собственного хранилища сессий CLI, а не восстанавливается. _meta.sessionIdSource сообщает вам, какой из них у вас есть. Если два запуска в одном каталоге могут соответствовать, вы получаете идентификаторы кандидатов и никакой команды возобновления: возобновление неправильной сессии продолжает чужую работу.

sessions

Каждый запуск Grok оставляет сессию на диске, и каждый идентификатор сессии, сообщаемый этим сервером, может быть возобновлён позже — из любого каталога, вами в терминале или другим вызовом инструмента.

> 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-клиента и вашей машины. Передайте id для одной сессии, query для поиска без учёта регистра по заголовкам, первым запросам и идентификаторам, 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 — предыстория проекта и проверенное поведение CLI grok, от которого зависит этот сервер.

• ROADMAP.md — вехи, критерии приёмки и идеи, которые были оценены и отвергнуты.

Релиз

Увеличьте version в package.json, переместите раздел Unreleased из CHANGELOG.md под новый заголовок версии, закоммитьте, затем:

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.