Content
# 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](https://modelcontextprotocol.io) 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
```bash
npm install -g github:Derek-Wong213/bluex-mcp
grok login
bluex-mcp health
```
Wire it into your agent:
```bash
# Claude Code
claude mcp add bluex -- bluex-mcp
```
```toml
# Codex (~/.codex/config.toml)
[mcp_servers.bluex]
command = "bluex-mcp"
```
```jsonc
// 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"`
```json
{
"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:
```json
{
"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:
```bash
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](https://jingrey.com/ai-tech/grok-usage-limits-guide) 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](https://jingrey.com/ai-tech/supergrok-vs-x-premium-limits)
**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](https://github.com/z2z23n0/grok-search-mcp). The `deep` analysis structure draws on [stat-guy/grok-search-mcp](https://github.com/stat-guy/grok-search-mcp), recency presets from [mzkrasner/grok-x-insights](https://github.com/mzkrasner/grok-x-insights), and tool categorisation from [guzus/grok-mcp](https://github.com/guzus/grok-mcp).
---
## License
MIT — [LICENSE](./LICENSE)
