grokbot-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
grokbot-mcp
English | 日本語
A Cloudflare Worker that turns Grok Bot's (Cursor automation webhook) async callback into a synchronous MCP tool result.
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 BotStructure
One run = one Run Durable Object. Waiters live in DO memory; state lives in DO storage.
File | Role |
| Worker entry. MCP tools, callback auth and intake, webhook dispatch |
|
|
| Shared helpers (JSON responses, constant-time compare, SHA-256 hex) |
|
|
|
|
|
|
|
|
| Reproducible provider patch passing Worker Env and refresh-current status to the token callback |
| Validation of vars (fail-closed when invalid) |
| Integration tests on the Workers runtime (vitest-pool-workers) |
Related MCP server: Grok Ally
MCP tools
Endpoint: POST /mcp. Authenticate with Authorization: Bearer $MCP_API_KEY (or X-API-Key), or with GitHub OAuth (see Authentication).
Tool | Purpose |
| Send to the webhook and wait for the callback. Returns |
| Keep waiting on a pending run |
| Fetch a run |
| 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_urlis/callbacks/{run_id}/{token}, where token isHMAC-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": "..."}tocallback_url. Ifrun_idis included it must match the URL, otherwise 400run_id_mismatch.The answer is extracted in the order
answer → message → content → text → output → result; if none is present, the whole body as JSON becomesanswer_text.
Status | Meaning |
400 |
|
403 |
|
404 | unknown run |
405 | non-POST |
409 |
|
410 | expired |
413 | body over 256KB |
503 |
|
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:
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 deployOAUTH_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 |
| Quick start, CLI harnesses (Claude Code, Cursor, curl) |
GitHub OAuth |
| 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.
Register a GitHub OAuth App with the Authorization callback URL
https://<worker-host>/oauth/github/callback.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):wrangler secret put GITHUB_CLIENT_ID wrangler secret put GITHUB_CLIENT_SECRET wrangler secret put GITHUB_OWNER_IDGITHUB_CLIENT_IDandGITHUB_OWNER_IDare not secret, so dashboard vars also work;keep_varskeeps them across deploys.Add
https://<worker-host>/mcpas 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 |
|
Protected-resource metadata |
|
Authorization-server metadata |
|
Authorization endpoint |
|
Token endpoint |
|
Dynamic client registration |
|
Scope |
|
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):
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:
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):
{
"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):
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 |
| Global per-minute |
|
| Daily | same |
| Stops | same (deploy after changing) |
| All |
|
HMAC callback token | Body reads and DO wake-ups from forged callbacks |
|
| Per-request input size and webhook wait | constants in |
| 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,
/mcpand callbacks return 503misconfigured(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_LIMITper day.Unauthenticated
/mcprequests 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. See SECURITY.md for reporting vulnerabilities.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Call AI by role, not by model: tiered AI gateway over REST and MCP.
Build and run AI workflows, agents, data tables and 1000+ API integrations from any MCP client.
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
Hosted MCP runtime where your agent publishes its own tools by tool call and keeps working.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI agents to manage Grok Bots through MCP: create, list, search, and delete bots, send and receive messages, read conversation transcripts, search message history, and check usage.113MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients like Codex and Claude Code to start or continue conversations with Grok Build, track progress, read completed answers, and cancel running turns using an existing Grok login.1Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables external MCP clients to invoke governed tools with schema validation, budgets, policy checks, human approval for side-effecting actions, and prompt-injection quarantine.MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients to ask a Grok Bot routine a question and receive the answer as a synchronous tool result, bridging the bot's asynchronous webhook callback.5MIT