grokbot-mcp
README.md
<div align="center">
# grokbot-mcp
**English** | [日本語](README.ja.md)
A Cloudflare Worker that turns Grok Bot's (Cursor automation webhook) async callback into a synchronous MCP tool result.
[](https://github.com/YunosukeYoshino/grokbot-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://developers.cloudflare.com/workers/)
[](https://developers.cloudflare.com/durable-objects/)
[](https://modelcontextprotocol.io/)
[](https://zod.dev/)
[](https://vitest.dev/)
[](https://bun.sh/)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/YunosukeYoshino/grokbot-mcp)
</div>
```
MCP client ─ask_grokbot→ Worker ─POST {message, run_id, callback_url}→ Grok Bot
MCP client ←answer_text─ Worker ←POST /callbacks/{run_id}/{token} {answer}─ Grok Bot
```
## Structure
One run = one `Run` Durable Object. Waiters live in DO memory; state lives in DO storage.
| File | Role |
|---|---|
| `src/index.ts` | Worker entry. MCP tools, callback auth and intake, webhook dispatch |
| `src/oauth.ts` | `/mcp` authentication (API key or GitHub OAuth), GitHub sign-in, and the `/oauth/token` refresh guard |
| `src/util.ts` | Shared helpers (JSON responses, constant-time compare, SHA-256 hex) |
| `src/run.ts` | `Run` DO. Run state, waiting, TTL / retention alarms |
| `src/budget.ts` | `Budget` DO. Per-minute and daily counters for `ask_grokbot` |
| `src/oauth-state.ts` | `OAuthStateGuard` DO. Atomic one-time consumption of GitHub OAuth callback state |
| `src/oauth-guard.ts` | `OAuthAdmissionGuard` and `OAuthTokenGuard` DOs. Global/IP admission control, single-use code redemption, refresh retry and grant-revocation state |
| `patches/@cloudflare%2Fworkers-oauth-provider@1.1.0.patch` | Reproducible provider patch passing Worker Env and refresh-current status to the token callback |
| `src/config.ts` | Validation of vars (fail-closed when invalid) |
| `test/bridge.test.ts` | Integration tests on the Workers runtime (vitest-pool-workers) |
## MCP tools
Endpoint: `POST /mcp`. Authenticate with `Authorization: Bearer $MCP_API_KEY` (or `X-API-Key`), or with GitHub OAuth (see [Authentication](#authentication)).
| Tool | Purpose |
|---|---|
| `ask_grokbot(message, wait_seconds=60)` | Send to the webhook and wait for the callback. Returns `webhook_failed` if the webhook fails |
| `wait_for_grokbot_answer(run_id, timeout_seconds=60)` | Keep waiting on a pending run |
| `get_grokbot_run(run_id)` | Fetch a run |
| `cancel_run(run_id)` | Cancel a pending run |
`status`: `pending` / `answered` / `cancelled` / `expired`. Waits are capped by `MAX_WAIT_SECONDS` (max 300). All of `/mcp` is limited by `MCP_RATE_LIMITER` (60 req/min, per location) and returns 429 beyond that.
## Callback (Grok Bot → Worker)
- `callback_url` is `/callbacks/{run_id}/{token}`, where token is `HMAC-SHA256(CALLBACK_SIGNING_SECRET, run_id)`. The Worker verifies it before reading the body or waking a DO, so forged callbacks are rejected with 403 and incur no DO charges.
- POST `{"answer": "..."}` to `callback_url`. If `run_id` is included it must match the URL, otherwise 400 `run_id_mismatch`.
- The answer is extracted in the order `answer → message → content → text → output → result`; if none is present, the whole body as JSON becomes `answer_text`.
| Status | Meaning |
|---|---|
| 400 | `invalid_json` / `body_must_be_object` / `run_id_mismatch` |
| 403 | `invalid_token` |
| 404 | unknown run |
| 405 | non-POST |
| 409 | `already_answered` / `already_cancelled` |
| 410 | expired |
| 413 | body over 256KB |
| 503 | `callback_secret_not_configured` / `misconfigured` |
## Setup
**With the button:** Click Deploy to Cloudflare above. The repository is cloned into your GitHub / GitLab and deployed with its Durable Objects; the `OAUTH_KV` namespace is created automatically. Enter the secrets it asks for (`CURSOR_WEBHOOK_URL`, `CURSOR_WEBHOOK_API_KEY`, `MCP_API_KEY`, `CALLBACK_SIGNING_SECRET`) and you can connect right away with `MCP_API_KEY`. GitHub OAuth is optional and can be added later.
**With the CLI:**
```sh
bun install
wrangler secret put CURSOR_WEBHOOK_URL
wrangler secret put CURSOR_WEBHOOK_API_KEY
wrangler secret put MCP_API_KEY # openssl rand -hex 32
wrangler secret put CALLBACK_SIGNING_SECRET # openssl rand -hex 32 (a different value)
bun run deploy
```
`OAUTH_KV` has no fixed ID in `wrangler.jsonc`: the first deploy creates it and later deploys reuse the bound namespace.
### Authentication
`/mcp` accepts two kinds of credentials:
| Method | Needs | Use for |
|---|---|---|
| API key | `MCP_API_KEY` | Quick start, CLI harnesses (Claude Code, Cursor, curl) |
| GitHub OAuth | `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` / `GITHUB_OWNER_ID` | ChatGPT / dot and any Remote MCP OAuth client; per-client, expiring, revocable tokens |
Anyone holding `MCP_API_KEY` has full access, and the key cannot be revoked per client. Once every client uses OAuth, delete it (`wrangler secret delete MCP_API_KEY`) to make the bridge OAuth-only.
### GitHub OAuth setup (optional)
Sign-in uses a GitHub OAuth App and only the configured account can receive an MCP token. OAuth stays disabled (`/authorize` returns `503`) until all three values below are set.
1. Register a GitHub OAuth App with the Authorization callback URL `https://<worker-host>/oauth/github/callback`.
2. Set the app's Client ID, its Client Secret, and the numeric GitHub user ID allowed to use this bridge (`gh api user --jq .id`):
```sh
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put GITHUB_OWNER_ID
```
`GITHUB_CLIENT_ID` and `GITHUB_OWNER_ID` are not secret, so dashboard vars also work; `keep_vars` keeps them across deploys.
3. Add `https://<worker-host>/mcp` as a Remote MCP server in ChatGPT, dot, or another client and complete the GitHub sign-in/consent flow. The Worker publishes OAuth metadata and supports dynamic client registration.
| Item | Path |
|---|---|
| MCP server | `/mcp` |
| Protected-resource metadata | `/.well-known/oauth-protected-resource/mcp` |
| Authorization-server metadata | `/.well-known/oauth-authorization-server` |
| Authorization endpoint | `/authorize` |
| Token endpoint | `/oauth/token` |
| Dynamic client registration | `/oauth/register` |
| Scope | `grokbot:use` |
The client should start with the MCP server URL and discover OAuth metadata automatically. After GitHub consent, verify with `tools/list`; do not call `ask_grokbot` as a connectivity probe.
The `OAUTH_KV` binding stores OAuth client, authorization-code, and token state.
Unauthenticated OAuth routes are limited to 20 requests per IP per minute and 120 total per minute by strongly consistent Durable Object counters. The global and per-IP checks share one transaction; either rejection leaves both counters unchanged. OAuth POST bodies are capped at 64 KiB and oversized streams are cancelled. Downstream authorization codes are atomically consumed only after the provider validates client, redirect URI, resource, and PKCE. A definitive KV `429` before the grant write releases the code reservation for retry. A failed refresh releases its reservation when the grant still points at the presented token; once the grant may have rotated, it stays fail-closed. Refresh retries for the same request receive the identical token response for 10 seconds; the cached response is AES-GCM encrypted with a key derived from `CALLBACK_SIGNING_SECRET`, then the response body is removed while its hash history remains. Authenticated grant revocation also invalidates the retry cache. Reuse after that window revokes the grant and its token family. A grant is also revoked after 1,000 successful rotations to bound replay history; a cached retry is checked before that cap. If another refresh arrives while the first response is being committed, the server returns `503` with `Retry-After` so the client can retry.
Create a Grok Bot routine (trigger: Webhook) and put its POST URL and Key into `CURSOR_WEBHOOK_URL` / `CURSOR_WEBHOOK_API_KEY`. Example Instructions (kept in Japanese, as used with the routine; translate as you like):
```text
Webhook で起動したら、ペイロードを読む。test: true / 空ボディ / 依頼文が無いものは無視する。
message を依頼文として扱い、回答を作る。ペイロードの run_id をそのままエコーし、新しい ID を発行しない。
1. callback_url に JSON を POST する(Content-Type: application/json、User-Agent: grokbot-bridge-callback/1。
Authorization ヘッダは付けず、着信 webhook のキーは転送しない)。
ボディ: {"ok": true, "run_id": "<着信UUID>", "answer": "<回答全文>"}
2. callback_url には疎通確認・test の POST を送らない。最初の POST が必ず回答全文であること。
3. 再送は通信エラーまたは 5xx のときだけ 1 回。4xx は再送しない。
4. このチャットには「回答: <要約>」「run_id: …」「callback: HTTP <ステータス>」だけを投稿する。
```
In short, the routine must: echo the incoming `run_id`, POST the full answer to `callback_url` with no `Authorization` header, retry once only on network errors or 5xx, and never send probe/test POSTs.
- Set the User-Agent explicitly. Python-urllib's default UA is blocked by Cloudflare with 1010 (403) before reaching the Worker.
- The first callback to arrive finalizes the answer (later ones get 409). A probe POST would become the answer.
## Connecting MCP clients
The transport is Streamable HTTP (not stdio). URL: `https://<worker>.workers.dev/mcp`. The examples below use `MCP_API_KEY`. For OAuth clients (ChatGPT / dot, or Claude Code without `--header`), register only the URL and sign in with GitHub.
Claude Code:
```sh
claude mcp add --transport http grokbot https://<worker>.workers.dev/mcp \
--header "Authorization: Bearer $MCP_API_KEY"
```
JSON config (Claude Code's `.mcp.json` expands `${VAR}` from the environment; for clients that don't, write the value directly):
```json
{
"mcpServers": {
"grokbot": {
"type": "http",
"url": "https://<worker>.workers.dev/mcp",
"headers": { "Authorization": "Bearer ${MCP_API_KEY}" }
}
}
}
```
Cursor's `mcp.json` has the same shape (`type` may be omitted). Never commit the key to the repository.
Check the connection (you should see the four tool names):
```sh
curl -s https://<worker>.workers.dev/mcp \
-H "Authorization: Bearer $MCP_API_KEY" -H "content-type: application/json" \
-H "accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | grep -o '"name":"[a-z_]*"'
```
## Local development
Copy `.dev.vars.example` to `.dev.vars`, fill in the values, and run `bun run dev`. Tests: `bun run test`. Type check: `bun run typecheck`.
## Cost guardrails
| Guardrail | What it caps | Where |
| --- | --- | --- |
| `ASK_PER_MINUTE_LIMIT` (default 10) | Global per-minute `ask_grokbot` count. Beyond it: `rate_limited` + `retry_after_seconds` | `wrangler.jsonc` vars |
| `ASK_DAILY_LIMIT` (default 200, UTC day) | Daily `ask_grokbot` count. Beyond it: `daily_limit_reached` | same |
| `COST_KILL_SWITCH="1"` | Stops `ask_grokbot` immediately (`disabled`) | same (deploy after changing) |
| `MCP_RATE_LIMITER` (60/min) | All `/mcp` calls (including wait / get). Beyond it: 429. Approximate, per location | `wrangler.jsonc` ratelimits |
| HMAC callback token | Body reads and DO wake-ups from forged callbacks | `CALLBACK_SIGNING_SECRET` |
| `message` 20,000 chars / webhook timeout 10 s | Per-request input size and webhook wait | constants in `src/index.ts` |
| `MAX_WAIT_SECONDS` / `CALLBACK_TTL_SECONDS` / `RUN_RETENTION_SECONDS` | Single wait, deadline for the answer, retention after finish (0 = keep forever) | vars |
- Limits are counted exactly in a single DO, `Budget("global")`. A rejected ask creates neither a webhook call nor a Run DO.
- An ask whose webhook returned 4xx was not accepted, so its slot is refunded and the run is cancelled. A 5xx may mean the routine already started, so the Worker does not send a second webhook and leaves the run pending; a later callback can still store the answer, and the slot is not refunded. Timeouts (10 s) and connection drops still cancel the run and are not refunded.
- If a var is not a valid number, `/mcp` and callbacks return 503 `misconfigured` (the service never runs with limits disabled).
- Remaining worst case (estimate): even if the daily limit is used up every day at maximum wait, the DOs stay around 800 requests and 4,500 GB-s per day, within the Free daily allowance and the Paid monthly free allowance. Grok Bot / Cursor usage is capped at `ASK_DAILY_LIMIT` per day.
- Unauthenticated `/mcp` requests and callbacks with a bad token cost only Worker request charges ($0.30/M).
Set these up manually:
- Cloudflare dashboard → Billing → Billable Usage → budget alert (notifies only; it does not stop usage)
- A spend limit on the Cursor side
## License
[MIT](LICENSE). See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessNo recent community issues