# 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. 저장소를 내려받고 의존성을 설치한다.

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

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

   ```bash
   npx bdk login
   npx bdk whoami
   ```

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

   macOS:

   ```bash
   cp .env.example .env.local
   ```

   Windows(PowerShell):

   ```powershell
   Copy-Item .env.example .env.local
   ```

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

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

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

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

   ```bash
   npm run token
   ```

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

   ```bash
   npx bdk validate --dir .
   npm run serve
   ```

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

## 자동 실행

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

```bash
npm run autostart:install
npm run status
```

| OS | 등록 방식 | 서버가 종료되면 |
|---|---|---|
| macOS | LaunchAgent `~/Library/LaunchAgents/local.grokbot-mcp.plist` | launchd가 다시 실행한다 |
| Windows | 시작프로그램 폴더의 `grokbot-mcp.vbs`. 창 없이 실행된다 | 보조 스크립트가 15초 뒤 다시 실행한다 |

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

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

## MCP 클라이언트 등록

### Claude Code

```bash
npm run mcp:claude
```

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

```bash
claude mcp list
```

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

### 다른 MCP 클라이언트

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

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

## 사용법

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

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

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

### 제공 도구

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

| `toolName` | 하는 일 |
|---|---|
| `grokbot__list` | 설정된 봇과 이미 연락한 봇을 보여 준다. 메시지는 보내지 않는다 |
| `grokbot__ask` | 봇에게 메시지를 보내고 답을 기다린다. 기본 대기 시간은 120초이고, 최대 600초다 |
| `grokbot__check` | 대기 시간 안에 끝나지 않은 답(`status: "running"`)을 이어서 받는다 |
| `grokbot__interrupt` | 봇이 진행 중인 작업을 멈춘다. 대화와 메모리는 남는다 |

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

## 명령 목록

| 명령 | 하는 일 |
|---|---|
| `npm run token` | `.bdk-token`을 만든다. `npm run token -- --force`는 토큰을 새로 바꾼다 |
| `npm run serve` | 서버를 현재 터미널에서 실행한다 |
| `npm run status` | 자동 실행 등록 여부와 서버 응답 여부를 보여 준다 |
| `npm run autostart:install` | 자동 실행을 등록하고 서버를 시작한다 |
| `npm run autostart:uninstall` | 자동 실행을 해제하고 서버를 종료한다 |
| `npm run mcp:claude` | Claude Code에 서버를 등록한다 |

## 설정

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

| 이름 | 필수 | 설명 |
|---|---|---|
| `GROKBOT_AGENTS` | 예 | 메시지를 보낼 수 있는 봇 이름 목록. 쉼표로 구분한다 |
| `GROKBOT_MCP_PORT` | 아니요 | 서버 포트. 기본값은 `3790`이다 |

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

## 파일 위치

| 항목 | macOS | Windows |
|---|---|---|
| 로그 | `~/Library/Logs/grokbot-mcp/grokbot-mcp.log` | `%LOCALAPPDATA%\grokbot-mcp\grokbot-mcp.log` |
| 자동 실행 | `~/Library/LaunchAgents/local.grokbot-mcp.plist` | `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\grokbot-mcp.vbs` |
| BDK 로그인 정보 | `npx bdk whoami`로 확인 | `npx bdk whoami`로 확인 |

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

## 보안

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

## 문제 해결

| 증상 | 원인과 해결 |
|---|---|
| `GROKBOT_AGENTS is empty` | `.env.local`이 없거나 `GROKBOT_AGENTS`가 비어 있다. 설치 3~4단계를 다시 확인한다 |
| `missing .bdk-token` | `npm run token`을 실행한다 |
| 결과에 `created: true`가 있다 | 그 이름의 봇이 계정에 없어서 빈 봇이 새로 생겼다. 이름 철자와 `npx bdk whoami` 계정을 확인하고, 필요하면 Grok Bot 앱에서 새로 생긴 봇을 지운다 |
| `claude mcp list`에서 연결에 실패한다 | `npm run status`로 서버 상태를 확인하고, 로그 파일을 본다 |
| 포트가 이미 사용 중이다 | `.env.local`에서 `GROKBOT_MCP_PORT`를 바꾸고 서버와 클라이언트 등록을 다시 한다 |
| 봇이 바쁘다는 응답이 온다 | 봇이 이전 작업을 처리하고 있다. 끝난 뒤 다시 보내거나 `grokbot__check`로 기다린다 |

## 제거

```bash
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 라이선스](LICENSE)를 따른다.

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