maginary-mcp

maginary-mcp

适用于 Maginary 的 Model Context Protocol 服务——一个面向图像和视频的抽象化 OpenRouter：约 20 个模型系列（GPT-image-2、Seedance 2、Sora 2、Nano Banana Pro、Flux……）共用一个 Midjourney 风格的 --flag 提示词。提供 16 个工具：完整的参数目录、生成／放大／变体／动画、聊天内注册、计费，以及支持钱包的 Agent 按次付费的 x402。

观看演示 →

为什么

Maginary 通过 Midjourney 风格的 --flag 提示词 DSL 调用异步 HTTP API。此服务：

• 向你的大模型提供完整的参数目录，让它能选择合适的标记
• 提供一次调用即可完成的 generate 工具，用于调用 POST /api/gens/
• 提供 get_generation 和 wait_for_generation，用于轮询直到任务进入终止状态
• 目录工具可离线使用（内置快照；启动时若能连接，会从在线文档端点刷新）

连接

这是一个 MCP 服务——你无需直接运行它；你的 AI 客户端（Claude Desktop、Cursor 等）会在幕后启动并与之通信。只需添加一个配置块，就可以开始聊天。

Claude Desktop

在 Claude Desktop 中：设置 → 开发者 → 编辑配置。此操作会打开 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）。添加：

{
  "mcpServers": {
    "maginary": {
      "command": "uvx",
      "args": ["--upgrade", "maginary-mcp"]
    }
  }
}

重启 Claude Desktop。让它生成图像——它会自动发现 Maginary 的工具。

还没有账户？ 没问题——Claude 会引导你完成注册（只需提供邮箱）。已有 API 密钥？将其添加到配置中即可跳过这一步：

"env": { "MAGINARY_API_KEY": "sk-mag-…" }

需要 Python 3.10+ 和 uv。也可以使用：pip install maginary-mcp。

配置

无需配置。对于 stdio 服务，最多只需设置一个变量：

变量	默认值	含义
MAGINARY_API_KEY	—	来自 app.maginary.ai/dashboard#api-keys 的 Bearer 令牌。跳过聊天内注册流程。无需此项也可使用目录工具。
MAGINARY_BASE_URL	https://app.maginary.ai/api	用于暂存环境或可自托管部署的覆盖值。
MAGINARY_MCP_LOG_LEVEL	INFO	标准 Python 日志级别；写入 stderr（stdout 保留用于 MCP JSON-RPC）。

其余变量仅适用于自行运行托管服务的情况（maginary-mcp-http，见下文）。扫描代码的目录页面也会列出这些变量；本地使用时可忽略。

变量（仅限托管）	默认值	含义
MAGINARY_MCP_HOST / MAGINARY_MCP_PORT	0.0.0.0 / 8642	HTTP 服务的绑定地址。
MAGINARY_PUBLIC_HOST	app.maginary.ai	当 MAGINARY_BASE_URL 是内部地址时，此值会通过 X-Forwarded-Host（以及 -Proto／-For）发送给后端，以便后端生成公开 URL。
MAGINARY_MCP_REQUIRE_AUTH	关闭	开启时，每次 /mcp 调用都需要 Bearer（OAuth 令牌或 API 密钥）；未提供时，服务会返回 401 和 WWW-Authenticate，并指向 /.well-known/oauth-protected-resource，Claude／ChatGPT 会据此启动登录流程。取舍是：仅使用钱包的 Agent 没有可发送的 Bearer，因此启用此限制后，必须先通过普通 HTTP（POST /api/gens/）完成首次 x402 付款，然后使用 POST /api/auth/wallet-account/ 获取的密钥连接；401 响应正文会说明这一点。
MAGINARY_OAUTH_ISSUER	https://app.maginary.ai/o	受保护资源元数据中指定的授权服务器（后端 django-oauth-toolkit）。
MAGINARY_MCP_RESOURCE_URL	https://mcp.maginary.ai/mcp	此服务的规范资源标识符（RFC 8707 audience）。此值也会由 /.well-known/mcp/server-card.json 公布。

