grok-mcp-server

A remote MCP server that gives any Claude (or any MCP-compatible AI) access to xAI Grok's full surface area — live X (Twitter) search, web search, chat, image generation, vision, image editing, video generation, structured outputs, and reasoning — from anywhere. Your laptop, your phone, an automated routine running while you sleep.

Whether you're a developer building agents, an automation tinkerer wiring up workflows, or a creator who wants real-time data inside Claude — this is the same install.

Hosted on your own Cloudflare account. 4 commands. Stateless. 9 tools.

Built as part of auny-ai/claude-os — a multi-AI operating system being built in public. 🧡

What it does

Nine tools, all wrapping xAI's API. Each tool is general-purpose — the use cases below are just examples of what's possible.

Search + chat

x_search — Real-time X (Twitter) data

Searches X via xAI's native x_search backend. Returns posts with author handles, follower counts, engagement metrics (likes, retweets, replies, views), timestamps, embedded media, and quote-tweet context.

Supports the full X advanced search operator set: min_faves:N, min_retweets:N, filter:blue_verified, filter:verified, from:user, lang:en, since:YYYY-MM-DD, and the rest.

grok_web_search — Live web search with current information

General web search via Grok, with results synthesized into a coherent answer plus sources. Updated continuously — not subject to a model knowledge cutoff.

grok_chat — Grok as a model, not just a search tool

Plain text completion with Grok directly. Optional system prompt and model override. Useful when you want Grok's reasoning style or voice — not Claude's — for a specific output.

Vision + media

grok_image_generate — Text-to-image generation

Generate images from a text prompt using Grok Imagine (Quality Mode). Returns image URL(s). Good for mockups, social cards, thumbnails, brand visuals, and A/B variants. Up to 4 variations per call.

grok_image_understand — Multimodal vision

Pass an image URL and a question — get analysis back. Useful for screenshot debugging, content audits, alt-text generation, design feedback, and visual triage.

grok_image_edit — Text-prompt image editing

Pass an existing image URL and a description of the change — get an edited image back. Useful for iterating on brand visuals, generating color/style variants, and remixing existing assets.

grok_video_generate — Text-to-video / image-to-video

Generate short videos (up to 10 seconds, 720p) using Grok Imagine. Supports text-only prompts and image-to-video (start from a still). Returns the video URL. Note: video generation can take 20-60 seconds.

Structured outputs + reasoning

grok_structured_output — JSON-schema-enforced responses

Pass a prompt and a JSON Schema describing the expected structure. Returns parsed JSON matching the schema. Useful for reliable agent pipelines, data extraction from text, and ETL workflows where you need consistent output shape.

grok_reasoning — Deep analysis mode

Use Grok's reasoning mode for complex problems. Slower than grok_chat but produces more rigorous output. Effort level adjustable (low, medium, high). Good for strategy questions, multi-step analysis, debate prep, and technical reviews.

Related MCP server: Cloudflare Tavily Search MCP

Use cases

This is a general-purpose Grok wrapper that any MCP client can hit. The use cases stretch as far as Grok's capabilities themselves.

For developers

• Build agents that need real-time data. Most AI agents are blind to the last 24 hours. This gives any MCP-compatible agent live X + web search as a primitive.

• Multi-model orchestration. Claude as orchestrator, Grok as worker — cheaper, faster fan-out for tasks where Claude's reasoning isn't needed but recency or specific tone is.

• Live research inside Claude Code. When debugging a library, pulling current GitHub issues or recent docs without leaving your terminal.

• Cross-model evaluation. Pipe the same prompt to both models from inside Claude. Compare outputs in one workflow.

• Replace web-scraping infra. If you have brittle Puppeteer/Playwright setups pulling X data, this replaces them with a single MCP call. xAI handles the auth, rate limits, and rendering.

• Reliable data extraction with grok_structured_output. Define a schema once, get consistent JSON back. Drop the regex parsing.

• Programmatic asset generation. Spin up test mockups, design variants, or visual placeholders mid-pipeline with grok_image_generate.

• Vision-augmented agents. Use grok_image_understand to let agents reason over screenshots, design files, or live UI.

• Cheap real-time data layer for SaaS prototypes. Validate a "real-time market intelligence" or "X mention monitoring" feature in a weekend before building a proper backend.

For data, analytics, and research

• Pull X conversation data on any topic for analysis. Sentiment, volume, who's posting, engagement distribution.

