内容
# bluex-mcp
[📖 中文文档](./README.zh.md)
**实时X（推特）+ 网络搜索MCP服务器 — 由本地登录的Grok CLI驱动，运行在您的X Premium / SuperGrok订阅配额上。**
[](https://opensource.org/licenses/MIT)
您的编码代理不知道今天早上发布了什么。它看不到其他十位开发者正在解决同一个错误的X线程。它无法观看20分钟前开始的主题演讲，无法跟进有关竞争对手定价的泄露信息，无法告诉您 `@karpathy` 本周发布了什么。
`bluex-mcp` 弥补了这一空白。如果您支付了X Premium（8美元/月），X Premium+（40美元/月）或SuperGrok（30美元/月）的费用，您已经拥有通过Grok获得实时X + 网络访问的一流服务。这是一个薄的 [MCP](https://modelcontextprotocol.io) 服务器，通过驱动您**本地登录的 `grok` CLI**，将这些服务暴露给Claude Code，Codex，Cursor，Claude Desktop和任何其他MCP客户端 — 使用您的现有配额。
---
## 为什么
其他Grok MCP服务器使用xAI API。您需要一个密钥，一个有资金的账户，并且按令牌计费。`bluex-mcp` 走了一条不同的路。
| | xAI API（大多数Grok MCP） | **bluex-mcp** |
|---|---|---|
| 认证 | `XAI_API_KEY` | 您登录的 `grok` CLI |
| 成本 | 按令牌计费的API账单 | **$0** — 在您的订阅配额上运行 |
| 实时X访问 | 是 | 是（相同的Grok） |
| 设置 | 获取密钥，充值余额 | `grok login` 一次 |
| 足迹 | — | 2个搜索工具 + 1个健康检查 |
> 如果您已经不支付Grok费用，那么基于API的MCP是正确的方法。如果您支付了费用，`bluex-mcp` 使该订阅发挥双倍作用。
---
## 快速开始
```bash
npm install -g github:Derek-Wong213/bluex-mcp
grok login
bluex-mcp health
```
将其连接到您的代理：
```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" } } }
```
重启。询问 *"在过去一小时内搜索X中关于 `<topic>` 的信息"* — 它通过 `bluex_x_search` 路由。
---
## 实际应用
每个示例都是一个真实的场景，没有实时X访问的代理会卡住。它们都通过下面的两个搜索工具路由。
**突发AI / 模型发布，第一信号。**
*" `@AnthropicAI`刚刚宣布了什么？最近一小时。"*
新模型在X上发布了30分钟，但您的代理的知识截止日期是六周前。→ `bluex_x_search` · `recency=1hr` · `from:@handle`
**库或CLI刚刚出现问题，文档无能为力。**
*"最近4小时内X中关于 `cursor composer-2.5-fast` 计费的提及？"*
" 我遇到的问题" 波在X上出现，比GitHub Issues的分类早了一整天。→ `bluex_x_search recency=4hr` → `bluex_web_search` 问题跟踪器
**供应商支持突然中断。**
*"Cursor按需计费投诉本周的 timeline + 原话引语。"*
退款单消失在黑洞中；真正的信号在X用户线程中。→ `bluex_x_search mode=deep` 返回timeline + 原话引语 + 情绪
**跟踪思想家，而不是订阅源。**
*"来自 `@karpathy` ，最近7天，关于 `nano-banana` 的任何信息。"*
特定账户的发言是解锁对话的关键。→ `bluex_x_search from:@handle last:7d`
**会议现在正在进行。**
*" `#AnthropicDevDay` 推文，过去一小时。"*
主题演讲正在进行中；官方博客将在六小时后总结。→ `bluex_x_search` 使用标签 + `last:1hr`
**竞争对手发布前情报。**
*"X上关于Cursor定价变化本周的信息。"*
路线图泄露在X上发布，而不是新闻稿。→ `bluex_x_search recency=7d mode=deep`
**发布前变更。**
*"有人在最近一天遇到Next.js 16应用路由器迁移问题吗？"*
库的文档表示"稳定"；X上有未修复的错误线程。→ `bluex_x_search` + `bluex_web_search` 上游问题
**独立发布定位研究。**
*"最近14天内X上的MCP服务器发布帖子 — 有多少互动？"*
研究其他人如何为类似产品构建类似的产品。→ `bluex_x_search` 使用提示中的互动提示
**学术论文反应循环。**
*"显示X上关于 `<paper title>` arXiv预印本的讨论。"*
作者不写博客；实际的辩论在引用推文中进行。→ `bluex_x_search mode=deep` 获取观点 + 验证
---
## 工具
| 工具 | 目的 |
|---|---|
| `bluex_x_search` | 搜索X/Twitter — 按 `@handles` 、日期范围、最近时间（`15min` / `1hr` / `4hr` / `24hr` / `7d` ）过滤 |
| `bluex_web_search` | 搜索实时网络 — 域名包含/排除，最近时间 |
| `bluex_health_check` | 检查grok安装、模型、配置文件、登录状态 |
### 搜索模式
| 模式 | 您获得的内容 |
|---|---|
| `basic` （默认） | 摘要 + 源项（标题，网址，作者，句柄，时间戳，片段）+ 引用 |
| `deep` | 基本 + `analysis` 对象：**时间线** ， **原话引用** （带属性）， **多个视角** ， **情绪** 和 **验证** （`confirmed` / `unconfirmed` / `contradictory` ） |
---
## 示例输出
`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"` 添加：
```json
{
"analysis": {
"timeline": [{ "date": "…", "event": "…", "source": "…" }],
"quotes": [{ "quote": "…", "speaker": "…", "source": "…" }],
"perspectives": [{ "viewpoint": "…", "summary": "…", "sources": ["…"] }],
"sentiment": "…",
"verification": {
"confirmed": ["…"], "unconfirmed": ["…"], "contradictory": ["…"]
}
}
}
```
---
## 工作原理
```
您的代理 ──MCP/stdio──▶ bluex-mcp ──子进程──▶ grok CLI（您的登录） ──▶ 实时X + 网络
```
每个搜索都在一个临时工作目录中运行 `grok --single … --output-format json --permission-mode dontAsk --json-schema …` 。模式约束模型发出符合JSON的模式 — 而不是从原始文本中猜测正则表达式。
- **身份验证缓存** — 每5分钟检查登录；冷探测约2秒，然后立即生效。
- **递归保护** — `BLUEX_MCP_ACTIVE` 环境变量防止循环启动。
- **隔离** — 内存/子代理/计划模式禁用；您的grok会话不受影响。
---
## 配置
在MCP客户端的服务器配置中，将这些变量设置为环境变量。所有变量都是可选的。
| 变量 | 默认值 | 目的 |
|---|---|---|
| `GROK_BIN` | `grok` | grok CLI二进制文件的路径 |
| `BLUEX_TIMEOUT_MS` | `180000` | 每次调用的超时时间（毫秒） |
| `BLUEX_MAX_TURNS` | `6` | 子grok可能采取的最大代理回合 |
| `BLUEX_MAX_RETRIES` | `2` | 空/失败运行的重试次数（指数退避） |
| `BLUEX_EFFORT` | *（grok默认值）* | 推理努力 — `low` / `medium` / `high` / `xhigh` / `max` |
| `BLUEX_ISOLATED` | `false` | 在专用干净配置文件下运行grok（见下文） |
| `BLUEX_HOME` | `~/.bluex-mcp` | 隔离配置文件的HOME |
| `BLUEX_LOG_FILE` | *（关闭）* | JSONL日志文件的路径 |
| `BLUEX_LOG_QUERY` | `hash` | `query`字段在日志中存储的方式 — `none` （丢弃）， `hash` （SHA-256）， `raw` |
| `BLUEX_LOG_DISPATCH` | `false` | 还记录每个日志行中的每个工具调度计数 |
| `BLUEX_AB` | `false` | 内部A/B实验采样器的主开关（生产环境关闭） |
| `BLUEX_AB_EFFORTS` | `none,low,high,max` | 逗号分隔的努力级别，A/B采样器从中选取。 `none` = 不传递 `--effort` 标志 |
| `BLUEX_AB_STRATEGY_RATE` | `0.5` | 注入X搜索策略提示的概率（启用A/B时） |
> **模型** 固定为 `grok-build` ，故意不可配置。唯一可用的本地模型， `grok-composer-2.5-fast` ，是编码模型 — 不适合搜索。
### 隔离配置文件（可选）
默认情况下， `bluex-mcp` 重用现有的Grok登录。为了完全隔离（无grok配置，规则或其他MCP服务器加载），设置 `BLUEX_ISOLATED=1` 并登录一次：
```bash
BLUEX_ISOLATED=1 bluex-mcp login
# 然后在MCP客户端的环境中为此服务器添加 BLUEX_ISOLATED=1。
```
---
## 常见问题
**它与其他的Grok或Twitter MCP服务器有什么不同？** 其他基于Grok的MCP是建立在xAI API上的 — 它们获取 `XAI_API_KEY` 并按令牌计费。 `bluex-mcp` 走了一条不同的路：它驱动您已经登录的 `grok` CLI，因此调用运行在您的X Premium / SuperGrok订阅配额上。有关完整比较，请参见 [Why](#why) 表。
**我需要xAI API密钥吗？** 不需要。只要使用现有的订阅登录 `grok` 即可。
**有使用限制吗？** 是的 — 您受Grok计划的速率限制。SuperGrok允许约100个提示/2小时；较低的层级较少。 [来源](https://jingrey.com/ai-tech/grok-usage-limits-guide) 这是您正常的Grok配额，而不是额外的限制。
**SuperGrok是否包含X蓝色勾选？** 不，SuperGrok是一个独立的AI订阅，没有X社交功能。蓝色勾选标记随X Premium / X Premium+提供。 [来源](https://jingrey.com/ai-tech/supergrok-vs-x-premium-limits)
**它与xAI或X有关吗？** 不，独立的开源包装器围绕公开的Grok CLI。
**它会存储我的凭证吗？** 不，身份验证存在于grok CLI自己的配置文件中。 `bluex-mcp` 只执行二进制文件。
**它会干扰我的正常grok会话吗？** 不，每个搜索都在一个临时目录中运行，禁用内存/子代理/计划模式。对于完全配置隔离，请设置 `BLUEX_ISOLATED=1` 。
---
## 致谢
`bluex-mcp`的初始架构从 [z2z23n0/grok-search-mcp](https://github.com/z2z23n0/grok-search-mcp) 分叉而来。 `deep` 分析结构借鉴了 [stat-guy/grok-search-mcp](https://github.com/stat-guy/grok-search-mcp) ，最近时间预设来自 [mzkrasner/grok-x-insights](https://github.com/mzkrasner/grok-x-insights) ，工具分类来自 [guzus/grok-mcp](https://github.com/guzus/grok-mcp)。
---
## 许可证
MIT — [LICENSE](./LICENSE)