托管（无需安装）— Streamable HTTP

直接将客户端连接到托管服务：https://mcp.maginary.ai/mcp。 无需安装——该服务支持多租户，因此每个请求都按其携带的凭据进行限定。有两种身份验证方式，选择适合客户端的一种：

连接（OAuth） — 适用于 Claude Desktop、claude.ai 及任何支持 MCP OAuth 规范的其他客户端。添加服务时无需任何请求头：

{
  "mcpServers": {
    "maginary": { "url": "https://mcp.maginary.ai/mcp" }
  }
}

在客户端中点击“连接”。系统会打开 app.maginary.ai 上的登录页面；登录并批准请求的权限范围后，客户端便会保存令牌供后续使用——无需生成或粘贴密钥。要求服务以 MAGINARY_MCP_REQUIRE_AUTH=1 运行；若未启用，则完全不会要求登录。

API 密钥 — 适用于不支持 OAuth 流程的客户端（或者你不想通过登录页面操作的情况）。在 app.maginary.ai/dashboard#api-keys 生成密钥并自行发送：

{
  "mcpServers": {
    "maginary": {
      "url": "https://mcp.maginary.ai/mcp",
      "headers": { "Authorization": "Bearer sk-mag-…" }
    }
  }
}

连接后，两种方式完全相同——工具和账户都相同。目录工具无需凭据即可使用；generate / get_generation / wait_for_generation 则需要凭据。使用以下命令自行运行托管服务：

在工具调用中付款（通过 MCP 使用 x402）

完全没有密钥？仍可调用 generate。如果额度不足（或没有账户），结果会包含 isError: true，顶层带有 x402 PaymentRequired 信息（accepts、resource 等），以及 error: "payment_required"。支持 x402 的 MCP 客户端——x402 SDK 的 x402MCPSession——会对 accepts[0] 签名，并在 _meta["x402/payment"] 中附上付款信息，再次调用同一工具。服务会将其作为 PAYMENT-SIGNATURE 转发给后端；后端会验证付款、在 Base 上完成结算，并为尚无账户的钱包创建账户。已结算的结果会在 _meta["x402/payment-response"] 和 x402_receipt 中包含链上收据。系统不会返回 API 密钥——后续请求会改用钱包签名的身份验证请求头（X-Wallet-Address、X-Wallet-Signature、X-Wallet-Timestamp）。 服务本身不处理付款逻辑；所有决策都由后端的 /api/gens/ 契约负责。

钱包签名身份验证

首次 x402 付款为钱包创建账户后，后续所有请求都通过钱包私钥对一条简短消息进行签名来完成身份验证。每个请求都必须包含以下三个请求头：

请求头	值
X-Wallet-Address	小写形式的 0x EVM 地址（42 个字符）
X-Wallet-Signature	对挑战字符串进行 EIP-191 personal_sign 后得到的十六进制签名
X-Wallet-Timestamp	Unix 秒数（整数）

挑战字符串如下：

Maginary: authenticate <address> at <timestamp>. This does not move funds.

其中 <address> 为小写形式，<timestamp> 与请求头中发送的 Unix 秒数相同。时间戳必须在服务器时钟前后 5 分钟内（允许最多 30 秒的未来时钟偏差）。无需管理 API 密钥——钱包本身就是凭据。

pip install "maginary-mcp[http]"
maginary-mcp-http          # serves /mcp on 0.0.0.0:8642 (MAGINARY_MCP_PORT to change)
# — or —
docker build -t maginary-mcp . && docker run -p 8642:8642 maginary-mcp

托管服务不会设置 MAGINARY_API_KEY（密钥随请求发送）。它还提供 /health、GET / 上的介绍页面、OAuth 受保护资源元数据，以及位于 /.well-known/mcp/server-card.json 的 MCP 服务卡片（实时工具列表、身份验证方式），供扫描裸 URL 的目录使用。

