MCP Server

通过 Model Context Protocol 将任何兼容 MCP 的 AI 助手连接到 muapi.ai。连接后，你无需离开编辑器，就可以让助手生成图片、视频和音频、编辑媒体、查询余额等。

muapi 支持两种 MCP 传输模式：

模式适合场景要求
托管（Streamable HTTP）Cursor、Windsurf只需要 API Key
通过 CLI 使用 stdioClaude Code、Claude Desktop已安装 muapi CLI

Claude Code 用户： 请使用 stdio 传输（muapi mcp serve），不要使用托管 HTTP URL。Claude Code 的 HTTP MCP 客户端不会把工具注入 AI 上下文——服务器会显示“Connected ✔”，但实际上没有任何工具可以调用。stdio 是 Claude Code 中可靠可用的唯一方式。

Option 1 — Hosted Server（Cursor、Windsurf）

托管 MCP 服务器地址为 https://api.muapi.ai/mcp，遵循标准 Streamable HTTP 传输协议。无需安装任何东西，只需将 URL 和 API Key 添加到客户端。

不适用于 Claude Code。 Claude Code 的 HTTP MCP 客户端不会把工具注入 AI 上下文。请改用 Option 2（stdio）。

如果客户端没有 header 字段（例如 claude.ai 的连接器对话框、Claude Cowork 等），不要直接使用下面的裸 URL——它不包含 Key，服务器无法完成身份验证，所有工具调用都会因 API Key 错误而失败。请跳转到没有 header 字段的 claude.ai / Claude Cowork / 其他连接器 UI，使用将 Key 嵌入 URL 的形式。

在 muapi.ai/dashboard 获取 API Key

Cursor

打开 Cmd+Shift+P（或 Ctrl+Shift+P）→ Open MCP settings，然后在 mcp.json 中添加：

{
  "mcpServers": {
    "muapi": {
      "url": "https://api.muapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MUAPI_KEY"
      }
    }
  }
}

保存后重启 Cursor。

Windsurf

打开 Settings → MCP，然后添加：

{
  "mcpServers": {
    "muapi": {
      "serverUrl": "https://api.muapi.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MUAPI_KEY"
      }
    }
  }
}

claude.ai / Claude Cowork / other connector UIs with no header field

一些自定义连接器 UI——包括 claude.ai 自带的 Settings → Connectors → Add custom connector 对话框（网页版和桌面版）以及 Claude Cowork——只接受 URL。它们没有用于填写自定义 Authorization header 的字段，而且连接器会被内部保存，无法通过手动编辑配置文件来添加 header。此时请将 Key 直接嵌入 URL 路径：

https://api.muapi.ai/mcp/YOUR_MUAPI_KEY

这种形式与基于 header 的 URL 等价，但在只有 URL 输入框的地方也能使用。如果客户端支持 header，优先使用 Authorization: Bearer 形式——Key 放在 URL 中时可能会出现在服务器或代理日志里。

Other MCP clients

任何支持 Streamable HTTP 传输的客户端都可以连接。使用以下配置：

Option 2 — stdio via CLI（Claude Code + Claude Desktop）

运行 muapi CLI 作为本地 stdio MCP 服务器。需要先安装 CLI。

# 安装 CLI
npm install -g muapi-cli

# 设置 API Key
muapi auth configure --api-key "YOUR_KEY"

Claude Code（CLI——运行一次即可为当前项目注册）：

claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve

然后启动新的 Claude Code 会话。使用 claude mcp list 验证，你应该能看到 Type: stdio 和 ✔ Connected。

Claude Desktop——在 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 或 Windows 的 %APPDATA%\Claude\claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": {
        "MUAPI_API_KEY": "your-key-here"
      }
    }
  }
}

Available Tools（可用工具）

不同传输方式提供的工具略有差异：

传输方式工具数量说明
托管 HTTP（https://api.muapi.ai/mcp）19包含 search_models；不包含上传和社交工具
CLI stdio（muapi mcp serve）24额外提供 muapi_upload_file 和 5 个社交工具；不包含 search_models

Discovery（模型发现）

工具说明传输方式
search_models按关键词或类别（文生图、视频、音频等）搜索 muapi 模型目录仅托管服务

Image Generation（图片生成）

工具说明主要模型
muapi_upload_image上传 Base64 编码的图片字节并获取托管 image_url，适用于无法访问本地文件或无法自行出网的客户端（例如 claude.ai 连接器 UI）—
muapi_image_generate根据文本提示词生成图片flux-dev、flux-schnell、flux-kontext-dev/pro/max、hidream-fast/dev/full、midjourney、gpt4o、seedream、reve、qwen、wan2.1
muapi_image_edit根据文本提示词编辑或变换图片flux-kontext-dev/pro/max/effects、gpt4o、seededit、reve、midjourney、qwen

