grok-mcp-server

一个远程 MCP 服务器，让任何 Claude（或任何兼容 MCP 的 AI）都能从任何地方使用 xAI Grok 的完整能力——实时 X（Twitter）搜索、网络搜索、聊天、图像生成、视觉理解、图像编辑、视频生成、结构化输出和推理。无论在笔记本电脑、手机，还是在你睡梦中运行的自动化任务上。

无论你是构建智能体的开发者、编排工作流的自动化爱好者，还是希望把实时数据带进 Claude 的创作者——安装方式都一样。

部署在你自己的 Cloudflare 账户上。4 条命令。无状态。9 个工具。

作为 auny-ai/claude-os 的一部分构建——这是一个公开建设的多 AI 操作系统。🧡

它能做什么

九个工具，全部是对 xAI API 的封装。每个工具都是通用型的——下面的用例只是可能用途的一些示例。

搜索 + 聊天

x_search — 实时 X（Twitter）数据

通过 xAI 原生的 x_search 后端搜索 X。返回的帖子包含作者账号、粉丝数、互动指标（点赞、转推、回复、浏览量）、时间戳、嵌入式媒体和引用推文上下文。

支持完整的 X 高级搜索运算符集：min_faves:N、min_retweets:N、filter:blue_verified、filter:verified、from:user、lang:en、since:YYYY-MM-DD 等。

grok_web_search — 实时网络搜索，获取最新信息

通过 Grok 进行通用网络搜索，将结果综合为连贯的答案，并附上来源。持续更新——不受模型知识截止日期限制。

grok_chat — 将 Grok 用作模型，而不仅是搜索工具

直接使用 Grok 进行纯文本补全。支持可选的系统提示词和模型覆盖。当你希望某个特定输出使用 Grok（而非 Claude）的推理风格或语气时，这个工具非常有用。

视觉 + 媒体

grok_image_generate — 文生图

使用 Grok Imagine（Quality Mode）根据文本提示生成图像。返回图像 URL。适用于原型图、社交媒体卡片、缩略图、品牌视觉素材和 A/B 变体。每次调用最多 4 个变体。

grok_image_understand — 多模态视觉理解

传入图片 URL 和一个问题——即可获得分析结果。适用于截图调试、内容审查、替代文本生成、设计反馈和视觉分诊。

grok_image_edit — 文本提示图像编辑

传入现有图片 URL 和修改描述——即可获得编辑后的图像。适用于迭代品牌视觉素材、生成颜色/风格变体以及混搭现有素材。

grok_video_generate — 文生视频 / 图生视频

使用 Grok Imagine 生成短视频（最长 10 秒、720p）。支持纯文本提示和图生视频（从静态图片开始）。返回视频 URL。注意：视频生成可能需要 20-60 秒。

结构化输出 + 推理

grok_structured_output — 受 JSON Schema 约束的响应

传入提示词和描述预期结构的 JSON Schema。返回符合该 Schema 的已解析 JSON。适用于需要稳定输出结构的可靠智能体流程、从文本中提取数据以及 ETL 工作流。

grok_reasoning — 深度分析模式

使用 Grok 的推理模式处理复杂问题。比 grok_chat 慢，但输出更严谨。可调节投入程度（low、medium、high）。适用于战略问题、多步骤分析、辩论准备和技术评审。

Related MCP server: Cloudflare Tavily Search MCP

使用场景

这是一个通用的 Grok 封装器，任何 MCP 客户端都可以调用。其使用场景与 Grok 自身的能力一样广阔。

面向开发者

• 构建需要实时数据的智能体。 大多数 AI 智能体对最近 24 小时内发生的事一无所知。这个服务器把实时 X + 网络搜索作为基本能力提供给任何兼容 MCP 的智能体。

• 多模型编排。 Claude 做编排者，Grok 做执行者——对于不需要 Claude 的推理能力、但需要信息新鲜度或特定语气风格的任务，这是一种更便宜、更快的并行分发方式。

• 在 Claude Code 中进行实时研究。 调试某个库时，无需离开终端即可拉取当前的 GitHub issue 或最新文档。

