# MCP 媒体工具

> 在 Claude Code、Cursor、VS Code、Codex、Claude、ChatGPT 等 MCP 客户端里填一个地址、用浏览器登录，就能出图、做视频、做音乐、配音，查余额和调用记录

来源：https://qd.zsopc.com/docs/integrations/mcp

`https://qd.zsopc.com/v1/mcp` 是一个 MCP server（Streamable HTTP），把平台的出图、视频、音乐、语音接口做成 9 个工具。接进 Claude Code、Cursor、VS Code、Codex、Claude、ChatGPT 这类 MCP 客户端以后，用自然语言就能调用。

**不用复制 API Key**：在客户端里填上地址，客户端会打开浏览器，登录小战AIhub 账号、点「允许」就连上了，之后自动续期。计费、限流和调用记录都和直接调接口一样，花费记在登录的账号上。

> 知识库检索是另一个 MCP server（`https://qd.zsopc.com/mcp`），登录方式相同，见 [知识库 API & MCP](../reference/wiki-api.md)。两个可以同时接。

## 工具

| 工具 | 做什么 | 扣费 |
|---|---|---|
| `list_models` | 能用的模型、类别和价格（积分，1 元 = 60 积分），可按类别或关键词筛 | 免费 |
| `generate_image` | 文生图，或按参考图改图；最多等 25 秒，出来了直接回图片链接，没出来回任务号 | 按张 |
| `create_video` | 文生视频，或用首帧、首尾帧、参考图生视频；立即回任务号 | 按模型、分辨率、时长 |
| `generate_music` | 按描述或你的歌词一次做两首歌（含歌词与封面）；立即回任务号 | 按次 |
| `text_to_speech` | 文字转语音（MP3），可用预置音色或你克隆的音色；最多等 25 秒 | 按字符 |
| `get_task` | 图片、视频、音乐、语音任务的状态与结果 | 免费 |
| `list_voices` | 可用的预置音色与你克隆的音色 | 免费 |
| `get_balance` | 还能用多少积分 | 免费 |
| `search_logs` | 调用记录：模型、状态、花费、错误、任务结果 | 免费 |

- 图片、视频必须指定模型（模型会先调 `list_models` 看价格再选）；音乐默认 `suno-v6`，语音默认 `voice-tts-pro`。
- 参考图、首帧、尾帧只收公网 http(s) 链接；本地图片要先放到能公开访问的地址。
- 失败的任务自动退款。

## 接入

下面每个客户端都只需要地址 `https://qd.zsopc.com/v1/mcp`，第一次使用时按提示在浏览器里登录。名字 `xiaozhanai` 可以随意改。

### Claude Code

```bash
claude mcp add --transport http --scope user xiaozhanai https://qd.zsopc.com/v1/mcp
```

`--scope user` 让所有项目都能用（不加只对当前项目生效）。然后在 Claude Code 里输入 `/mcp`，选中 `xiaozhanai`（显示需要登录），选 **Authenticate**，浏览器会打开登录页。也可以在终端里运行 `claude mcp login xiaozhanai`。

### Cursor

全局配置 `~/.cursor/mcp.json`，或项目里的 `.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "xiaozhanai": {
      "url": "https://qd.zsopc.com/v1/mcp"
    }
  }
}
```

在侧栏 **Customize → MCPs** 里找到它，按提示登录。Cursor CLI 用 `agent mcp login xiaozhanai`。

### VS Code（GitHub Copilot）

所有工作区共用的配置在 `~/.copilot/mcp-config.json`，只给当前工作区用就放在工作区根目录的 `.mcp.json`：

```json
{
  "mcpServers": {
    "xiaozhanai": {
      "type": "http",
      "url": "https://qd.zsopc.com/v1/mcp",
      "tools": ["*"]
    }
  }
}
```

第一次连接时会打开浏览器登录；没有弹出的话，在 **MCP Servers** 里点这个 server 的菜单选 **Authenticate**。需要 VS Code 1.101 或更新的版本。还在用 `.vscode/mcp.json` 的话，写成 `{"servers": {"xiaozhanai": {"type": "http", "url": "https://qd.zsopc.com/v1/mcp"}}}`（VS Code 1.146 起这种写法已不推荐）。

### Codex

```bash
codex mcp add xiaozhanai --url https://qd.zsopc.com/v1/mcp
codex mcp login xiaozhanai
```

也可以直接写 `~/.codex/config.toml`，再运行 `codex mcp login xiaozhanai`：

```toml
[mcp_servers.xiaozhanai]
url = "https://qd.zsopc.com/v1/mcp"
```

