UnificAlly MCP

UnificAlly MCP 服务

面向 UnificAlly API 的 MCP 服务。它让 AI 助手通过一个 API 密钥，使用 100 多种模型（Veo 3.1、Kling、Seedance、Hailuo、Grok Imagine、Nano Banana、Flux、GPT Image、Suno、ElevenLabs、Topaz）生成视频、图像、音乐、语音和音效，转录音频并提升媒体分辨率。

它适用于任何 MCP 客户端：Cursor、Claude Desktop、Claude Code、Cline、Windsurf、Zed、ChatGPT Desktop、Goose、n8n，以及你自己的代码。

安装

1. 在 https://unifically.com/api-keys 创建 API 密钥。新账号会获得 $0.50 余额，可用于测试。
2. 将服务添加到客户端配置中：

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "@unifically/mcp-server"],
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

该代码块可直接用于 Cursor（.cursor/mcp.json）、Claude Desktop（claude_desktop_config.json）、Cline 和 Windsurf（~/.codeium/windsurf/mcp_config.json）。保存后重启客户端。

Claude Code：

claude mcp add unifically -e UNIFICALLY_API_KEY=sk-... -- npx -y @unifically/mcp-server

{
  "context_servers": {
    "unifically": {
      "command": { "path": "npx", "args": ["-y", "@unifically/mcp-server"] },
      "env": { "UNIFICALLY_API_KEY": "sk-..." }
    }
  }
}

UNIFICALLY_API_KEY=sk-... npx -y @unifically/mcp-server

此外，还提供托管服务 https://mcp.unifically.com/mcp，供接受 URL 的客户端使用。请参阅远程服务。

示例

向助手提出需求：

生成一张 16:9 的黄昏灯塔图像，然后生成一段以该图像为起始画面的 6 秒视频。

它会按顺序调用工具：

{ "name": "generate_image", "arguments": { "prompt": "a lighthouse at dusk, waves, warm light", "aspect_ratio": "16:9" } }

Generated image with google/nano-banana-pro. Result: https://files.unifically.com/image/....png [task_id: 7f3c...]

{ "name": "generate_video", "arguments": { "prompt": "slow push in, waves rolling", "image_url": "https://files.unifically.com/image/....png", "duration": 6 } }

每个生成工具都会等待任务完成并返回媒体 URL。结构化结果如下：

{
  task_id: string,
  status: "completed" | "pending" | "processing",
  output: { video_url?, image_url?, audio_url?, image_urls?, audio_urls?, text? },  // when completed
  model: string,
  cost_usd?: number
}

在底层，每次调用都会向 UnificAlly API 发送一个请求（POST /v1/tasks，包含 { model, input }，然后调用 GET /v1/tasks/{id}），与 API 文档中所示的方式相同。

工具

每个工具都会设置全部四个 MCP 提示。七个会消耗余额的工具均标记为 destructiveHint: true 和 idempotentHint: false，因此，即使客户端会自动批准只读工具，也仍会在付费运行前征求确认。生成失败不会收费。

支持的模型及其参数、id 和浏览器试用页面：

• 视频：Veo 3.1、Kling、Seedance、MiniMax Hailuo、Grok Imagine、Wan 3.0、Gemini Omni Flash 1.1
• 图像：Nano Banana、GPT Image 2、Flux.2 Pro、Qwen Image、SeeDream
• 音乐和音频：Suno、ElevenLabs
• 升级：Topaz Labs

list_models 会返回完整的实时目录。

工作方式

• 每个生成工具仅通过 prompt 工作。model 为可选项，可使用短别名（veo、kling、flux、nano-banana-2、seedance、tts、sfx、stt）或完整 ID，例如 google/veo-3.1-fast。
• 媒体字段（image_url、image_urls、end_image_url、reference_image_urls、audio_url、video_url）仅接受公开的 https URL。本地路径或 base64 字符串会触发错误，提示先上传。
• 不同模型的字段名称各不相同（Kling 使用 start_frame_url，Veo 使用 start_image_url，Seedance 使用 first_frame_url）。你传入 image_url，服务会将其重命名。服务不支持的字段参数应放在 provider_options 中，该参数也会覆盖映射。
• 服务不会保存各模型支持的时长、分辨率或宽高比。API 会检查参数值，并返回指出如何修正的 422 错误，且不收取费用。服务指令会要求助手在运行模型前阅读其在 docs.unifically.com/llms.txt 中的页面。
• 每个生成工具还接受 wait、callback_url、provider_options 和 confirm_cost。
• 错误以一句话返回：缺少密钥或密钥错误时返回 401，余额不足时返回 402（附充值链接），参数验证失败时返回包含 API 验证消息的 422；超时消息会提示助手使用 get_task 继续。遇到 429、5xx 和网络错误时，会采用退避策略重试。

上传

模型只能读取公开 URL，因此本地文件会先上传到 UnificAlly CDN。

1. upload_file { content_type: "image/png" } 会返回一次性 upload_url 和最终的 file_url。助手使用 curl 发送字节数据，shell 中不会包含任何 API 密钥：

   curl -X PUT '<upload_url>' --data-binary @photo.png
   

   URL 经过签名，只能使用一次，并会在约 5 分钟后过期。文件会保持完整质量。