• 跨模型评估。 在 Claude 内部把同一个提示词同时发送给两个模型，在一个工作流中比较输出。

• 替代网页抓取基础设施。 如果你有脆弱的 Puppeteer/Playwright 配置在抓取 X 数据，这个服务器可以用一次 MCP 调用取而代之。xAI 负责处理认证、速率限制和渲染。

• 使用 grok_structured_output 进行可靠的数据提取。 定义一次 Schema，就能获得一致的 JSON 返回。告别正则解析。

• 程序化资产生成。 在流程中途用 grok_image_generate 快速生成测试原型图、设计变体或视觉占位图。

• 视觉增强的智能体。 使用 grok_image_understand 让智能体能够对截图、设计文件或实时 UI 进行推理分析。

• SaaS 原型的低价实时数据层。 在构建正式后端之前，用一个周末验证“实时市场情报”或“X 提及监控”这样的功能。

面向数据、分析和研究

• 拉取任意主题的 X 对话数据进行分析。 包括情感倾向、声量、发布者、互动分布等。

• 跟踪监管、政策或行业动态——在事件发生时即可掌握，而不是等几个月后才进入 Claude 的训练数据。

• 社交话语学术研究——无需编写 Twitter API 客户端，即可实时获取某个话题的讨论数据。

• 竞争情报管道——跟踪竞争对手的产品发布、招聘帖子、客户投诉和价格变动。

• 大规模结构化数据提取。 grok_structured_output 能从非结构化文本中可靠地提取实体、关系或特征。

面向自动化和运维

• 醒来就能看到你关心的主题的每日简报（Claude Routines + 这个 MCP = 自动化个人新闻台）。

• 品牌提及监控，无需为 Brandwatch / Mention.com 付费。

• 趋势检测——在你的细分领域话题登顶之前，发现正在走红的内容。

• 销售线索分诊——找到那些公开抱怨你的产品所解决的问题的人。

• 客户支持侦察——在工单出现之前，先了解用户对你的产品有什么评价。

• 自动生成视觉警报。 当有值得关注的事情发生时，触发一次 grok_image_generate 调用，生成一张自定义缩略图。

面向创作者

• 热门内容雷达——每天自动研究你的细分领域里正在走红的内容。

• 引用推文机会发现器——找出你关注的话题中互动量高、值得回应的帖子。

• 受众研究——了解你的目标受众实际在谈论什么，而不是你臆测他们在意什么。

• 为任何产出拉取素材——文章、帖子串、演示文稿——无需切换到浏览器。

• 视觉品牌工作流。 无需离开 Claude，即可在一个工作流中生成横幅图、社交媒体卡片、帖子缩略图和视频片段。

• 在聊天中获得设计反馈。 通过 grok_image_understand 丢一张截图，问一句“这个设计有什么问题？”——就能得到具体的改进意见。

• 多步骤内容生产： grok_web_search → 调研，grok_chat → 草稿，grok_image_generate → 视觉素材，grok_video_generate → 视频片段。一条管道，一个聊天窗口。

面向所有人

• 把最新信息带进 Claude。 凡是发生在 Claude 知识截止日期之后的事件，都可以通过这个服务器获取——无需离开你的 Claude 聊天窗口。

• 用实时网络数据核查 Claude 的输出。

• 用网络来源和实时 X 讨论交叉验证各种说法。

• 生成真正可用的视觉素材——Grok Imagine Quality Mode 能产出可直接投入生产环境的图像。

你需要准备什么

• 一个 xAI API 密钥——在 https://console.x.ai/ 获取

• 一个 Cloudflare 账户（免费；如果没有，30 秒就能注册好）

• 一个你习惯粘贴命令的终端（macOS Terminal、iTerm、Windows Terminal——什么都可以）

• 已安装 Node 18+——如果没有，在此下载

• 约 5 分钟

关于费用的说明

这个仓库不会向你收取任何费用。你部署的是自己的服务器副本，直接向 xAI 支付 Grok 使用费，而 Cloudflare 在典型使用场景下不产生任何费用。

• xAI：你为 Grok API 调用向 xAI 付费，账单会记入你 xAI 账户上的支付方式（console.x.ai）。图像和视频生成比文本更贵——在自动化大批量创意工作流之前，请先查看价格。