ChatGPT 桌面版与 IDE 插件读的是同一份配置，也可以在它们的 **Settings → MCP servers** 里添加并点 **Authenticate**。远程机器上用 `codex mcp login xiaozhanai --no-browser`。

### Claude（网页、桌面、手机）

**Customize → Connectors → Add → Add custom connector**，填名字和地址 `https://qd.zsopc.com/v1/mcp`，按提示选择登录方式（推荐「Use Claude's published identity」），添加后点 **Connect**，在弹出的页面登录。免费账号可以添加 1 个自定义连接器。Team / Enterprise 由组织管理员在 **Organization settings → Connectors** 里添加，成员再各自 **Connect**。在网页或桌面版添加的连接器，手机上也能用。

### ChatGPT

在 <https://chatgpt.com/plugins> 点加号，选 **Add custom MCP server**，填名字和 **Server URL** `https://qd.zsopc.com/v1/mcp`，认证选 **OAuth**，按提示创建并安装，之后在对话里输入 `@` 选它。哪些套餐能添加自定义 MCP server 以 ChatGPT 帮助中心为准（目前主要面向 Business、Enterprise、Edu 工作区）。

### Gemini CLI

`~/.gemini/settings.json`：

```json
{
  "mcpServers": {
    "xiaozhanai": {
      "httpUrl": "https://qd.zsopc.com/v1/mcp"
    }
  }
}
```

然后在 Gemini CLI 里运行 `/mcp auth xiaozhanai`。

### 其它客户端

支持远程（Streamable HTTP）MCP server 和 OAuth 登录的客户端，只填地址 `https://qd.zsopc.com/v1/mcp` 即可，登录按标准 MCP 授权流程自动进行。

以上写法依据 2026 年 11 月各客户端的官方文档；客户端改版后请以它们的文档为准。

## 用 API Key

没有浏览器的环境（CI、服务器）、不支持 OAuth 登录的客户端，或者从国内入口 `zsopc.com` 接入时，改用 API Key：在 [API Keys](https://qd.zsopc.com/dashboard/keys) 创建一把，放进请求头 `Authorization: Bearer sk-gpushare-xxx`（或 `x-api-key: sk-gpushare-xxx`）。不支持把 Key 写在地址里。

```bash
claude mcp add --transport http xiaozhanai https://qd.zsopc.com/v1/mcp \
  --header "Authorization: Bearer sk-gpushare-xxx"
```

```json
{
  "mcpServers": {
    "xiaozhanai": {
      "url": "https://qd.zsopc.com/v1/mcp",
      "headers": { "Authorization": "Bearer ${env:XIAOZHANAI_API_KEY}" }
    }
  }
}
```

Codex 用 `bearer_token_env_var = "XIAOZHANAI_API_KEY"`（填的是**环境变量的名字**），或 `codex mcp add xiaozhanai --url https://qd.zsopc.com/v1/mcp --bearer-token-env-var XIAOZHANAI_API_KEY`。

## 用起来

直接说要什么：「用 gpt-image-2 画一张海报，主题是……」「做一段 5 秒 720p 的视频：……，做好了把链接给我」。模型会先用 `list_models` 选模型，再调生成工具；视频和音乐要几分钟，模型会过一会儿用 `get_task` 去查结果。

## 常见问题

- **登录能保持多久？** 连接会自动续期，一直在用就一直有效；90 天没有用过才需要重新登录（浏览器里还登录着的话只要再点一次「允许」）。
- **怎么断开？** 在控制台 [我的连接](https://qd.zsopc.com/dashboard/connections) 里能看到每个用浏览器登录的应用、最近使用时间和本月花费，点「断开」立即生效。找回或重设密码会断开全部连接；注销账号同理。
- **企业员工能用吗？** 能，规则与 Deski 桌面端相同：企业管理员在企业控制台关闭某位员工的 Deski 权限后，这位员工的连接会一并断开，也不能再登录新的。
- **登录页显示「未验证的应用」？** 说明这个应用不在已识别名单里。确认是你自己刚刚在客户端里发起的登录，并核对页面上显示的回跳地址，再点「允许」。

## 说明

- **扣费与直接调接口相同**：每次生成都按模型价格从登录的账号（或 API Key 所在账号）扣积分。工具的 `idempotency_key` 参数与接口的 `Idempotency-Key` 头同义：同一把键、同样的参数重发不会重复扣费。
- **限流**：与普通 API Key 相同的并发与每分钟次数限制。
- **余额用完以后**：`get_balance`、`list_models`、`search_logs` 照常能用；查任务（`get_task`，以及生成工具里的等待）和列音色（`list_voices`）与直接调接口一样需要余额大于 0。
- **还没做成工具的**：数字人、声音克隆、智能剪辑，请直接调 [媒体 API](../reference/media-apis.md)。