2. upload_file { url } 会导入已经在线的文件。

3. upload_file { file_path } 会从磁盘读取文件，但仅限服务在本地通过 stdio 运行时使用。

不支持 base64 上传，且指令会要求助手绝不将用户的文件发送到其他主机。这两条规则都源于实际发生过的失误：由于 base64 大小限制，Agent 曾缩小用户的图片以满足要求；还有一个 shell 中没有密钥的 Agent 曾将私人照片上传到公开文件托管服务。

长时任务

高质量视频和完整歌曲可能需要几分钟才能完成。

• wait: false 会立即返回 { task_id, status: "pending" }。轮询 get_task，直到 status 为 "completed"。
• callback_url 也会立即返回，API 会将结果 POST 到你的 webhook。

任何任务都可以稍后通过 get_task 获取。

支出限制

默认情况下，所有限制均关闭。可按部署设置：

• UNIFICALLY_CONFIRM_COST_ABOVE=<usd>：价格高于此金额的调用会返回报价，只有助手使用 confirm_cost: true 重试后才会运行。
• UNIFICALLY_MAX_COST_PER_TASK=<usd>：价格高于此金额的调用会被拒绝。confirm_cost 无法覆盖此限制。
• UNIFICALLY_BLOCKED_MODELS=veo-quality,suno 或 UNIFICALLY_ALLOWED_MODELS=nano-banana-2,flux,tts：限制可运行的模型。
• UNIFICALLY_DISABLE_GENERATION=true：只读模式。浏览、dry_run_cost 和 check_balance 仍可使用。

环境变量

远程服务

MCP_TRANSPORT=http 会在 /mcp 上提供 Streamable HTTP，并在 GET /sse + POST /messages 上提供旧版 SSE。托管版本运行于 https://mcp.unifically.com/mcp。

每个调用方都发送自己的密钥，因此一个部署即可服务多个用户，并从各自的余额中扣费：

1. Authorization: Bearer <key>（推荐）
2. X-API-Key: <key>
3. ?api_key=<key>，适用于只能接收 URL 的客户端。查询字符串可能会出现在代理日志中，因此尽可能使用请求头。

{
  "mcpServers": {
    "unifically": {
      "url": "https://mcp.unifically.com/mcp",
      "headers": { "Authorization": "Bearer sk-..." }
    }
  }
}

对于 claude.ai（Settings、Connectors、Add custom connector），请将密钥放入 URL：https://mcp.unifically.com/mcp?api_key=sk-...。对于仅支持 stdio 的客户端，可使用 mcp-remote 进行桥接：

{
  "mcpServers": {
    "unifically": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.unifically.com/mcp", "--header", "Authorization: Bearer sk-..."]
    }
  }
}

HTTP 模式详情：

• Streamable HTTP 为无状态模式，因此可在任何反向代理后扩展，无需粘性会话。
• 无密钥的调用方可以运行 initialize、tools/list、resources/list、prompts/list 和 ping，以便目录读取工具列表。其他所有操作都会返回 401。无密钥流量按 IP 限速，并发消息数上限为 16。GET /.well-known/mcp-config 会返回仅包含一个必填设置（api_key）的 JSON Schema，GET /.well-known/mcp/server-card.json 会返回工具列表。
• 密钥会向 API 验证，验证结果会缓存；此外，每个 IP 都有失败验证次数上限。限速按密钥和账户分别执行，因此增加密钥不会提高单个账户的限额。批次最多包含 16 条消息，请求正文最大为 512 KB。
• 浏览器的 Origin 请求头会经过 DNS 重绑定验证。MCP 客户端不会发送该请求头，因此不受影响。
• 仅信任来自 UNIFICALLY_TRUSTED_PROXIES 的 X-Forwarded-For。提供的 Compose 文件会为其隔离网络设置 private；请勿在共享 LAN 上使用该设置。
• 余额为零的密钥仍可查询余额、列出和获取任务，以及查询作业价格，但无法启动作业（402）。
• GET / 会返回连接说明，GET /health 是无需身份验证的健康检查。

自托管

此仓库提供了 Dockerfile 和 docker-compose.yml，可通过每个请求的密钥运行 HTTP 传输。将容器置于 HTTPS 反向代理之后，将域名指向该容器，并使用 /health 进行健康检查。无需设置任何环境变量。对于共享部署，UNIFICALLY_CONFIRM_COST_ABOVE=1.00 是一个合理的默认值。

开发

git clone https://github.com/unifically-dev/unifically-mcp.git
cd unifically-mcp
npm install
cp .env.example .env       # add your UNIFICALLY_API_KEY
npm run dev

交互式检查工具：

npx @modelcontextprotocol/inspector npx -y tsx src/index.ts

测试：

npm test               # build + smoke test
npm run test:vitest    # full suite

故障排查

链接

• API 文档：https://docs.unifically.com
• API 密钥：https://unifically.com/api-keys
• 模型：https://unifically.com/models
• MCP 页面：https://unifically.com/mcp
• 支持：[email protected]，Discord

许可证

MIT