Bluex Mcp

bluex-mcp

[📖 中文文档](./README.zh.md)

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

[](https://opensource.org/licenses/MIT)

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 ` in the last hour"* — it routes through bluexxsearch`.

---

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 ` arXiv preprint."* Authors don't blog; the actual debate plays out in quote-tweets. → bluexxsearch 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](#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](./LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Derek-Wong213
• Source: Derek-Wong213/bluex-mcp
• License: MIT
• Homepage: https://github.com/Derek-Wong213/bluex-mcp

Install and usage instructions live in the source repository linked above.