Video Generation（视频生成）

工具说明主要模型
muapi_video_generate根据文本提示词生成视频veo3、veo3-fast、veo3.1、veo3.1-fast、kling-master、wan2.1/2.2、seedance-pro/lite/2/2-fast、hunyuan、runway、pixverse、vidu、minimax-std/pro
muapi_video_from_image将图片制作成动画视频veo3、veo3-fast、veo3.1、veo3.1-fast、kling-std/pro/master、wan2.1/2.2、seedance-pro/lite/2/2-fast、midjourney、minimax-std/pro

Audio（音频）

工具说明
muapi_audio_create使用 Suno 创建原创音乐（提示词、标题、流派标签、纯音乐模式）
muapi_audio_from_text使用 MMAudio 生成音效或环境音

Image Enhancement（图片增强）

工具说明
muapi_enhance_upscaleAI 超分辨率放大
muapi_enhance_bg_remove移除背景
muapi_enhance_face_swap图片或视频换脸。图片模式：使用 source_url（人脸）和 target_url（目标图片）；视频模式：使用 source_url（人脸）和 target_url（目标视频），并设置 mode: "video"。
muapi_enhance_ghibli吉卜力风格转换

Video Editing（视频编辑）

工具说明
muapi_edit_lipsync将嘴部动作与音轨同步（sync、latentsync、creatify、veed）
muapi_edit_clipping从长视频中提取 AI 选择的精彩片段

Async Polling（异步轮询）

工具说明
muapi_predict_result通过 request ID 查询任意异步生成任务的状态和结果

Account & Keys（账户与 Key）

工具说明
muapi_account_balance查询当前 credit 余额
muapi_account_topup创建 Stripe checkout session 以充值
muapi_keys_list列出账户中的所有 API Key
muapi_keys_create创建新的 API Key
muapi_keys_delete按 ID 删除 API Key

File Upload（CLI stdio only）

工具说明
muapi_upload_file将本地文件上传到 muapi.ai，并获取可用于生成工具的托管 URL

托管 MCP 用户： muapi_upload_file 不支持托管 HTTP 服务器，因为它需要访问本地文件系统。如果客户端可以执行 shell 命令（并拥有自己的网络出口），请先通过 REST API 上传文件，再使用返回的 URL：

curl -X POST https://api.muapi.ai/api/v1/upload_file \
  -H "x-api-key: YOUR_MUAPI_KEY" \
  -F "file=@/path/to/your/image.png"
# → { "url": "https://cdn.muapi.ai/..." }

如果客户端完全无法出网（例如位于 claude.ai 连接器之后的沙箱 Agent，只能通过 MCP 工具调用通道访问 muapi），请改用 muapi_upload_image 工具——传入图片 Base64，它会返回托管的 image_url，然后可将该 URL 传给 muapi_image_edit、muapi_video_from_image 等工具。或者切换到包含 muapi_upload_file 的 CLI stdio 传输。

Social Publishing（CLI stdio only）

工具说明
muapi_social_accounts_list列出已连接的社交账户（YouTube、TikTok、Instagram）及其 ID
muapi_social_publish将媒体 URL 发布到已连接的社交账户。传入 scheduled_at（ISO 8601，例如 "2026-06-15T14:00:00Z"）即可改为定时发布
muapi_social_posts_list列出已安排、已发布、失败或已取消的帖子
muapi_social_posts_cancel取消定时帖子，或重新排队失败的帖子
muapi_social_connect获取连接新社交账户所需的 OAuth URL

Example Prompts（示例提示词）

连接客户端后，可以自然地向 AI 助手提出请求：

生成图片：

“使用 flux-dev 生成一幅黄金时刻的写实山湖图”

编辑图片：

“移除这张图片的背景”（附上图片 URL）

创建视频：

“使用 kling-master 制作一个 5 秒的电影感视频：机器人走过雨中的森林”

让照片动起来：

“把这张产品照片变成一个短循环视频”（附上图片 URL）

创建音乐：

“创建一段 30 秒的 Lo-fi 嘻哈音乐，只要纯音乐”

查询余额：

“我的 muapi credit 余额是多少？”

查找模型：

“muapi 上有哪些视频生成模型？”

How Async Generation Works（异步生成原理）

图片、视频和音频生成工具会立即返回 request_id：

{ "request_id": "abc123", "status": "processing" }

