Skip to main content
Glama
Derek-Wong213

bluex-mcp

by Derek-Wong213
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

License: 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.

Related MCP server: grok-search-mcp

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

Available Tools

3 tools
bluex_health_checkCheck bluex-mcp + grok wiringA

Verify the grok CLI is installed, which model is used, the isolated HOME, and whether you are logged in. Run this first if searches fail.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description bears full burden. Lists what it checks but omits behavioral details like read-only nature or side effects. Adequate basic transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose. No redundant words. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with no parameters or output schema. Description covers usage context but lacks detail on output format or results structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, schema coverage 100%. Description adds meaning by explaining the specific checks performed, beyond schema's empty property list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it verifies the grok CLI installation, model, HOME, and login status. This distinguishes it from sibling search tools as a diagnostic utility.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Run this first if searches fail', providing clear when-to-use guidance. No exclusions mentioned but sufficient for context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedbluex_health_check
    • First observedbluex_web_search
    • First observedbluex_x_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a unique and non-overlapping purpose: health check for system readiness, web search for general web queries, and X search for Twitter-specific content. There is no ambiguity in their intended use.

Naming Consistency5/5

All tool names follow a consistent pattern with the 'bluex_' prefix followed by a descriptive verb-noun pair (health_check, web_search, x_search). The naming is uniform and predictable, aiding agent selection.

Tool Count4/5

With only 3 tools, the server is lean but covers its core functionality adequately. The count is on the lower end of the ideal range but not egregiously small, as each tool serves a distinct and necessary role.

Completeness4/5

The tool set covers health verification and two main search domains (web and X), which seems sufficient for its stated purpose. Minor gaps like additional search refinement or account management are absent but not critical for basic operation.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • X MCP Server

    siddheshutd
    A
    license
    B
    quality
    D
    maintenance
    MCP server for interacting with the X platform (Twitter) via MCP clients like Claude, Cursor AI, and Windsurf AI.
    20
    8 npm
    6
    MIT

  • grok-search-mcp

    z2z23n0
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that enables coding agents to search X/Twitter and the web through the local Grok CLI, providing better search results than default Codex or Claude search without requiring an API key.
    17 npm
    6
    MIT

  • twitterapis

    TwitterAPIs
    A
    license
    A
    quality
    B
    maintenance
    MCP server for the Twitter/X read API, enabling search, user profiles, tweets, followers, and more via natural language.
    94
    984 npm
    MIT