Grok It：让 Claude Code 和 Codex 直接调用 xAI/Grok 能力的 Agent 插件

背景

2026年5月中旬，xAI在accounts.x.ai悄悄开放了OAuth登录流程。这个动作意味着什么？SuperGrok或X Premium+的订阅用户，现在可以通过OAuth 2.0授权，直接调用Grok的内置工具——x_search、web_search、图像和视频生成，而且优先消耗订阅额度，跟API Key的付费计量完全走的是两套体系。

背后的信号很明确：只要你有SuperGrok订阅，在额度范围内，让Agent跑实时搜索和多模态生成的门槛基本归零。

第一个大规模落地这一能力的第三方工具是Hermes Agent v0.14.0。而受此启发，我做了

——一个MCP Server + Agent Plugin，让和也能无缝调用xAI/Grok的完整工具链。

项目代码完全开源（github.com/Misty-Star/…）。

Grok It 是什么

一句话概括：它是一个轻量级Agent插件，通过MCP（Model Context Protocol）协议，把xAI/Grok的能力暴露为标准工具调用，让Claude Code或Codex这种开发环境里的Agent可以直接用。

核心能力拆开来看：

• 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 "wa ves crashing at sunset" --duration 6 --json

第三步：安装插件到 Agent

 复制代码/plugin marketplace add Misty-Star/grok-it-mcp
/plugin install grok-it@grok-it

 复制代码codex plugin marketplace add Misty-Star/grok-it-mcp
codex plugin add grok-it@grok-it

在项目的.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/responsesAPI配合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的定位很明确：

。如果你主力用Hermes Agent，它已经内置了Grok支持；但日常在Claude Code或Codex中工作的话，Grok It就是最自然的选择。

实际使用场景

场景一：技术调研

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

场景二：内容创作配图

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

配置参考

环境变量	说明	默认值
XAI_API_KEY	API Key（OAuth回退）	-
XAI_BASE_URL	自定义API端点
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正好填补了这个空缺。

项目地址：github.com/Misty-Star/…

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