Mage

官方

使用众多前沿模型生成 AI 图像、视频和音频，默认私密。

你可以用 Mage MCP 做什么？

生成前先询价 — 让助手在扣费前先报出图片、视频或音频生成的 Gems 费用。
生成媒体 — 用 Run 启动图片、视频或音频生成，然后等待完成并取回结果链接。
选择模型 — 列出推荐模型及其价格和取舍，或说明某个模型的字段、默认值和规则。
使用已保存的角色和参考 — 列出你的角色和参考，或提及像 @ana 这样的句柄，让助手将其传给模型。
查看历史和创作 — 列出最近 30 天的生成记录，或按内容、收藏集或日期搜索已保存的创作。
查看账户余额 — 显示已连接的 Mage 账户及其当前 Gems 余额。

托管 MCP 服务器

npx add-mcp 'https://mcp.mage.space/mcp'

可安装到 Claude Code、Codex、Cursor 等客户端

文档

从 Claude、ChatGPT、Grok 和 Cursor 使用 Mage

通过 Mage MCP 服务器将 Claude、ChatGPT、Claude Code、Grok 或 Cursor 连接到你的 Mage 账户，然后让你的助手生成图像、视频和音频，以 Gems 支付。

Mage MCP 服务器将 AI 助手连接到你的 Mage 账户。连接后，你可以让 Claude、ChatGPT、Claude Code、Grok 或 Cursor 选择模型、查询价格、生成图像、视频或音频片段，并带回结果。它还能读取你的生成历史和已保存的创作，并使用你保存的角色和参考素材。

https://mcp.mage.space/mcp

[!WARNING]

你的助手启动的每一次生成都会从你的账户中以 Gems 支付。你的助手可以先查询价格，你也可以随时断开连接。

连接你的助手

Claude

适用于网页版 Claude、桌面应用、移动应用和 Cowork。

打开 Connect Mage to Claude。连接器名称和 URL 已为你填写好。选择 Add。
选择 Connect。会打开一个 Mage 页面，如果你尚未登录，它会要求你登录。
检查页面是否显示了你正在连接的应用名称，然后选择 Connect。你会返回 Claude。
在聊天中，从 + 菜单下的 Connectors 中开启 Mage 连接器，然后提出你想制作的内容。

在 Team 或 Enterprise 计划中，需要由所有者先在 Organization settings → Connectors 下添加连接器。Free 计划允许一个自定义连接器。

ChatGPT

从 ChatGPT 的 Plugins 页面将 Mage 添加为个人插件。

打开 ChatGPT Plugins。
点击 Add，然后选择 Create MCP App。
在 Name 中输入 Mage，在 Server URL 中输入 https://mcp.mage.space/mcp，并在 Authentication 中选择 OAuth。将 Advanced OAuth settings 留空；无需客户端 ID 或客户端密钥。图标和描述为可选项。
查看通知，勾选 I understand and want to continue，然后点击 Create。
在打开的页面中登录 Mage，检查应用名称，然后选择 Connect。
从你的 Personal 插件中安装 Mage，开始一个 Work 聊天，并提及 @Mage。

[!NOTE]

如果找不到 Create MCP App，请在 ChatGPT 的 Settings → Security and login 中开启 Developer mode，然后返回 Plugins。更多详情请参阅 ChatGPT 的设置指南。

Claude Code

添加服务器，然后从 Claude Code 登录：

claude mcp add --transport http mage https://mcp.mage.space/mcp

在 Claude Code 中运行 /mcp，选择 mage，然后进行身份验证。会打开一个浏览器页面，供你登录 Mage 并选择 Connect。

如需使用 API 密钥代替登录：

claude mcp add --transport http mage https://mcp.mage.space/mcp \
  --header "Authorization: Bearer $MAGE_API_KEY"

Grok

将 Mage 添加为自定义 MCP 连接器。

打开 Grok connectors，选择 New Connector，然后选择 Custom。
输入 https://mcp.mage.space/mcp 并完成身份验证提示，以连接你的 Mage 账户。
开始对话，让 Grok 使用 Mage 创建图像、视频或音频。

在 Grok Business 或 Enterprise 中，团队管理员必须先在云控制台中配置该连接器。

Cursor

该按钮使用 Mage 的公共 OAuth 客户端 ID 安装 Mage；出现提示时登录 Mage。如果 Mage 已安装，请用此链接中的配置替换其现有配置。如果按钮无响应，请改为打开网页安装链接：它会从浏览器打开 Cursor，并显示相同的配置供你手动添加。

如需手动设置，请将以下条目添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "auth": {
        "CLIENT_ID": "https://cursor.com/mcp",
        "scopes": [
          "mage",
          "offline_access"
        ]
      }
    }
  }
}

客户端 ID 是公开的，无需客户端密钥。Cursor 使用静态 OAuth 配置打开 Mage 的授权页面。

你也可以使用 API 密钥连接：

{
  "mcpServers": {
    "mage": {
      "url": "https://mcp.mage.space/mcp",
      "headers": { "Authorization": "Bearer ${env:MAGE_API_KEY}" }
    }
  }
}

当应用通过登录连接时，Mage 会在共享任何内容之前显示请求方：应用名称、来源站点以及你之后返回的位置。访客会话无法连接应用；请先使用你的 Mage 账户登录。

你的助手可以做什么

