# grok-mcp

把 [Grok2API](https://github.com/chenyme/grok2api) 上的 **Grok Console** 画图 / 改图 / 视频 / 对话搜索能力，同时提供：

1. **MCP Server** — 给 Claude Code / Codex / Cursor 等 Agent 调用  
2. **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` |

## 架构

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

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

## 仓库结构

```text
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. 配置

```bash
cp .env.example .env
```

至少填写：

```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. 本地开发

```bash
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

```bash
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`](examples/mcp.claude.json)）：

```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`](examples/mcp.codex.toml)：

```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
```

```bash
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 自带的媒体自动清理；本仓库默认不强制删除上游。

## 开发

```bash
uv sync --extra dev
uv run pytest

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

## License

MIT