grok-mcp

把 Grok2API 上的 Grok Console 画图 / 改图 / 视频 / 对话搜索能力，同时提供：

MCP Server — 给 Claude Code / Codex / Cursor 等 Agent 调用
Web Console — 风格对齐 grok2api 管理端的创作台（Chat / Image / Video）

能力边界（Console）

默认模型全部来自 Grok Console：

模型	类型	网关接口能力
`grok-4.20-0309-non-reasoning`	对话	Chat Completions、Responses、Messages
`grok-4.20-0309-reasoning`	对话	Chat Completions、Responses、Messages
`grok-4.20-multi-agent-0309`	对话	Chat Completions、Responses、Messages
`grok-4.5`	对话	Chat Completions、Responses、Messages
`grok-4.3`	对话	Chat Completions、Responses、Messages
`grok-build-0.1`	对话	Chat Completions、Responses、Messages
`grok-imagine-image`	图像 + 图像编辑	Images Generations、Images Edits
`grok-imagine-image-quality`	图像 + 图像编辑	Images Generations、Images Edits
`grok-imagine-video`	视频	Videos

能力	Grok2API 路径	默认模型
文生图	`POST /v1/images/generations`	`grok-imagine-image`（`quality` → `grok-imagine-image-quality`）
图编辑	`POST /v1/images/edits`	同上（无单独 edit 模型 id）
视频	`POST /v1/videos/generations` + `GET /v1/videos/{id}`	`grok-imagine-video`
搜索 / 对话	`POST /v1/chat/completions`	搜索 `grok-4.3` / 对话 `grok-4.20-0309-non-reasoning`

架构

Claude Code / Codex / Cursor
        │  MCP HTTP  (/mcp)
        ▼
     grok-mcp  (本仓库)
        │  OpenAI-compatible HTTPS
        ▼
     Grok2API  →  Grok Console

网页控制台是另一条线：浏览器 → FastAPI → Grok2API。

仓库结构

grok-mcp/
├── src/grok_mcp/          # MCP server + Grok2API client
├── backend/app/           # FastAPI：Web API + /mcp 挂载 + 静态前端
├── frontend/              # React + Vite + Tailwind 控制台
├── examples/              # Claude Code / Codex 接入样例
├── scripts/               # 本地开发脚本
└── tests/

快速开始

1. 配置

cp .env.example .env

至少填写：

GROK2API_BASE_URL=http://127.0.0.1:8000
GROK2API_API_KEY=g2a_xxx_xxx
MCP_TOKEN=change-me-mcp-token
PUBLIC_BASE_URL=http://127.0.0.1:8790
ADMIN_PASSWORD=change-me
SESSION_SECRET=change-me-session-secret

2. 本地开发

uv sync --extra dev

# 终端 1 — API / MCP :8790
./scripts/dev-backend.sh

# 终端 2 — 前端 :5173
./scripts/dev-frontend.sh

浏览器打开 http://127.0.0.1:5173。

3. Docker

cd frontend && pnpm install && pnpm build && cd ..
docker compose up -d --build

服务默认：

Web：http://127.0.0.1:8790
MCP：http://127.0.0.1:8790/mcp
登录：ADMIN_USERNAME / ADMIN_PASSWORD

MCP 接入

Claude Code / CC Switch

推荐连接已部署的 grok-mcp HTTP 端点（见 examples/mcp.claude.json）：

{
  "mcpServers": {
    "grok": {
      "type": "http",
      "url": "http://127.0.0.1:8790/mcp",
      "headers": {
        "Authorization": "Bearer change-me-mcp-token"
      }
    }
  }
}

写入 ~/.claude.json 的 mcpServers，或项目 .mcp.json，然后重开会话。

Codex

见 examples/mcp.codex.toml：

[features]
rmcp_client = true

[mcp_servers.grok]
url = "http://127.0.0.1:8790/mcp"
bearer_token_env_var = "MCP_BEARER_TOKEN"
startup_timeout_sec = 30
tool_timeout_sec = 600

export MCP_BEARER_TOKEN="change-me-mcp-token"

MCP Tools

Tool	作用
`list_console_catalog`	静态 Console 模型表
`list_models`	目录 + 网关模型
`generate_image` / `edit_image`	画图 / 改图（下载到本地并返回可展示内容）
`generate_video` / `get_video_status` / `wait_video`	视频任务（完成后提供 `/media/...` 链接）
`web_search` / `chat`	搜索 / 对话

Web 页面

路由	说明
`/`	概览
`/creative`	创作台：对话 / 图片 / 视频
`/gallery`	本地图片历史
`/videos`	本地视频任务历史
`/settings`	MCP 接入向导 + 配置展示

设计说明

不重新实现 Grok 上游协议；只做 Grok2API 适配层。
Agent 配置里应出现本服务的 /mcp，不要把 g2a_ key 写进 Claude/Codex。
图片会物化到 GROK_MCP_MEDIA_DIR，并通过 MCP ImageContent / /media 提供给客户端。
上游图库清理优先使用 Grok2API 自带的媒体自动清理；本仓库默认不强制删除上游。

开发

uv sync --extra dev
uv run pytest

cd frontend
pnpm install
pnpm exec tsc -p tsconfig.app.json --noEmit
pnpm build

License

MIT

grok-mcp

grok-mcp

能力边界（Console）

架构

仓库结构

快速开始

1. 配置

2. 本地开发

3. Docker

MCP 接入

Claude Code / CC Switch

Codex

MCP Tools

Web 页面

设计说明

开发

License

Latest Blog Posts

MCP directory API