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

# MCP 插件安装

> 为 Claude Code、Cursor、VS Code、Windsurf、Codex CLI、Hermes Agent 或 OpenClaw 安装 MeiGen MCP,分钟级配置。支持 GPT Image 2、Midjourney V8.1、Seedance 2.0、Veo 3.1 等图像与视频模型。开源,生成消耗积分。

## 前提条件

* 已安装 **Node.js 18+**
* 至少一个生成提供商(`generate_image` / `generate_video` 用):
  * **MeiGen Cloud** — 从 [meigen.ai](https://www.meigen.ai) 获取 API Key（设置 → API Keys）
  * **ComfyUI** — 运行中的 ComfyUI 服务器（[安装指南](https://github.com/comfyanonymous/ComfyUI)）
  * **OpenAI 兼容 API** — 自带 Key，支持 Together AI、Fireworks AI、OpenAI 等任意供应商

<Tip>
  无需提供商即可开始使用。画廊搜索、提示词增强和灵感工具无需任何 API Key 即可运行。
</Tip>

***

## 安装

### Claude Code 插件（推荐）

<Steps>
  <Step title="安装插件">
    ```bash theme={null}
    # 添加插件市场
    /plugin marketplace add jau123/MeiGen-AI-Design-MCP

    # 安装
    /plugin install meigen@meigen-marketplace
    ```

    安装后**重启 Claude Code**（关闭并重新打开，或打开一个新的终端标签页）。
  </Step>

  <Step title="配置提供商">
    启动一个新的 Claude Code 会话并运行 `/meigen:setup`。安装向导引导你完成提供商选择和 API Key 配置,自动适配 macOS / Linux / Windows shell。

    或直接设置环境变量(参见下方[提供商配置](#提供商配置))。
  </Step>

  <Step title="开始使用">
    用自然语言让 Claude 生成图片或视频:

    * *"生成一个咖啡店的极简 Logo"*
    * *"把这张图动画化成一段 5 秒视频"*
    * *"在画廊中搜索赛博朋克城市风景"*
    * *"增强这个提示词:一只猫在太空中"*
  </Step>
</Steps>

### Cursor / VS Code / Windsurf / Roo Code

一行命令写好每个编辑器的 MCP 配置文件:

```bash theme={null}
npx meigen init cursor      # 写 .cursor/mcp.json
npx meigen init vscode      # 写 .vscode/mcp.json
npx meigen init windsurf    # 写 ~/.codeium/windsurf/mcp_config.json
npx meigen init roo         # 写 .roo/mcp.json
npx meigen init claude      # 写 .mcp.json (Claude Code 项目级)
```

配置写好后,在 shell 设置 `MEIGEN_API_TOKEN` 并重启宿主。**不支持 `/meigen:setup` slash 命令的宿主**,直接在 meigen server entry 的 `env` 块加 token。

### OpenAI Codex CLI

Codex 用 TOML。在 `~/.codex/config.toml` 加:

```toml theme={null}
[mcp_servers.meigen]
command = "npx"
args = ["-y", "meigen@latest"]

[mcp_servers.meigen.env]
MEIGEN_API_TOKEN = "meigen_sk_..."
```

### Hermes Agent (NousResearch)

Hermes 原生支持 MCP。在 `~/.hermes/config.yaml` 加:

```yaml theme={null}
mcp_servers:
  meigen:
    command: "npx"
    args: ["-y", "meigen@latest"]
    env:
      MEIGEN_API_TOKEN: "meigen_sk_..."
    timeout: 600          # 视频生成可能 5-10 分钟
    connect_timeout: 120  # 首次 npx 拉包可能慢
```

<Warning>
  `timeout: 600` 和 `connect_timeout: 120` 这两个覆盖很重要 — Hermes 默认(120s / 60s)是给短命令调好的,视频生成或首次 npx 下载会超时。
</Warning>

### 独立 CLI 模式(不需要 MCP 宿主)

适合 shell 脚本、CI 流水线以及不跑 MCP 宿主的终端用户:

```bash theme={null}
# 设置 token
export MEIGEN_API_TOKEN=meigen_sk_...

# 生图
npx meigen gen --prompt "阳光厨房里的三花猫"

# 指定模型 + 比例
npx meigen gen -p "logo design" -m midjourney-v8.1 -r 1:1

# 带参考图(本地路径自动上传)
npx meigen gen -p "产品 hero shot" --ref ~/Desktop/bottle.jpg

# 只提交不等待 — 输出 generationId(适合 CI)
npx meigen gen -p "..." --no-wait

# JSON 输出(适合 jq 管道)
npx meigen gen -p "..." --json | jq -r '.imageUrls[0]'
```

图像默认保存到 `~/Pictures/meigen/` — 改保存位置见[输出目录](#输出目录)。

### OpenClaw

从 [ClawHub](https://clawhub.ai/plugins/meigen-ai-design) 安装完整插件（包含命令、技能和 MCP 服务器）：

```bash theme={null}
openclaw bundles install clawhub:meigen-ai-design
```

或仅安装技能（不含命令/agents）：

```bash theme={null}
npx clawhub@latest install creative-toolkit
```

<Note>
  OpenClaw 使用 [Agent Skills](https://agentskills.io) 开放标准。无需配置 MCP — Skill 会处理一切。
</Note>

### 其它 MCP 兼容宿主

任意吃 stdio MCP 的宿主,把这个加到它的配置文件:

```json theme={null}
{
  "mcpServers": {
    "meigen": {
      "command": "npx",
      "args": ["-y", "meigen@latest"],
      "env": {
        "MEIGEN_API_TOKEN": "meigen_sk_..."
      }
    }
  }
}
```

***

## 提供商配置

配置一个或多个提供商。当多个提供商可用时，插件按以下顺序选择：MeiGen → ComfyUI → OpenAI 兼容。你可以在每次请求时覆盖此设置。

### MeiGen Cloud

最简单的入门方式。MeiGen 的托管 API 汇集了 OpenAI、Google、ByteDance、Midjourney、xAI、Black Forest Labs、Alibaba、Agnes 的图像与视频模型 — 无需 GPU。当前清单用 `list_models` 查，能力与定价见[模型对比](/zh/features/models)。

| 变量                 | 值                          |
| ------------------ | -------------------------- |
| `MEIGEN_API_TOKEN` | 以 `meigen_sk_` 开头的 API Key |

获取 API Key：在 [meigen.ai](https://www.meigen.ai) 登录 → 点击头像 → **设置** → **API Keys** → 创建新 Key。

<Warning>
  API Key 只能使用**购买积分**，不能使用每日免费积分。在通过插件生成前，请确保你的账户有购买积分。
</Warning>

### 自带 API（OpenAI 兼容）

接入**任意**符合 OpenAI 接口规范的生图 API — Together AI、Fireworks AI、DeepInfra、硅基流动、OpenAI，或你自己的端点。

| 变量                | 值                                       |
| ----------------- | --------------------------------------- |
| `OPENAI_API_KEY`  | 你的供应商 API Key                           |
| `OPENAI_BASE_URL` | API 端点（如 `https://api.together.xyz/v1`） |
| `OPENAI_MODEL`    | *（可选）* 供应商的模型名                          |

设置 `OPENAI_BASE_URL` 指向你的供应商端点。如果省略，默认使用 OpenAI 的 API。

### ComfyUI（本地）

在你自己的 GPU 上运行图片生成，完全控制模型、采样器和工作流。免费使用 — 无需 API Key。

| 变量            | 值                                         |
| ------------- | ----------------------------------------- |
| `COMFYUI_URL` | ComfyUI 服务器地址（默认：`http://127.0.0.1:8188`） |

**要求**：

1. ComfyUI 必须正在运行且可通过配置的 URL 访问
2. 你需要至少导入一个工作流模板 — 参见 [ComfyUI 指南](/zh/mcp/comfyui)

<Note>
  ComfyUI 串行处理：每次只生成一张图片。
</Note>

***

## 输出目录

MCP 工具和独立 CLI 都会把生成结果落盘到本地。

| 类型 | 默认位置                 | 覆盖变量                      | Linux 备选           |
| -- | -------------------- | ------------------------- | ------------------ |
| 图片 | `~/Pictures/meigen/` | `MEIGEN_OUTPUT_DIR`       | `XDG_PICTURES_DIR` |
| 视频 | `~/Movies/meigen/`   | `MEIGEN_VIDEO_OUTPUT_DIR` | `XDG_VIDEOS_DIR`   |

设置方式与提供商变量相同 — 写在 MCP 配置的 `env` 块里，或在 shell 里 export 供 CLI 使用。

***

## 验证安装

安装完成后，向你的 AI 助手提问：

> "列出可用的模型"

如果配置正确，它会调用 `list_models` 工具并显示你所有已配置提供商的可用模型。

***

## 使用

安装完成后，用自然语言向 AI 助手提问即可——例如"生成一幅水彩风景画，16:9 宽高比"。完整工具清单见[概览](/zh/mcp/overview)。

***

## 故障排除

<AccordionGroup>
  <Accordion title="'No image generation providers configured'" icon="circle-exclamation">
    未设置任何提供商。在 Claude Code 上运行 `/meigen:setup`(交互向导)。在其它宿主(Cursor、Codex、Windsurf、Hermes Agent 等)上,直接在 MCP 配置文件加 env var:

    * MeiGen:`MEIGEN_API_TOKEN`
    * OpenAI 兼容:`OPENAI_API_KEY`
    * ComfyUI:`COMFYUI_URL`(并导入一个工作流)

    然后重启宿主。
  </Accordion>

  <Accordion title="'Insufficient credits'（MeiGen）" icon="circle-exclamation">
    API Key 只能使用购买积分，不能使用每日免费积分。请在 [meigen.ai](https://www.meigen.ai) 购买积分。
  </Accordion>

  <Accordion title="ComfyUI 连接被拒绝" icon="circle-exclamation">
    1. 确保 ComfyUI 正在运行（在 ComfyUI 目录中执行 `python main.py`）
    2. 检查 `COMFYUI_URL` 是否与 ComfyUI 启动时显示的地址一致（默认：`http://127.0.0.1:8188`）
    3. 如果在其他机器上运行，确保端口可访问
  </Accordion>

  <Accordion title="ComfyUI 生成失败" icon="circle-exclamation">
    1. 打开 ComfyUI Web UI 检查错误信息
    2. 使用 `comfyui_workflow view` 检查工作流节点
    3. 确保工作流中引用的检查点模型已下载
    4. 先尝试在 ComfyUI 中手动运行工作流
  </Accordion>

  <Accordion title="插件未出现在工具列表中" icon="circle-exclamation">
    1. 确保已安装 Node.js 18+
    2. 尝试直接运行 `npx -y meigen` 检查是否有错误
    3. 重启编辑器
    4. 检查 MCP 配置 JSON 是否有效
  </Accordion>

  <Accordion title="生成超时" icon="circle-exclamation">
    生成时间因模型和提供商而异。MeiGen Cloud 图片模型通常 5-60 秒；视频生成需要 1-8 分钟。ComfyUI 取决于你的 GPU 性能。

    超时上限：`generate_image` 最多等 5 分钟，`generate_video` 最多等 8 分钟，独立 CLI 和 ComfyUI 均为 5 分钟。
  </Accordion>

  <Accordion title="配置修改未生效" icon="circle-exclamation">
    修改 `~/.config/meigen/config.json` 或环境变量后，你必须重启编辑器（或启动新的 Claude Code 会话）才能使更改生效。
  </Accordion>
</AccordionGroup>