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 diff를 검토하고, 웹에서 질문을 조사하며, 해당 실행이 생성한 세션을 나열하고, 세션, 사용량 및 비용을 보고합니다. 출시된 내용은 CHANGELOG.md를, 고려 및 기각된 내용은 ROADMAP.md를 참조하세요.

진행 상황

긴 에이전트 실행은 텍스트 벽으로 끝나는 조용한 대기가 아니라 실행 중에 볼 수 있습니다. 클라이언트가 progressToken을 보내면 서버는 --output-format streaming-json으로 Grok을 실행하고 이벤트당 알림을 전달합니다.

#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 레지스트리에서 설치하는 클라이언트는 이 서버를 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입니다. 사용자가 허용할 때까지 파일을 수정할 수 없습니다.

권한은 상한이며, 호출할 때마다 프롬프트가 표시되는 것이 아니라 서버를 등록할 때 한 번 설정됩니다. 세 가지 수준이 있습니다.

Grok이 편집할 수 있도록 하려면:

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

이미 MCP 클라이언트를 전체 승인으로 실행 중이고 위임된 Grok 실행도 동등하게 무인 상태가 되기를 원하는 경우에만 full을 사용하세요. 생성된 grok 프로세스에 사용자와 동일한 권한을 부여합니다.

상한을 초과하는 요청은 자동으로 낮춰지지 않고 거부됩니다. 제한된 실행은 아무것도 변경하지 않으면서 성공을 보고하므로 명확한 오류보다 더 나쁩니다.

환경 변수

Grok의 자체 변수(XAI_API_KEY, GROK_HOME, GROK_DISABLE_AUTOUPDATER)는 자식 프로세스에 그대로 전달됩니다.

도구

review

diff는 프로세스 내에서 수집되어 프롬프트에 포함되므로 모델이 검토해야 할 대상을 다시 발견하는 데 시간을 소비하지 않습니다.

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

대상은 uncommitted, base: "<ref>"(병합 기준 diff이므로 분기 후 베이스에 도착한 커밋은 사용자에게 귀속되지 않음) 또는 commit: "<sha>"입니다. 아무것도 제공되지 않으면 자동 감지합니다: 분기가 앞서 있을 때는 업스트림 diff, 그렇지 않으면 작업 트리이며, 조용히 추측하는 대신 어떤 것을 선택했는지 알려줍니다.

review는 GROK_MCP_PERMISSION_CEILING이 허용하는 것과 관계없이 항상 읽기 전용입니다. 검토 중인 코드를 편집하는 검토는 원하는 것이 아니므로 permission, write 또는 yolo 인수를 사용하지 않습니다.

구조화된 결과를 위해 structured: true를 전달하면 검증된 후 _meta.findings에 머신 판독 가능한 결과(severity, file, line, summary, rationale)가 제공됩니다.

두 가지 다른 문제가 발생할 수 있으며, 혼동되지 않고 다르게 보고됩니다.

• 실행이 완료되지 않음 — 중단되거나 결과를 생성하지 않고 종료되었습니다. 검토가 없으므로 호출은 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에서 동일한 질문을 했을 때 두 페이지에 걸쳐 한 번 검색했고, 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

긴 에이전트 실행이 반드시 클라이언트를 점유할 필요는 없습니다. 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 아래에 저장되며, 각 실행마다 하나의 디렉토리가 생성됩니다.

완료된 실행에 대한 status는 동기 호출이 반환했을 값과 동일합니다 — 동일한 텍스트, 동일한 메타데이터, 동일한 오류 플래그. 백그라운드는 툴 호출을 위한 전송 방식일 뿐, 툴의 두 번째 구현이 아닙니다. 실행이 진행 중인 동안에는 해당 상태, 경과 시간, 두 프로세스 ID, 그리고 진행 로그의 마지막 부분을 얻을 수 있습니다. waitMs는 최대 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를 제공하고 재개 명령은 제공하지 않습니다: 잘못된 세션을 재개하면 다른 사람의 작업을 계속하게 됩니다.

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 클라이언트, 그리고 머신의 재시작에도 유지됩니다. 하나의 세션에 대해 id를 전달하거나, 제목, 첫 프롬프트, 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 — 프로젝트 배경 및 이 서버가 의존하는 검증된 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이 자체적으로 출처 증명(provenance attestation)을 생성합니다. 신뢰는 이 저장소와 이 워크플로의 파일 이름에 등록되므로, release.yml의 이름을 바꾸면 게시가 중단됩니다. npm은 게시가 시도될 때까지 구성을 확인하지 않으며, 증상은 원인을 명명하지 않는 ENEEDAUTH입니다.

라이선스

MIT — LICENSE 참조.