• Cloudflare：Workers 免费版 = 每天 10 万次请求，远超你的实际用量。

• 我：零——没有遥测、没有代理、没有中转。代码运行在你的账户上，用你的密钥，记在你的账单上。

5 条命令完成安装

git clone https://github.com/auny-ai/grok-mcp-server.git
cd grok-mcp-server
npm install
npx wrangler login

（wrangler login 会打开一个浏览器标签页——只需授权一次 Cloudflare 访问权限。）

将你的 xAI 密钥和自定义生成的认证密钥配置为 Worker 机密，然后部署：

npx wrangler secret put XAI_API_KEY
# (paste your xai-... key when prompted)

printf '%s' "$(openssl rand -hex 32)" | npx wrangler secret put AUTH_SECRET
# generates and sets your own random secret — this gates the endpoint below

npx wrangler deploy

你会看到类似这样的输出：

Deployed grok-mcp-server triggers
  https://grok-mcp-server.<your-account>.workers.dev

完成。你的 Worker 已上线——并且设有访问门禁。与 v1 不同，/mcp 端点现在默认拒绝访问：在设置 AUTH_SECRET 之前，它会拒绝所有请求（返回 503），并对任何未提供有效凭证的请求返回 401。完整的安装契约见 AGENTS.md，认证门禁的工作原理见 docs/ARCHITECTURE.md。

一条命令同时验证两条认证路径和工具数量：

AUTH_SECRET=<the secret you generated> \
MCP_URL=https://grok-mcp-server.<your-account>.workers.dev \
./verify.sh

输出应以 PASS 结尾。

连接到 Claude

该端点由 AUTH_SECRET 保护。有两种认证方式，与两种客户端形态对应：

在 Claude.ai 中（Routines、Projects、自定义集成）

1. 设置 → 连接器 → 添加自定义连接器

2. 名称：Grok

3. URL：https://grok-mcp-server.<your-account>.workers.dev/mcp

4. 保存，然后连接——这会触发针对 /oauth/authorize 和 /oauth/token 的一键 OAuth/PKCE 握手。你无需将原始密钥粘贴到 claude.ai 中；连接器会收到一个带签名的、有时效的令牌。

现在，只要在任意聊天或 Routine 中启用 Grok 连接器，这九个工具就都可用了。

在 Claude Desktop / Claude Code 中

这两种是无头客户端，因此直接使用静态 Bearer 认证路径。将其添加到你的 MCP 配置文件中：

{
  "mcpServers": {
    "grok": {
      "url": "https://grok-mcp-server.<your-account>.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer <your AUTH_SECRET>"
      }
    }
  }
}

或者使用 Claude Code CLI：

claude mcp add grok --transport http \
  https://grok-mcp-server.<your-account>.workers.dev/mcp \
  --header "Authorization: Bearer <your AUTH_SECRET>"

重启你的 Claude 客户端，工具即可使用。

工具参考

x_search

通过 xAI 原生的 X 搜索工具搜索 X（Twitter）。

输入参数：

• query（字符串，必填）——要搜索的内容

• context（字符串，可选）——缩小关注范围

示例调用（在 Claude 内）：

使用 x_search 查找关于 "Claude Code" 的最新帖子，筛选条件为 min_faves:500 filter:blue_verified

此工具支持的 X 搜索运算符： min_faves:N、min_retweets:N、filter:blue_verified、filter:verified、from:user、lang:en、since:YYYY-MM-DD，以及大多数其他高级搜索运算符。

grok_web_search

通过 Grok 进行通用网络搜索。

输入参数：

• query（字符串，必填）——要搜索的内容

• context（字符串，可选）——缩小关注范围

grok_chat

纯文本 Grok 补全。

输入参数：

• prompt（字符串，必填）——用户提示词

• system（字符串，可选）——系统提示词

• model（字符串，可选）——模型覆盖（默认值：grok-4.3）

grok_image_generate

根据文本提示生成图像。

输入参数：

• prompt（字符串，必填）——图像描述

• n（整数 1-4，可选）——变体数量（默认值：1）

