bluex-mcp

📖 中文文档

Live X (Twitter) + web search MCP server — powered by your locally logged-in Grok CLI, running on your X Premium / SuperGrok subscription quota.

Your coding agent doesn't know what shipped this morning. It doesn't see the X thread where ten other developers are hitting the same bug. It can't watch the keynote that started 20 minutes ago, can't follow the leak about your competitor's pricing, can't tell you what @karpathy posted this week.

bluex-mcp closes that gap. If you pay for X Premium ($8/mo), X Premium+ ($40/mo), or SuperGrok ($30/mo), you already have first-class live X + web access through Grok. This is a thin MCP server that exposes it to Claude Code, Codex, Cursor, Claude Desktop, and any other MCP client — by driving your locally logged-in grok CLI. Usage counts against your existing plan.

---

Why

Other Grok MCP servers use the xAI API. You need a key, a funded account, and you pay per token. bluex-mcp takes a different path.

	xAI API (most Grok MCPs)	bluex-mcp
Auth	XAI_API_KEY	Your logged-in grok CLI
Cost	Pay-per-token API billing	$0 — runs on your subscription's quota
Live X access	Yes	Yes (same Grok)
Setup	Get a key, fund a balance	grok login once
Footprint	—	2 search tools + 1 health check

If you don't already pay for Grok, an API-based MCP is the right call. If you do, bluex-mcp makes that subscription do double duty.

---

Quick start

npm install -g github:Derek-Wong213/bluex-mcp
grok login
bluex-mcp health

Wire it into your agent:

# Claude Code
claude mcp add bluex -- bluex-mcp

# Codex (~/.codex/config.toml)
[mcp_servers.bluex]
command = "bluex-mcp"

// Cursor / Claude Desktop (mcp.json)
{ "mcpServers": { "bluex": { "command": "bluex-mcp" } } }

Restart. Ask "search X for what people are saying about <topic> in the last hour" — it routes through bluex_x_search.

---

What people actually ask it

Each example is a real moment where an agent without live X access just stalls. They all route through the two search tools below.

Breaking AI / model release, first signal. "What did @AnthropicAI just announce? Last hour." The newest model dropped on X 30 minutes ago; your agent's knowledge cutoff is six weeks behind. → bluex_x_search · recency=1hr · from:@handle

A library or CLI just broke and the docs are clueless. "X mentions of cursor composer-2.5-fast billing in the last 4 hours?" The "me too" wave shows up on X a full day before GitHub Issues triages it. → bluex_x_search recency=4hr → bluex_web_search the issue tracker

Vendor support went silent. "Timeline + verbatim user quotes on the Cursor on-demand billing complaints this week." The refund ticket disappeared into a black hole; the real signal lives in X user threads. → bluex_x_search mode=deep returns timeline + verbatim quotes + sentiment

Track a thinker, not a feed. "From @karpathy, last 7 days, anything on nano-banana." A specific account speaking up is what unblocks the call. → bluex_x_search from:@handle last:7d

Conference happening right now. "#AnthropicDevDay tweets from the last hour." The keynote is live; the official blog will recap six hours later. → bluex_x_search with hashtag + last:1hr

Competitor pre-launch intel. "What's on X about Cursor pricing changes this week?" Roadmap leaks land on X before any press release. → bluex_x_search recency=7d mode=deep

Breaking change before the docs admit it. "Anyone hitting issues with Next.js 16 app router migration in the last day?" The library's docs say "stable"; X has the unfixed-bug thread. → bluex_x_search + bluex_web_search on the upstream issue

Indie launch positioning research. "Recent MCP server launch posts on X, last 14 days — what got real engagement?" Studying how others framed a similar product before you ship yours. → bluex_x_search with engagement cues in the prompt

Academic paper reaction loop. "Show me the X discussion around the <paper title> arXiv preprint." Authors don't blog; the actual debate plays out in quote-tweets. → bluex_x_search mode=deep for perspectives + verification

---

Tools

Tool	Purpose
bluex_x_search	Search X/Twitter — filter by @handles, date range, recency (15min / 1hr / 4hr / 24hr / 7d)
bluex_web_search	Search the live web — domain include/exclude, recency
bluex_health_check	Check grok install, model, profile, login status

Search modes

Mode	What you get
basic (default)	Summary + source items (title, url, author, handle, timestamp, snippet) + citations
deep	Basic + analysis object: timeline, verbatim quotes (with attribution), multiple perspectives, sentiment, and verification (confirmed / unconfirmed / contradictory)

---

Example output

bluex_x_search · mode: "basic"