Claude Skill

该服务附带一个 Agent Skill，用于说明 --flag DSL、模型选择，以及异步的生成→轮询流程：

maginary-mcp --install-skill   # -> ~/.claude/skills/maginary-image-gen/SKILL.md

该 Skill 可独立使用——不支持 MCP 的宿主可以使用 DSL 和原始 REST 调用（POST /gens/ → 轮询）。连接服务后，Claude 会改为调用 search_parameters 获取权威的标志列表，并原生调用 generate/wait_for_generation。重新运行会更新它；除非传入 --force，否则会保护本地修改。 来源：src/maginary_mcp/SKILL.md。

工具

目录（无需身份验证）

• list_parameters(category?, status?, include_reserved=false) — 枚举目录
• search_parameters(query, category?, include_reserved=false) — 按文本搜索名称 / 别名 / 描述 / 示例
• get_parameter(name) — 获取一个标记的完整记录（规范名称或别名）

list_parameters 响应包含 categories / statuses 分类体系，list_parameters 和 search_parameters 响应都带有 source（live 与 bundled-snapshot）。

生成（需要身份验证）

• generate(prompt, callback_url?) — POST /api/gens/。支持 img2img：在提示词中放入图片 URL。多个 URL = 多输入合成。使用 --sref <url> 仅传递风格（而非 img2img）。
• upload_image(file_path, filename?) — 读取本地图片文件，并通过 POST /api/images/upload/ 上传。返回 CDN URL，可用于 img2img 提示词或 --sref。仅支持 Stdio 连接（托管环境：直接使用 URL 或 REST 端点）。
• execute_action(generation_uuid, action_type, parent_image_index?, prompt?, callback_url?) — POST /api/gens/{uuid}/actions/。对已完成生成的图片执行后续操作（放大、变化、平移、缩放、img2vid、重新生成）。
• get_generation(uuid) — GET /api/gens/{uuid}/。响应包含 processing_result.available_actions，其中映射了各个槽位对应的有效操作类型。
• wait_for_generation(uuid, timeout_s=45) — 轮询至 done / failed；timeout 结果表示仍在运行，请再次调用

使用示例

在支持 MCP 的客户端中完成配置后：

“在 maginary 目录中搜索与纵横比有关的内容。”

LLM 调用 search_parameters("aspect")，并获取包含取值、示例和支持模型的 --ar 条目。

“现在用旗舰模型生成一张 16:9 的电影感肖像。”

LLM 调用 generate("a cinematic portrait --ar 16:9 --flagship")，获取 uuid，然后调用 wait_for_generation(uuid)，并从最终记录中读取 image_urls[]。

“放大第一张图片。”

LLM 检查 processing_result.available_actions["0"]，发现 "upscale_2x"，调用 execute_action(uuid, "upscale_2x", 0)，获取新的 uuid，然后调用 wait_for_generation(new_uuid)。

“将这张照片编辑成水彩画风格。”（用户提供本地图片）

LLM 调用 upload_image("/tmp/photo.png") → 获取 CDN URL，然后调用 generate("https://cdn.maginary.ai/…/photo.webp reimagine as watercolor painting")。（仅限 stdio — 托管环境中，用户改为提供 URL。）

目录更新

• 启动时从 https://maginary.ai/docs/parameters.json 实时获取，超时时间为 5 秒。
• 内置快照 src/maginary_mcp/parameters_snapshot.json 在实时获取失败时用作后备（无网络、文档站点宕机等情况）。
• 维护者通过 python scripts/refresh_snapshot.py 手动刷新快照 — 刻意不将其打包进 wheel 构建，以确保新快照始终对应经过审核的提交。

list_parameters / search_parameters 响应中的 source 字段会告知你当前使用的是哪一种来源。

开发

cd mcp
python -m venv venv && source venv/bin/activate
pip install -e .
maginary-mcp   # runs on stdio; kill with Ctrl+D

许可证

MIT。