• Track regulatory, policy, or industry developments as they happen, not as they hit Claude's training data months later.

• Academic research on social discourse — pull real-time data on how a topic is being discussed without writing a Twitter API client.

• Competitive intelligence pipelines — track competitor releases, hiring posts, customer complaints, pricing changes.

• Structured data extraction at scale. grok_structured_output reliably extracts entities, relationships, or features from unstructured text.

For automation and ops

• Wake up to a daily brief on topics you care about (Claude Routines + this MCP = autonomous personal news desk).

• Brand mention monitoring without paying for Brandwatch / Mention.com.

• Trend detection — surface things going viral in your niche before they peak.

• Lead-gen triage — find people publicly complaining about problems your product solves.

• Customer support reconnaissance — see what users are saying about your product before a support ticket exists.

• Auto-generate visual alerts. Trigger a grok_image_generate call to make a custom thumbnail when something noteworthy happens.

For creators

• Trending content radar — daily, autonomous research on what's going viral in your niche.

• Quote-tweet opportunity finder — surface high-engagement posts in your topics worth responding to.

• Audience research — see what your target audience actually talks about, not what you assume they care about.

• Source pulls for any output — articles, threads, presentations — without context-switching to a browser.

• Visual brand workflows. Generate banner art, social cards, post thumbnails, and video clips in one workflow without leaving Claude.

• Design feedback in chat. Drop a screenshot via grok_image_understand and ask "what's wrong with this design?" — get specific notes.

• Multi-step content production: grok_web_search → research, grok_chat → draft, grok_image_generate → visual, grok_video_generate → clip. One pipeline, one chat.

For everyone

• Get current info into Claude. Anything that happened after Claude's knowledge cutoff is reachable through this — without leaving your Claude chat.

• Fact-check Claude's outputs against live web data.

• Cross-reference claims with both web sources and live X discussion.

• Generate visuals you can actually use — Grok Imagine Quality Mode produces production-ready images.

What you'll need

• An xAI API key — get one at https://console.x.ai/

• A Cloudflare account (free, takes 30 seconds to set up if you don't have one)

• A terminal you're comfortable pasting commands into (macOS Terminal, iTerm, Windows Terminal — anything works)

• Node 18+ installed — download here if you don't have it

• ~5 minutes

A note on cost

This repo doesn't bill you for anything. You're deploying your own copy of the server, paying xAI directly for Grok usage, and paying Cloudflare nothing for typical use.

• xAI: you pay xAI for Grok API calls, billed to whatever payment method is on your xAI account (console.x.ai). Image and video generation are more expensive than text — check pricing before automating high-volume creative workflows.

• Cloudflare: Workers free tier = 100k requests/day, more than you'll hit

• Me: zero — no telemetry, no proxying, no relay. The code runs on your account, your key, your bill.

Install in 5 commands

git clone https://github.com/auny-ai/grok-mcp-server.git
cd grok-mcp-server
npm install
npx wrangler login

(wrangler login opens a browser tab — authorize Cloudflare access once.)

Set your xAI key and generate your own auth secret as Worker secrets, then deploy:

npx wrangler secret put XAI_API_KEY
# (paste your xai-... key when prompted)

printf '%s' "$(openssl rand -hex 32)" | npx wrangler secret put AUTH_SECRET
# generates and sets your own random secret — this gates the endpoint below

npx wrangler deploy

You'll see something like:

Deployed grok-mcp-server triggers
  https://grok-mcp-server.<your-account>.workers.dev

Done. Your Worker is live — and gated. Unlike v1, the /mcp endpoint now fails closed: it refuses every request (503) until AUTH_SECRET is set, and 401s any request that doesn't present a valid credential. See AGENTS.md for the full install contract and docs/ARCHITECTURE.md for how the auth gate works.

Verify both auth paths and the tool count in one shot:

AUTH_SECRET=<the secret you generated> \
MCP_URL=https://grok-mcp-server.<your-account>.workers.dev \
./verify.sh

Should end in PASS.

Connect to Claude

The endpoint is gated behind AUTH_SECRET. There are two ways to authenticate, matching the two client shapes:

In Claude.ai (Routines, Projects, custom integrations)

1. Settings → Connectors → Add custom connector

2. Name: Grok

3. URL: https://grok-mcp-server.<your-account>.workers.dev/mcp

4. Save, then Connect — this triggers a one-click OAuth/PKCE handshake against /oauth/authorize and /oauth/token. You never paste the raw secret into claude.ai; the connector receives a signed, expiring token.

The nine tools are now available to any chat or Routine where you enable the Grok connector.

In Claude Desktop / Claude Code

These are headless clients, so they use the static-bearer path directly. Add to your MCP config file:

{
  "mcpServers": {
    "grok": {
      "url": "https://grok-mcp-server.<your-account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your AUTH_SECRET>"
      }
    }
  }
}