• model（字符串，可选）——模型覆盖（默认值：grok-imagine-image-quality）

返回： 图像 URL。如果有多张，返回一个编号列表。

示例调用：

使用 grok_image_generate 制作一张赛博朋克风格的海报：一只黑猫坐在发光的键盘上，n=2

grok_image_understand

使用 Grok 的视觉能力分析图像。

输入参数：

• image_url（字符串，必填）——图像 URL（jpg、jpeg 或 png）

• prompt（字符串，必填）——你想了解的内容

• model（字符串，可选）——模型覆盖（默认值：grok-4.3）

示例调用：

使用 grok_image_understand 处理 https://example.com/dashboard.png — 你看到了哪些 UX 问题？

grok_image_edit

通过文本提示编辑现有图像。

输入：

• image_url（字符串，必填）— 源图像的 URL

• prompt（字符串，必填）— 编辑的描述

• model（字符串，可选）— 模型覆盖（默认：grok-imagine-image-quality）

返回： 编辑后的图像 URL。

示例调用：

使用 grok_image_edit 处理 https://example.com/banner.jpg — 将背景改为日落，并在右上角添加一个小月亮

grok_video_generate

根据文本或图像生成一个短视频（最长 10 秒，720p）。

输入：

• prompt（字符串，必填）— 视频的描述

• image_url（字符串，可选）— 图生视频的起始图像

• model（字符串，可选）— 模型覆盖（默认：grok-imagine-video）

返回： 视频 URL。注意：生成通常需要 20-60 秒。

示例调用：

使用 grok_video_generate，提示词为"日落时海浪拍打岩石，慢动作"

grok_structured_output

从 Grok 获取由 JSON Schema 约束的响应。

输入：

• prompt（字符串，必填）— 你希望 Grok 生成的内容

• schema（对象或字符串化 JSON，必填）— 描述预期响应结构的 JSON Schema

• system（字符串，可选）— 系统提示词

• model（字符串，可选）— 模型覆盖（默认：grok-4.3）

返回： 与提供的 schema 匹配的 JSON。

示例调用：

使用 grok_structured_output 从这段文本中提取人物、公司和地点。Schema: { type: "object", properties: { people: { type: "array", items: { type: "string" } }, companies: { ... }, locations: { ... } }, required: ["people", "companies", "locations"] }

grok_reasoning

使用 Grok 的推理模式进行深度分析。

输入：

• prompt（字符串，必填）— 问题或难题

• effort（"low" | "medium" | "high"，可选）— 推理深度（默认：medium）

• system（字符串，可选）— 系统提示词

• model（字符串，可选）— 模型覆盖（默认：grok-4.3）

示例调用：

使用 grok_reasoning，effort=high，分析构建个人 MCP 服务器与使用现有连接器相比，是否值得承担维护成本

本地开发

在部署前测试更改：

1. 将 .env.example 复制为仓库根目录下的 .dev.vars（已被 git 忽略），并填入 你自己的值：

XAI_API_KEY="xai-..."
AUTH_SECRET="<output of: openssl rand -hex 32>"

2. 运行开发服务器：

npm run dev

3. 服务器现在运行于 http://localhost:8787。

架构

MCP client (Claude / Cursor / anything)
        │
        │  Streamable HTTP MCP, Bearer auth (static secret or OAuth token)
        ▼
Cloudflare Worker (this repo)
        │  gateMcp() — fails closed without AUTH_SECRET
        │
        │  Bearer auth via Worker secret
        ▼
xAI Grok API (api.x.ai/v1)
  ├── /responses       — chat, search, vision, structured, reasoning
  ├── /images/generations — image gen
  ├── /images/edits    — image edit
  └── /videos/generations — video gen

• 传输： 通过 Streamable HTTP 在 /mcp 上提供 MCP

• 状态： 每个请求无状态，无 Durable Objects，无会话记忆

• 认证（服务器 → xAI）： 使用 Bearer 令牌，通过 XAI_API_KEY Worker 密钥

