背景

2026 年 5 月中旬，xAI 在 accounts.x.ai 正式开放了 OAuth 登录流程——SuperGrok 或 X Premium+ 订阅用户可以通过 OAuth 2.0 授权，直接调用 Grok 的内置工具（x_search、web_search、图像/视频生成），而且优先消耗订阅额度，不走 API Key 的付费计量。

这意味着：只要你有 SuperGrok 订阅，就能免费（在额度内）让 Agent 拥有实时 X/Twitter 搜索和多模态生成能力。

Hermes Agent v0.14.0 是最先大规模落地这一能力的第三方工具。受其启发，我做了 Grok It——一个 MCP Server + Agent Plugin，让 Claude Code 和 Codex 也能无缝接入 xAI/Grok 的完整工具链。

Grok It 是什么

Grok It 是一个轻量级 Agent 插件，通过 MCP（Model Context Protocol）协议将 xAI/Grok 的能力暴露为标准工具调用。

核心能力：

• X Search (grok_x_search)：实时搜索 X/Twitter 内容，支持日期范围、用户筛选、媒体过滤
• 图像生成 (grok_image_generate)：调用 xAI 图像生成 API，支持多种宽高比和分辨率
• 视频生成 (grok_video_generate)：文本/图像驱动的视频生成，支持 1-30 秒时长控制
• OAuth 认证管理 (grok_auth_status / grok_login)：PKCE 安全流程，浏览器一键登录

为什么需要它

场景	没有 Grok It	有 Grok It
Agent 需要搜索 X 上的最新讨论	手动打开浏览器搜索，复制粘贴	Agent 直接调用 grok_x_search，结果即时可用
需要为文档配图	切换到其他图像生成工具	在对话中直接 grok_image_generate
验证 API Key 额度	登录 xAI 控制台查看	用 OAuth 走订阅额度，API Key 不消耗

关键优势：

1. 零 API Key 管理：OAuth 登录后自动使用 SuperGrok 订阅额度
2. 双认证回退：OAuth 失败时自动 fallback 到 XAI_API_KEY
3. 即插即用：npx grok-it-mcp 即可启动，无需全局安装
4. 极简依赖：运行时仅依赖 @modelcontextprotocol/sdk 和 zod

快速开始

第一步：安装 CLI

npm install -g grok-it-mcp

第二步：登录 Grok（OAuth）

grok-it-mcp login --open

浏览器会自动打开 xAI OAuth 授权页面，登录你的 SuperGrok / X Premium+ 账号完成授权即可。Token 会持久化到 ~/.grok-it/auth.json，后续无需重复登录。

如果在远程/无头服务器上，使用 loopback 模式并转发端口：

# 本地终端转发端口
ssh -N -L 8153:127.0.0.1:8153 user@remote-host

# 远程机器上执行
grok-it-mcp login --loopback

登录后可以验证状态：

grok-it-mcp status

也可以直接在 CLI 中体验搜索和生成：

grok-it-mcp search "xAI news"
grok-it-mcp image-gen "a neon robot in Shanghai" --aspect-ratio 16:9
grok-it-mcp video-gen "waves crashing at sunset" --duration 6 --json

第三步：安装插件到 Agent

Claude Code：

/plugin marketplace add Misty-Star/grok-it-mcp
/plugin install grok-it@grok-it

Codex CLI：

codex plugin marketplace add Misty-Star/grok-it-mcp
codex plugin add grok-it@grok-it

手动配置 MCP Server（任意支持 MCP 的客户端）：

在项目的 .mcp.json 中添加：

{
  "mcpServers": {
    "grok-it": {
      "command": "npx",
      "args": ["-y", "grok-it-mcp@latest"]
    }
  }
}

备用认证：API Key

如果不方便 OAuth，也可以通过环境变量提供 API Key：

export XAI_API_KEY="your-xai-api-key"

两种方式可以共存——OAuth 优先，失败时自动回退到 API Key。

工具详解

X Search

grok_x_search: 搜索关于 Claude Code 最新讨论

支持的参数：

• query：搜索关键词
• date_range：日期范围过滤
• handle：指定用户
• media_filter：过滤媒体类型
• max_results：结果数量限制

底层使用 xAI /responses API 配合 x_search 内置工具，模型默认为 grok-4.20-reasoning。

图像生成

grok_image_generate: 生成一张赛博朋克风格的城市夜景

支持参数：

• prompt：图像描述
• aspect_ratio：宽高比（1:1、16:9、9:16 等）
• resolution：分辨率
• n：批量生成数量（1-4）

生成的图像自动缓存到 ~/.grok-it/artifacts/，基于内容 SHA-256 去重。

视频生成

grok_video_generate: 根据描述生成一段 5 秒的动画

