> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AihubMax MCP

> 在 Claude Desktop / Claude Code / Cursor 等 MCP 客户端里直接调用 AihubMax 的媒体生成能力

## 概述

**AihubMax MCP** 是 [AihubMax](https://api.aihubmax.com/console) 的官方 [MCP](https://modelcontextprotocol.io) 服务器，把平台的图像 / 视频 / 音频 / 文档生成、媒体理解与异步任务体系封装成一组工具，让 Claude Desktop、Claude Code、Cursor、Cline 等 MCP 客户端里的智能体直接调用——**发现模型、生成媒体、拿回结果**，全程在对话里完成。

它与「集成指南」里改 Base URL 接入 CLI、以及 Skills 并列，是第三种官方集成形态。

<Info>
  只需一个以 `sk-` 开头的 AihubMax API Key。前往 [AihubMax 控制台](https://api.aihubmax.com/console) 获取。
</Info>

## 前置条件

<CardGroup cols={2}>
  <Card title="Node.js 18+" icon="node-js">
    通过 `npx` 拉起 MCP 服务器需要 Node.js 18 或更高版本。[下载 Node.js →](https://nodejs.org/zh-cn/download/)
  </Card>

  <Card title="AihubMax API Key" icon="key">
    一个有效的 `sk-` 开头的 API Key。[前往控制台 →](https://api.aihubmax.com/console)
  </Card>
</CardGroup>

## 安装

在你的 MCP 客户端配置文件中加入以下内容，把 `sk-你的key` 换成自己的 API Key：

```json theme={null}
{
  "mcpServers": {
    "aihub": {
      "command": "npx",
      "args": ["-y", "github:cookaihq/aihub-mcp"],
      "env": { "AIHUBMAX_API_KEY": "sk-你的key" }
    }
  }
}
```

<Tip>
  首次拉取时 `npx` 会自动下载并编译，稍等片刻即可。之后启动会很快。
</Tip>

各客户端配置文件位置：

<CodeGroup>
  ```text Claude Desktop theme={null}
  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
  ```

  ```text Claude Code theme={null}
  项目根目录 .mcp.json，或用命令：
  claude mcp add aihub --env AIHUBMAX_API_KEY=sk-你的key -- npx -y github:cookaihq/aihub-mcp
  ```

  ```text Cursor theme={null}
  设置 → MCP → Add new server，填入上面的 command / args / env
  ```
</CodeGroup>

配置完成后重启客户端，看到 `aihub` 服务器已连接、工具已加载即可。

## 工具一览

配置成功后，智能体可直接使用以下 14 个工具：

| 工具                                                                           | 作用                               |
| ---------------------------------------------------------------------------- | -------------------------------- |
| `list_models`                                                                | 列出可用生成模型（图/视频/音频/文档），带可用性与定价摘要   |
| `describe_model`                                                             | 查看某模型的参数、示例、端点与定价                |
| `generate_image` / `generate_video` / `generate_audio` / `generate_document` | 提交生成任务；图像完成时可直接在对话内看图            |
| `get_task` / `wait_for_task`                                                 | 查询 / 阻塞等待异步任务（含进度）               |
| `download_asset`                                                             | 把产物下载到本地磁盘                       |
| `upload_file`                                                                | 本地文件 / URL / base64 → 可引用的公网 URL |
| `analyze_media`                                                              | 多模态理解：图 / 视频 / 音频 → 文本           |
| `ask_model`                                                                  | 问另一个 LLM（二次意见 / 试用）              |
| `create_embeddings`                                                          | 文本向量嵌入                           |
| `get_credits`                                                                | 查询额度与用量                          |

## 用法示例

在对话里直接用自然语言驱动即可，例如：

<Steps>
  <Step title="发现模型">
    「列一下可用的视频模型和价格」——智能体调用 `list_models`，返回模型清单、可用性与每次调用的价格。
  </Step>

  <Step title="生成媒体">
    「用 veo-3.1-text-to-video 生成一段海边日落的视频」——智能体调用 `generate_video` 提交任务，用 `wait_for_task` 等到产物 URL。
  </Step>

  <Step title="落盘 / 看图">
    「把刚才的视频下载到 \~/Downloads」——`download_asset` 落盘；图像类结果会直接显示在对话中。
  </Step>
</Steps>

<Note>
  产物 URL 有效期为 24 小时，请及时用 `download_asset` 保存。
</Note>

## 说明

* 本 MCP 与文档站内置的**文档搜索 MCP**（`docs.aihubmax.com/mcp`，用于检索本站文档）是两回事：前者调用生成 API，后者只读检索文档。
* 认证用环境变量 `AIHUBMAX_API_KEY`（也可用 `--api-key sk-...` 传入）；Base URL 默认 `https://api.aihubmax.com`，可用 `AIHUBMAX_BASE_URL` 覆盖。
* 源码与问题反馈：[GitHub](https://github.com/cookaihq/aihub-mcp)