• 认证（客户端 → 服务器）： 由 AUTH_SECRET（src/auth.ts）控制，fail-closed（默认拒绝）。 两条路由：一条静态 Bearer 令牌路由，面向无头客户端（Claude Code）；以及一条 OAuth 2.0 + PKCE 路由，使用无状态 HMAC 签名令牌，面向 claude.ai 连接器。 无 KV，无数据库——参见 docs/ARCHITECTURE.md 了解完整的请求路由和令牌验证说明。

参见 docs/RUNBOOK.md，了解轮换密钥、重新部署和常见故障模式。

添加工具

src/index.ts 使用 MCP SDK 的 server.tool() 模式定义工具：

server.tool(
  "tool_name",
  "Tool description for the LLM",
  { param: z.string() },
  async ({ param }) => {
    // your logic here
    return { content: [{ type: "text", text: "..." }] };
  }
);

所有工具共用一个 xaiFetch(env, path, body) 辅助函数来调用 xAI API。要添加一个包装其他 xAI 端点的新工具，只需将端点路径和请求体传给 xaiFetch 即可。

添加新工具后，运行 npm run dev 在本地测试，然后运行 npx wrangler deploy 发布。

Worker 名称

默认情况下，Worker 以 grok-mcp-server 的名称部署。要重命名它，请在部署前编辑 wrangler.jsonc 中的 name 字段：

{
  "name": "grok-mcp-server"  // change this
}

每个 Cloudflare 账户都有自己的命名空间，因此 grok-mcp-server.<you>.workers.dev 不会与任何人的部署冲突。

为什么会有这个项目？

大多数 MCP 服务器都运行在你的本地机器上。它们用起来很好——直到你想在笔记本之外的地方使用 Claude。

一旦你这样做：

• Claude Routines 无法访问本地服务器——它们运行在 Anthropic 的云端，而不是你的机器上

• 手机上的 Claude 无法与你的桌面电脑通信

• 任何代理或自动化，只要运行在笔记本以外的任何地方，就会被拒之门外

• 分享你的配置意味着要请别人安装 Node、克隆仓库，并让他们的笔记本保持开机

托管式 MCP 解决了所有这些问题。服务器位于开放的互联网上——在你的 Cloudflare 账户中，受你的密钥保护。Claude 可以从任何地方访问它。同样的工具、同样的密钥、同样的行为，无论从任何设备或工作流访问，都是如此。

如果你是开发者： 这是生产环境模式。本地用于原型开发，托管用于正式发布。同一套代码在开发和生产环境中运行。

如果你是创作者或自动化用户： 这就是让神奇功能随你离开笔记本的东西。你的例程在你睡觉时运行。你的手机拥有与桌面电脑相同的能力。你的上下文是可移植的。

更详细的版本——架构、取舍、围绕 Claude 构建这种上下文系统的模板——都在 CLAUDE.md 是起点 中。如果你正在考虑围绕 Claude 构建一个系统，而不仅仅是用它聊天，那值得一读。

更新日志

v1.2.0 — 新增 fail-closed 双路由入站认证（src/auth.ts）：一条静态 Bearer 路径，面向无头客户端；以及面向 claude.ai 连接器的自包含 OAuth 2.0 + PKCE， 二者均由同一个 AUTH_SECRET 支撑。无 KV，无数据库——无状态 HMAC 签名令牌。 新增 verify.sh、mcp.json、AGENTS.md、.env.example 和 docs/。

v1.1.0 — 新增 6 个工具：grok_image_generate、grok_image_understand、grok_image_edit、grok_video_generate、grok_structured_output、grok_reasoning。重构为共用的 xaiFetch 辅助函数。服务器现在暴露了 Grok 的完整功能面。

v1.0.0 — 初始版本。三个工具：x_search、grok_web_search、grok_chat。基于 Cloudflare Workers 的无状态 MCP 服务器。

许可证

MIT。你可以 fork 它、发布它、修改它、出售它。

相关链接

• auny-ai/claude-os — 本项目所属的多 AI 操作系统

• Cloudflare Agents SDK 文档 — 底层所用的 SDK

• Model Context Protocol — 本项目实现的标准

• xAI API 文档 — 本项目包装的底层 API

如果你基于这个项目做出了什么有趣的东西，欢迎开一个 issue，或在 X 上 @我。🧡