工具	功能
`list_models`	列出推荐模型及其价格、各自最适合的用途和权衡；其余模型按需列出。
`get_model`	描述单个模型：其字段、允许值、默认值、规则和价格。
`estimate_cost`	在生成开始前为其定价。不收取任何费用。
`create_upload`	获取一个签名链接，用于从你的计算机上传文件，适用于能运行命令的助手。
`generate`	启动一次生成，以 Gems 支付。
`get_request`	等待生成完成并返回结果链接。
`cancel_request`	停止正在运行的生成。Gems 不予退还。
`get_account`	显示已连接的账户及其 Gems 余额。
`list_characters`	列出你的角色及其 `@handle`。
`create_character`	从图像链接保存一个私有角色，可选附带语音片段。
`delete_character`	删除你的某个角色。
`list_references`	列出你的服装、姿势、场景、物体和语音片段，可列出全部或某一类。
`create_reference`	从图像或音频链接保存一个私有参考素材。
`delete_reference`	删除你的某个参考素材。
`list_history`	列出你最近 30 天的生成记录，包括你在 Mage 中自行创建的记录。
`search_creations`	按内容、集合或日期搜索你保存的创作。

在请求中使用句柄提及已保存的角色或参考素材，例如“Make a portrait of @ana wearing @red-coat”，你的助手会将其传递给模型。

技能

Mage 技能在这些工具之上教会你的助手完成完整任务：产品拍摄、市场商品列表、广告变体、UGC 和无脸视频、YouTube 缩略图，以及 Mage 应用，从换脸和重新打光到视频编辑和口型同步。使用 npx skills add mage-space/skills 添加它们，或在 mage.space/skills 浏览带示例的技能。

你的助手使用哪个模型

除非你指定模型，否则你的助手使用 Mango 3 制作图像、使用 Cherry 2 Pro 制作视频、使用 Seed Audio 制作音频。它会在开始前告诉你模型和价格，并在出结果后，当某个替代方案的权衡更适合你正在做的事情时，可能会建议一个替代方案。

	图像	视频
默认	Mango 3	Cherry 2 Pro
同系列	Mango 3S（更便宜，最高 3K）、Mango 2（最高 4K）、Mango	Cherry Pro（4K）、Cherry、Cherry Mini（最便宜的 Cherry）
也推荐	Guava 2 Pro 和 Guava 2（照片级真实）、GPT Image 2.5 Flare（文字和精确编辑）	Lemon（首尾帧，片段最长 30 秒）

其他所有模型仅在你按名称要求时运行，例如“make it with Melon”或“use Nano Banana 2”。当某个模型更适合请求时，你的助手可能会建议它，例如用动漫模型制作动漫片段，并等待你的答复。我应该使用哪个模型？对它们进行了全面比较。

Cherry 2 Pro 是 Mage 最强大也最昂贵的视频模型，其价格会随分辨率和时长急剧上升。在起草阶段请要求使用 Cherry Mini 或 Lemon。

生成的工作方式

你的助手按上述方式使用 list_models 选择模型，并使用 get_model 读取其字段。
它使用 estimate_cost 检查价格，这也会捕获模型会拒绝的请求。视频的价格取决于其时长：Mage 在报价时会测量已在 Mage 上的视频，例如上传的文件或之前的结果，而从其他站点链接的视频仅在生成开始时测量。
它使用 generate 启动生成，这会扣除你的 Gems。每次生成都带有一个由你的助手生成的密钥，因此连接中断后的重试会返回同一次生成，而不会重复付费。
它使用 get_request 等待，直到结果就绪，并将链接提供给你。

结果会保留 30 天：下载你想保留的内容，或将其保存在 Mage 中。被审核标记为 NSFW 的结果会被如此标记。有关生成经历的状态，请参阅请求；有关 Gems 的计费方式，请参阅计费。

图像和文件

媒体输入，例如首帧、参考图像或要编辑的视频，都是链接：指向文件本身的公共 https 链接，或最大约 3 MB 的数据 URL。

Claude Code、Cursor 和其他能运行命令的助手可以从你的计算机上传文件：它们使用 create_upload 获取签名上传链接，将文件发送到该链接，然后像使用其他链接一样使用文件的新链接。文件最大可达 100 MB，并在 30 天后删除。每次上传只包含一个文件：修正后的文件会作为新上传，因为旧链接在最长 4 小时内可能仍显示第一个文件。
Claude、ChatGPT 和 Grok 聊天无法将你附加到聊天中的文件传递给 Mage。请改为分享指向该文件的直接链接，或使用已在 Mage 上的创作。
指向网页的链接，例如 YouTube 或 TikTok 视频，不是文件，会被拒绝。

管理已连接的应用

你连接的每个应用都会列在 MCP → Connected apps 中，包括你连接它的时间以及最后使用的时间。选择 Disconnect 可立即停止某个应用；在你再次连接它之前，它无法再使用你的账户或花费你的 Gems。在浮动导航中打开 MCP，然后选择 Connected apps。

限制

你的账户最多可同时运行 20 次生成，与 API 相同。
一个应用每分钟最多可进行 120 次工具调用。
get_request 每次调用最多等待 2 分钟；对于更长的生成，你的助手会再次调用它。

故障排除

Cursor 提示“Incompatible auth server: does not support dynamic client registration”：将 ~/.cursor/mcp.json 中现有的 Mage 条目更新为包含上述 Cursor 设置中的 auth 块，然后重新连接。仅提供服务器 URL 不包含 Mage 预注册的 Cursor 客户端 ID。
“Couldn't reach the MCP server”：检查 URL 是否完全为 https://mcp.mage.space/mcp，然后移除连接器并重新添加。
连接要求你再次登录：连接最长持续 180 天，之后应用会要求你再次批准。在 Mage 中断开连接也会结束它。
生成失败并显示 insufficient_gems：在 API → Billing 中添加 Gems 并重试。

本文档构建并托管于 Mintlify，一个开发者文档平台。