支持参数：

• prompt：视频描述
• image_url：参考图像（图生视频模式）
• duration：时长（1-30 秒）
• cache_video：是否缓存到本地

视频生成为异步任务，插件内置轮询逻辑（默认 2 秒间隔），超时 10 分钟。

架构设计

┌─────────────────────────────────────────────────┐
│           Claude Code / Codex                    │
│                  (Agent)                         │
└────────────────────┬────────────────────────────┘
                     │ MCP Protocol (stdio)
┌────────────────────▼────────────────────────────┐
│              Grok It MCP Server                  │
├─────────────────────────────────────────────────┤
│  Tools:                                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────────┐   │
│  │ x_search │ │ image_gen│ │  video_gen   │   │
│  └─────┬────┘ └────┬─────┘ └──────┬───────┘   │
│        │            │              │            │
│  ┌─────▼────────────▼──────────────▼───────┐   │
│  │           XAI Client                    │   │
│  │   (auto-refresh, retry, redaction)      │   │
│  └─────────────────┬──────────────────────┘   │
│                    │                           │
│  ┌─────────────────▼──────────────────────┐   │
│  │       Credential Resolver              │   │
│  │  OAuth (PKCE) ──→ fallback: API Key    │   │
│  └────────────────────────────────────────┘   │
├─────────────────────────────────────────────────┤
│  Cache:  ~/.grok-it/artifacts/ (SHA-256)       │
│  Token:  ~/.grok-it/auth.json                  │
└─────────────────────────────────────────────────┘
                     │
                     ▼
          xAI API (api.x.ai/v1)

设计原则：

• 模块化：auth、tools、cache、config 完全解耦
• 类型安全：全量 TypeScript + Zod schema 验证
• 最小依赖：运行时仅 2 个依赖
• 双模运行：既是 MCP Server（Agent 集成），也是独立 CLI

与同类工具对比

特性	Grok It	Hermes Agent	直接调用 xAI API
Claude Code 集成	✅ 原生插件	❌	❌ 需自行封装
Codex 集成	✅ 原生插件	❌	❌ 需自行封装
OAuth 订阅额度	✅	✅	❌ 仅 API Key
MCP 协议	✅	❌	❌
CLI 独立使用	✅	✅	❌
图像/视频缓存	✅ 自动去重	取决于实现	❌ 需自行管理
零配置启动	✅ npx	需安装	需编码

Grok It 的定位很明确：让 Claude Code 和 Codex 的用户以最低成本接入 xAI 生态。如果你的主力工具是 Hermes Agent，它已经内置了 Grok 支持；但如果你日常在 Claude Code 或 Codex 中工作，Grok It 就是最自然的选择。

实际使用场景

场景一：技术调研

“搜索 X 上最近一周关于 MCP Server 最佳实践的讨论”

Agent 调用 grok_x_search，自动附加日期范围，返回结构化的搜索结果。不再需要手动打开浏览器、筛选、复制粘贴。

场景二：内容创作配图

“为这篇关于微服务架构的文章生成一张概念图”

Agent 调用 grok_image_generate，图片自动缓存到本地，直接引用路径即可插入文档。

配置参考

环境变量	说明	默认值
XAI_API_KEY	API Key（OAuth 回退）	-
XAI_BASE_URL	自定义 API 端点	https://api.x.ai/v1
GROK_IT_TOKEN_STORE	Token 存储路径	~/.grok-it/auth.json
GROK_IT_CACHE_DIR	缓存目录	~/.grok-it/artifacts
GROK_IT_CACHE_VIDEO	默认缓存视频	false
GROK_IT_MAX_DOWNLOAD_BYTES	最大下载大小	50MB

安全设计

• PKCE 流程：OAuth 使用 SHA-256 challenge，防止授权码截获
• Token 不外泄：grok_auth_status 仅返回状态，不暴露 Token 内容
• 错误信息脱敏：所有错误日志自动 redact Token 和 verifier
• 文件权限：缓存文件 0o600，仅当前用户可读写
• 下载限制：默认 50MB 上限，防止异常大文件占用磁盘

总结

Grok It 的出发点很简单：xAI 开放了 OAuth 能力，SuperGrok 订阅用户有了免费的工具调用额度，而 Claude Code 和 Codex 是很多开发者的主力 Agent 环境——把两者连起来就是了。

如果你：

• 有 SuperGrok 或 X Premium+ 订阅
• 日常使用 Claude Code 或 Codex
• 需要 Agent 具备实时搜索 X、生成图像/视频的能力

那 Grok It 正好填补了这个空缺。

项目地址：https://github.com/Misty-Star/grok-it-mcp

# 两行命令开始体验
npm install -g grok-it-mcp
grok-it-mcp login --open