助手会自动轮询 muapi_predict_result，直到任务完成：

{
  "request_id": "abc123",
  "status": "completed",
  "outputs": ["https://cdn.muapi.ai/..."]
}

你也可以随时手动检查：

“检查请求 abc123 的状态”

Self-Hosted MCP Server（自托管 MCP 服务器）

如果团队希望运行自己的 MCP 服务器实例，muapi-mcp-server 仓库提供了一个独立的 FastAPI 服务器和完整工具目录。

git clone https://github.com/SamurAIGPT/muapi-mcp-server.git
cd muapi-mcp-server
pip install fastapi uvicorn requests pydantic
MUAPI_API_KEY=your_key python mcp_server.py

Troubleshooting（故障排查）

运行 claude mcp add 后工具在 Claude Code 中不可用

有两个独立原因，请分别检查：

  1. 传输方式错误。 如果使用 --transport http 注册了服务器，Claude Code 会显示“Connected ✔”，但工具不会注入 AI 上下文。请切换到 stdio：

    claude mcp remove muapi
claude mcp add muapi -e MUAPI_API_KEY=YOUR_MUAPI_KEY -- muapi mcp serve

  2. 没有重启会话。 MCP 工具在会话启动时加载。如果你在活跃会话中运行了 claude mcp add——包括让 Claude 自己完成设置——必须启动新会话，工具才会可用。

如果需要在当前会话中立即使用 muapi，可以直接调用 REST API：

# 提交任务
curl -X POST https://api.muapi.ai/api/v1/flux-schnell-image \
  -H "x-api-key: YOUR_MUAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "..."}'

# 轮询结果
curl https://api.muapi.ai/api/v1/predictions/{request_id}/result \
  -H "x-api-key: YOUR_MUAPI_KEY"

claude mcp list 显示 Connected，但工具无法调用

这几乎总是说明使用了 HTTP 传输。Connected 只代表服务器可访问，并不代表工具已经注入 AI 的工具命名空间。请切换到 stdio（见上文）。

如果已经使用 stdio，但调用工具返回 403 或身份验证错误，则 API Key 可能错误或已过期。请在 muapi.ai/dashboard 获取新 Key，然后重新添加服务器：

claude mcp remove muapi
claude mcp add muapi -e MUAPI_API_KEY=YOUR_NEW_KEY -- muapi mcp serve

claude.ai、Claude Cowork 或其他无 header 连接器出现 API Key / unauthorized 错误

这几乎总是因为将裸 URL（https://api.muapi.ai/mcp）粘贴到了连接器的 URL 字段，而该 UI 没有办法附加 Authorization header——因此根本没有发送 Key，所有工具调用都会鉴权失败。请删除连接器，然后使用将 Key 嵌入 URL 路径的形式重新添加：

https://api.muapi.ai/mcp/YOUR_MUAPI_KEY

参见没有 header 字段的 claude.ai / Claude Cowork / 其他连接器 UI。

出现 Not authorized: missing or invalid credentials 错误

CLI 从 ~/.config/muapi/config.json 读取 Key。该文件可能保留着以前安装时留下的过期或无效 Key——CLI 不会提醒你，而是静默返回 401。

运行 muapi auth login 自动获取新 Key（会提示输入邮箱和密码）：

muapi auth login

或者直接从 muapi.ai/dashboard 复制 Key：

muapi auth configure --api-key "YOUR_KEY"

保存 Key 后，重新添加 MCP 服务器，让 Claude Code 读取新配置：

claude mcp remove muapi
claude mcp add muapi -e MUAPI_API_KEY=YOUR_NEW_KEY -- muapi mcp serve

然后启动新的 Claude Code 会话。

Claude Desktop 显示“tools missing”，但服务器在终端中正常

Claude Desktop 在干净环境中启动 MCP 服务器，不会继承 shell 的环境变量。服务器虽然启动了，但由于缺少 MUAPI_API_KEY 无法加载。请在 claude_desktop_config.json 中显式传入 Key：

{
  "mcpServers": {
    "muapi": {
      "command": "muapi",
      "args": ["mcp", "serve"],
      "env": { "MUAPI_API_KEY": "your-key-here" }
    }
  }
}

search_models 不可用

search_models 只在托管 HTTP 传输上提供。如果使用 CLI stdio 服务器（muapi mcp serve），则不会有这个工具。

muapi_upload_file 不可用

muapi_upload_file 只在 CLI stdio 传输上提供。托管 MCP 的解决方式见上面的 File Upload 部分。

Related（相关文档）

MCP Server — Muapi Docs