grokbot-mcp

Grok Bot 앱의 봇에게 Claude Code 같은 MCP 클라이언트가 메시지를 보내고 답을 받게 하는 로컬 MCP 서버다. Cursor의 Bot Development Kit(BDK, @cursor/bdk)를 사용하며 macOS와 Windows에서 동작한다.

이 프로젝트는 개인이 만든 비공식 도구다. Cursor, Anysphere, xAI와 관계가 없다.

동작 구조

MCP 클라이언트 ──(HTTP, Bearer 토큰)──▶ 127.0.0.1:3790/v1/mcp ──▶ bdk serve ──(Cursor 계정)──▶ Grok Bot 봇
(Claude Code 등)                         이 프로젝트

• bdk serve는 BDK 프로젝트를 로컬 HTTP 서버로 실행하고, /v1/mcp 경로에 MCP 엔드포인트를 연다.
• BDK의 cursor-grokbot-agents 확장이 bdk login으로 로그인한 Cursor 계정의 Grok Bot 봇에 이름으로 메시지를 보낸다.
• 봇은 기존 대화, 메모리, 도구를 그대로 쓴다. MCP 클라이언트는 봇의 답장만 받는다.

요구 사항

• macOS 또는 Windows 10 이상
• Node.js 22.13 이상
• Grok Bot 봇이 있는 Cursor 계정
• 연결할 봇의 이름. Grok Bot 앱에 표시된 이름과 정확히 같아야 한다.

설치

1. 저장소를 내려받고 의존성을 설치한다.

   git clone <이 저장소 URL> grokbot-mcp
   cd grokbot-mcp
   npm ci
   

2. Cursor 계정으로 로그인한다. 브라우저가 열리면 Grok Bot 봇이 있는 계정으로 로그인한다.

   npx bdk login
   npx bdk whoami
   

3. 설정 파일을 만든다. .env.local은 git에 올라가지 않는다.

   macOS:

   cp .env.example .env.local
   

   Windows(PowerShell):

   Copy-Item .env.example .env.local
   

4. .env.local의 GROKBOT_AGENTS에 메시지를 보낼 봇 이름을 쉼표로 구분해 적는다.

   GROKBOT_AGENTS="일정 비서,글쓰기 도우미"
   

   주의: 이름을 틀리게 적으면 BDK가 그 이름으로 빈 봇을 새로 만든다. Grok Bot 앱에 표시된 이름을 그대로 복사한다. 목록이 비어 있으면 서버가 시작되지 않는다.

5. MCP 클라이언트가 인증에 쓸 토큰을 만든다. 토큰은 .bdk-token 파일에 저장되고, 이 파일은 git에 올라가지 않는다.

   npm run token
   

6. 설정을 검사하고 서버를 실행해 본다. Ctrl+C로 종료한다.

   npx bdk validate --dir .
   npm run serve
   

   grokbot-mcp listening 메시지가 나오면 정상이다.

자동 실행

컴퓨터에 로그인할 때 서버가 자동으로 켜지게 한다. 설치하면 서버가 바로 시작된다.

npm run autostart:install
npm run status

두 방식 모두 관리자 권한이 필요 없다.

자동 실행 등록에는 그 시점의 Node.js 실행 파일 경로가 저장된다. Node.js 버전을 바꾸거나 프로젝트 폴더를 옮기면 npm run autostart:install을 다시 실행한다.

MCP 클라이언트 등록

Claude Code

npm run mcp:claude

이 명령은 Claude Code의 사용자 범위에 grokbot이라는 이름으로 서버를 등록한다. 같은 이름의 기존 항목은 지우고 새로 등록한다. 등록한 뒤에는 Claude Code를 다시 시작한다.

claude mcp list

grokbot: http://127.0.0.1:3790/v1/mcp (HTTP) - ✔ Connected가 보이면 정상이다.

다른 MCP 클라이언트

Streamable HTTP를 지원하는 클라이언트라면 아래 값으로 등록한다. <토큰> 자리에는 .bdk-token 파일의 내용을 넣는다.

{
  "mcpServers": {
    "grokbot": {
      "url": "http://127.0.0.1:3790/v1/mcp",
      "headers": { "Authorization": "Bearer <토큰>" }
    }
  }
}

사용법

MCP 클라이언트에게 "글쓰기 도우미 봇에게 이번 주 게시글 초안을 부탁해"처럼 요청한다. 클라이언트는 call_tool로 봇에게 메시지를 보낸다.

{
  "toolName": "grokbot__ask",
  "input": { "agent": "글쓰기 도우미", "message": "..." }
}

봇은 MCP 클라이언트와의 대화 내용을 볼 수 없다. 메시지에는 누가 묻는지, 봇이 알아야 할 사실, 원하는 답의 형식을 모두 담는다.

제공 도구

이 서버의 MCP 도구는 ask, check, call_tool 세 가지다. 봇과 대화할 때는 call_tool로 아래 도구를 부른다.

MCP 도구 ask는 BDK 에이전트의 모델이 한 번 더 판단한 뒤 봇을 부른다. 그만큼 느리고 사용량이 더 들어서, 봇과 대화할 때는 call_tool을 쓰는 편이 낫다.

명령 목록

설정

.env.local에 아래 값을 둔다.

봇 목록이나 포트를 바꾼 뒤에는 서버를 다시 시작한다. 자동 실행을 쓰고 있으면 npm run autostart:install을 다시 실행한다. 포트를 바꾸면 npm run mcp:claude로 Claude Code 등록도 다시 한다.

파일 위치

로그 파일이 5MB를 넘으면 서버가 시작할 때 .log.1로 이름을 바꾸고 새 파일을 쓴다.

보안

• 서버는 127.0.0.1에서만 연결을 받는다. 같은 컴퓨터의 프로그램만 접속할 수 있다.
• 모든 요청에 .bdk-token의 토큰이 필요하다. 토큰 없이 요청하면 401을 반환한다.
• 이 서버에 접속할 수 있는 프로그램은 설정된 봇에게 메시지를 보내고, 봇의 진행 중인 작업을 멈출 수 있다. 토큰을 다른 사람과 공유하지 않는다.
• 토큰이 노출되면 npm run token -- --force로 바꾸고, 서버를 다시 시작한 뒤 클라이언트를 다시 등록한다.
• .env.local, .bdk-token, .agent-serve/는 .gitignore에 들어 있다. 커밋하기 전에 git status로 다시 확인한다.

문제 해결

제거

npm run autostart:uninstall
claude mcp remove grokbot -s user

그다음 프로젝트 폴더를 지운다.

테스트 환경

• macOS(Apple Silicon), Node.js 24, @cursor/bdk 0.2.25, Claude Code에서 검증했다.
• Windows 자동 실행 방식은 실제 Windows 환경에서 검증하지 않았다. 문제가 있으면 이슈로 알려 준다.

라이선스

이 저장소의 코드는 MIT 라이선스를 따른다.

의존성인 @cursor/bdk는 Cursor SDK License를 따르며, 사용 조건은 Cursor 이용 약관에 따른다. 이 저장소는 @cursor/bdk를 포함하지 않고, npm ci로 설치한다.