Or with the Claude Code CLI:

claude mcp add grok --transport http \
  https://grok-mcp-server.<your-account>.workers.dev/mcp \
  --header "Authorization: Bearer <your AUTH_SECRET>"

Restart your Claude client and the tools become available.

Tools reference

x_search

Search X (Twitter) via xAI's native X search tool.

Inputs:

• query (string, required) — what to search for

• context (string, optional) — narrows the focus

Example call (from inside Claude):

use x_search to find recent posts about "Claude Code" with min_faves:500 filter:blue_verified

X search operators that work here: min_faves:N, min_retweets:N, filter:blue_verified, filter:verified, from:user, lang:en, since:YYYY-MM-DD, and most other advanced search operators.

grok_web_search

General web search via Grok.

Inputs:

• query (string, required) — what to search for

• context (string, optional) — narrows the focus

grok_chat

Plain text Grok completion.

Inputs:

• prompt (string, required) — user prompt

• system (string, optional) — system prompt

• model (string, optional) — model override (default: grok-4.3)

grok_image_generate

Generate images from a text prompt.

Inputs:

• prompt (string, required) — description of the image

• n (integer 1-4, optional) — number of variations (default: 1)

• model (string, optional) — model override (default: grok-imagine-image-quality)

Returns: image URL(s). For multiple, returns a numbered list.

Example call:

use grok_image_generate to make a cyberpunk-style poster of a black cat sitting on a glowing keyboard, n=2

grok_image_understand

Analyze an image using Grok's vision capabilities.

Inputs:

• image_url (string, required) — URL of the image (jpg, jpeg, or png)

• prompt (string, required) — what you want to know about it

• model (string, optional) — model override (default: grok-4.3)

Example call:

use grok_image_understand on https://example.com/dashboard.png — what UX issues do you see?

grok_image_edit

Edit an existing image via a text prompt.

Inputs:

• image_url (string, required) — URL of the source image

• prompt (string, required) — description of the edit

• model (string, optional) — model override (default: grok-imagine-image-quality)

Returns: edited image URL.

Example call:

use grok_image_edit on https://example.com/banner.jpg — change the background to a sunset and add a small moon in the upper right

grok_video_generate

Generate a short video (up to 10 seconds, 720p) from text or an image.

Inputs:

• prompt (string, required) — description of the video

• image_url (string, optional) — starting image for image-to-video

• model (string, optional) — model override (default: grok-imagine-video)

Returns: video URL. Note: generation typically takes 20-60 seconds.

Example call:

use grok_video_generate with the prompt "ocean waves crashing on rocks at sunset, slow motion"

grok_structured_output

Get a JSON-schema-enforced response from Grok.

Inputs:

• prompt (string, required) — what you want Grok to produce

• schema (object or stringified JSON, required) — JSON Schema describing the expected response shape

• system (string, optional) — system prompt

• model (string, optional) — model override (default: grok-4.3)

Returns: JSON matching the provided schema.

Example call:

use grok_structured_output to extract people, companies, and locations from this text. Schema: { type: "object", properties: { people: { type: "array", items: { type: "string" } }, companies: { ... }, locations: { ... } }, required: ["people", "companies", "locations"] }

grok_reasoning

Use Grok's reasoning mode for deep analysis.

Inputs:

• prompt (string, required) — the question or problem

• effort ("low" | "medium" | "high", optional) — reasoning depth (default: medium)

• system (string, optional) — system prompt

• model (string, optional) — model override (default: grok-4.3)

Example call:

use grok_reasoning with effort=high to analyze whether building a personal MCP server is worth the maintenance cost vs using existing connectors

Local development

For testing changes before deploying:

1. Copy .env.example to .dev.vars (gitignored) in the repo root and fill in your own values:

   XAI_API_KEY="xai-..."
   AUTH_SECRET="<output of: openssl rand -hex 32>"