{
  "summary": "…",
  "items": [
    { "title": "…", "url": "https://x.com/…/status/…", "handle": "@…",
      "publishedAt": "2026-06-30T12:00:00Z", "snippet": "…" }
  ],
  "citations": [{ "url": "https://x.com/…", "domain": "x.com", "secure": true }],
  "urls": ["https://x.com/…"],
  "diagnostics": {
    "mode": "x", "analysisMode": "basic", "parseOk": true, "structured": true,
    "model": "grok-build", "profile": "shared", "attempts": 1, "warnings": []
  }
}

mode: "deep" adds:

{
  "analysis": {
    "timeline": [{ "date": "…", "event": "…", "source": "…" }],
    "quotes": [{ "quote": "…", "speaker": "…", "source": "…" }],
    "perspectives": [{ "viewpoint": "…", "summary": "…", "sources": ["…"] }],
    "sentiment": "…",
    "verification": {
      "confirmed": ["…"], "unconfirmed": ["…"], "contradictory": ["…"]
    }
  }
}

---

How it works

your agent ──MCP/stdio──▶ bluex-mcp ──child process──▶ grok CLI (your login) ──▶ live X + web

Each search runs grok --single … --output-format json --permission-mode dontAsk --json-schema … in a throwaway working directory. The schema constrains the model to emit conforming JSON — no regex-guessing from prose.

• Auth cache — login checked every 5 min; a cold probe takes ~2 s, then instant.
• Recursion guard — BLUEX_MCP_ACTIVE env var prevents circular launches.
• Isolation — memory / subagents / plan-mode disabled; your grok sessions are untouched.

---

Configuration

Set these as environment variables in your MCP client's server config. All optional.

Variable	Default	Purpose
GROK_BIN	grok	Path to the grok CLI binary
BLUEX_TIMEOUT_MS	180000	Per-call timeout (ms)
BLUEX_MAX_TURNS	6	Max agentic turns the child grok may take
BLUEX_MAX_RETRIES	2	Retries on empty/failed runs (exponential backoff)
BLUEX_EFFORT	(grok default)	Reasoning effort — low / medium / high / xhigh / max
BLUEX_ISOLATED	false	Run grok under a dedicated clean profile (see below)
BLUEX_HOME	~/.bluex-mcp	HOME for the isolated profile
BLUEX_LOG_FILE	(off)	Path to JSONL log file
BLUEX_LOG_QUERY	hash	How the query field is stored in logs — none (drop), hash (SHA-256), raw
BLUEX_LOG_DISPATCH	false	Also record per-tool dispatch counts in each log line
BLUEX_AB	false	Master switch for the internal A/B experiment sampler (off in production)
BLUEX_AB_EFFORTS	none,low,high,max	Comma-separated effort levels the A/B sampler picks from. none = pass no --effort flag
BLUEX_AB_STRATEGY_RATE	0.5	Probability of injecting the X search strategy prompt when A/B is on

Model is pinned to grok-build and is intentionally not configurable. The only other locally available model, grok-composer-2.5-fast, is a coding model — not suited for search.

Isolated profile (optional)

By default bluex-mcp reuses your existing Grok login. For full isolation (no grok config, rules, or other MCP servers loaded), set BLUEX_ISOLATED=1 and log in once:

BLUEX_ISOLATED=1 bluex-mcp login
# Then add BLUEX_ISOLATED=1 to your MCP client's environment for this server.

---

FAQ

How is this different from other Grok or Twitter MCP servers? Other Grok-based MCPs are built on the xAI API — they take an XAI_API_KEY and bill per token. bluex-mcp takes a different path: it drives your already-logged-in grok CLI, so calls run on your X Premium / SuperGrok subscription quota. See the Why table for the full comparison.

Do I need an xAI API key? No. grok login with your existing subscription is all you need.

Is there a usage limit? Yes — you're subject to your Grok plan's rate limits. SuperGrok allows ~100 prompts/2 hr; lower tiers less. source This is your normal Grok quota, not an extra limit.

Does SuperGrok include an X blue check? No. SuperGrok is a standalone AI subscription with no X social features. The blue checkmark comes with X Premium / X Premium+. source

Is this affiliated with xAI or X? No. Independent open-source wrapper around the public Grok CLI.

Does it store my credentials? No. Auth lives in the grok CLI's own profile. bluex-mcp only executes the binary.

Will it interfere with my normal grok sessions? No. Each search runs in a throwaway directory with memory/subagents/plan-mode off. For full config isolation, set BLUEX_ISOLATED=1.

---

Acknowledgements

bluex-mcp's initial architecture was forked from z2z23n0/grok-search-mcp. The deep analysis structure draws on stat-guy/grok-search-mcp, recency presets from mzkrasner/grok-x-insights, and tool categorisation from guzus/grok-mcp.

---

License

MIT — LICENSE