grok-mcp-server
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: grok-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、自定义集成)
设置 → 连接器 → 添加自定义连接器
名称:
GrokURL:
https://grok-mcp-server.<your-account>.workers.dev/mcp保存,然后连接——这会触发针对
/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(字符串,必填)— 源图像的 URLprompt(字符串,必填)— 编辑的描述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 Schemasystem(字符串,可选)— 系统提示词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 服务器与使用现有连接器相比,是否值得承担维护成本
本地开发
在部署前测试更改:
将
.env.example复制为仓库根目录下的.dev.vars(已被 git 忽略),并填入 你自己的值:
XAI_API_KEY="xai-..."
AUTH_SECRET="<output of: openssl rand -hex 32>"运行开发服务器:
npm run dev服务器现在运行于
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_KEYWorker 密钥认证(客户端 → 服务器): 由
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 上 @我。🧡
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Hosted MCP server from TwitterAPI.io that gives AI agents read-only access to Twitter/X data. 12 tools: tweet search with X operators, user profiles, a user's latest tweets, followers and followings, replies, quotes, retweeters, mentions and trends. Connect at https://mcp.twitterapi.io/mcp with a TwitterAPI.io API key or account sign-in; usage is paid per result returned. Separately, TwitterAPI.io also offers x402 pay-per-call HTTP endpoints (tweet search, user info, a user's latest tweets) paid in USDC on Base or Solana with no account or API key; see https://docs.twitterapi.io/x402-pay-per-call. The MCP server itself uses an API key or sign-in.
Hosted X (Twitter) MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Related MCP Servers
- AlicenseAqualityBmaintenanceUse XAI's latest api functionalities with Grok MCP. It supports image understanding and generation, live search, latest models and more.2255MIT
- AlicenseAqualityDmaintenanceMCP server that wraps the xAI Grok API, allowing Claude and other AI agents to delegate thinking, planning, and real-time search tasks to Grok. It provides a single tool with options for different use cases including web search, Twitter/X search, and multi-agent reasoning.2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for xAI Grok API with 19 tools for chat, web and X search, session management, tool chaining, image and video generation, and documentation.2MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to generate text, images, and videos via Grok's web UI using MCP tools (grok_chat, grok_generate_image, grok_generate_video) without an API key.1MIT