2. Run the dev server:

   npm run dev

3. The server is now at http://localhost:8787.

Architecture

MCP client (Claude / Cursor / anything)
        │
        │  Streamable HTTP MCP, Bearer auth (static secret or OAuth token)
        ▼
Cloudflare Worker (this repo)
        │  gateMcp() — fails closed without AUTH_SECRET
        │
        │  Bearer auth via Worker secret
        ▼
xAI Grok API (api.x.ai/v1)
  ├── /responses       — chat, search, vision, structured, reasoning
  ├── /images/generations — image gen
  ├── /images/edits    — image edit
  └── /videos/generations — video gen

• Transport: MCP over Streamable HTTP at /mcp

• State: stateless per request, no Durable Objects, no session memory

• Auth (server → xAI): Bearer token via XAI_API_KEY Worker secret

• Auth (client → server): gated by AUTH_SECRET (src/auth.ts), fail-closed. Two routes: a static bearer for headless clients (Claude Code), and OAuth 2.0 + PKCE with stateless HMAC-signed tokens for the claude.ai connector. No KV, no database — see docs/ARCHITECTURE.md for the full request-routing and token-verification walkthrough.

See docs/RUNBOOK.md for rotating secrets, redeploying, and common failure modes.

Adding tools

src/index.ts defines tools using the MCP SDK's server.tool() pattern:

server.tool(
  "tool_name",
  "Tool description for the LLM",
  { param: z.string() },
  async ({ param }) => {
    // your logic here
    return { content: [{ type: "text", text: "..." }] };
  }
);

All tools share a single xaiFetch(env, path, body) helper for hitting the xAI API. To add a new tool wrapping a different xAI endpoint, just pass the endpoint path and request body to xaiFetch.

Add a new tool, run npm run dev to test locally, then npx wrangler deploy to ship.

Worker name

By default the Worker deploys as grok-mcp-server. To rename it, edit the name field in wrangler.jsonc before deploying:

{
  "name": "grok-mcp-server"  // change this
}

Each Cloudflare account has its own namespace, so grok-mcp-server.<you>.workers.dev won't conflict with anyone else's deploy.

Why does this exist?

Most MCP servers run locally on your machine. They work great — until you want to use Claude somewhere that isn't your laptop.

The moment you do:

• Claude Routines can't reach a local server — they run in Anthropic's cloud, not on your machine

• Claude on your phone can't talk to your desktop

• Any agent or automation running anywhere but your laptop is locked out

• Sharing your setup means asking someone to install Node, clone the repo, and keep their laptop awake

A hosted MCP fixes all of that. The server lives on the open internet — on your Cloudflare account, behind your secret. Claude can reach it from anywhere. Same tools, same key, same behavior, from any device or workflow.

If you're a developer: this is the production pattern. Local for prototyping, hosted for shipping. The same code runs in dev and prod.

If you're a creator or automation user: this is what lets the magic follow you off your laptop. Your routines run while you sleep. Your phone has the same powers as your desktop. Your context is portable.

The longer version — the architecture, the trade-offs, the templates for building this kind of context system around Claude — lives in CLAUDE.md is the Starting Point. Worth a read if you're thinking about building a system around Claude, not just chatting with it.

Changelog

v1.2.0 — Added fail-closed dual-route inbound auth (src/auth.ts): a static-bearer path for headless clients and self-contained OAuth 2.0 + PKCE for the claude.ai connector, both backed by one AUTH_SECRET. No KV, no database — stateless HMAC-signed tokens. Added verify.sh, mcp.json, AGENTS.md, .env.example, and docs/.

v1.1.0 — Added 6 new tools: grok_image_generate, grok_image_understand, grok_image_edit, grok_video_generate, grok_structured_output, grok_reasoning. Refactored to a shared xaiFetch helper. Server now exposes Grok's full surface area.

v1.0.0 — Initial release. Three tools: x_search, grok_web_search, grok_chat. Stateless MCP server on Cloudflare Workers.

License

MIT. Fork it, ship it, change it, sell it.

Related

• auny-ai/claude-os — the multi-AI operating system this is part of

• Cloudflare Agents SDK docs — the SDK underneath this

• Model Context Protocol — the standard this implements

• xAI API docs — the underlying API this wraps

If you build something interesting on top of this, open an issue or tag me on X. 🧡