Magic Hour

Magic Hour MCP 服务

基于 OpenAPI 的 MCP 服务，支持 Magic Hour 图像和视频生成与编辑、 音乐生成、上传、等待任务完成，以及检索现有音频项目。

启动时，此服务会读取 docs/openapi.json，并通过 FastMCP.from_openapi() 构建 MCP 工具。OpenAPI 规范提供端点覆盖范围，而 Magic Hour MCP 策略则补充面向 Agent 的异步轮询、上传和项目下载指南。

连接 Agent

托管创建端点：https://mcp.magichour.ai/

请按照 客户端设置指南 连接 Claude、Claude Code、Codex CLI 或 ChatGPT。连接后，调用 account_retrieve 验证 API 访问权限，并在生成前查看账户信息； 仅调用 ping 无法验证 API 密钥。

试试：“使用我的肖像创建一张电影感的太空飞行员静帧图，然后用缓慢推进的镜头 为其制作动画。保持我的脸部一致，等待渲染完成并展示最终视频。消费积分前， 请检查账户资格和费用。”

使用 workflow_guide_retrieve 获取按顺序排列的工具步骤和输出审核指南。 编码时如需搜索文档，请使用单独的 API Docs MCP。

文档：

• Magic Hour Agent 技能 - 媒体工作流、已发布示例和故障恢复指南
• user.md - 托管端点用户指南
• integration-handoff.md - FastAPI 挂载检查清单
• docs/detailed-step-by-step-integration.md - 完整后端集成指南
• docs/api-reference.md - 生成的 API 参考文档

评估付费工作流

使用工作负载评估指南 比较已完成的图像或视频任务，包括输入、模型、设置、 输出和费用。请查看当前模型限制 和计费选项：已消耗积分对应的美元 费用与账户充值所需的现金金额不同。例如，Creator annual 套餐需预付 $144，可获得 144,000 积分，足够生成 600 个启用音频的 Kling 3.0 720p 五秒视频（积分全额使用时每个 $0.24，税费另计）。音频、 更高分辨率和视频参考输入需要更多积分。

账户读取会验证 API 授权并返回账户信息；它不会针对特定请求提供价格或资格报价。当前 MCP 工具 契约不包含此类报价操作。工作流指南不会验证所请求的模型、源媒体或套餐访问权限。 创建付费项目前，请先厘清费用或访问权限方面的问题。

如需查看可检查的视频示例，已发布的图像转视频基准测试 提供源图像、请求、所有尝试和可下载结果。该测试通过 Magic Hour 比较模型， 但不能据此认定某个提供商的质量胜出，也不能证明人类接受这些片段。

积分和数据

MCP 生成会使用 Magic Hour 账户积分。无需订阅即可购买一次性积分包；未使用的积分永不过期。积分包包含适用的无水印导出和商业用途，但须遵守条款，且源内容必须具备相应权利。积分包不会解锁仅限订阅用户使用的模型或分辨率。

技术故障通常会在处理后返还积分；已完成但不满意的结果不会自动返还积分。等待超时并不代表项目失败——请使用现有项目 ID 继续操作。付款退款遵循单独的退款政策。

信任与数据使用说明了 Magic Hour 对客户提示词、上传内容和输出内容不用于训练的政策，以及根据功能而定的保留期限。

设置

pip install -e .

在本地运行

python main.py

本地 MCP 端点：

http://127.0.0.1:8000/

此本地开发服务运行在 /，而不是 /mcp。宿主应用挂载服务时会添加 /mcp。

默认情况下，请求会发送到 Magic Hour 生产 API：

https://api.magichour.ai

工具发现是公开的。调用工具需要身份验证。托管的 Claude 和 ChatGPT OAuth 连接器会在你登录并授权访问后处理令牌。对于手动使用 Bearer 的客户端，请提供你的 Magic Hour API 密钥：

Authorization: Bearer <magic_hour_api_key>

Agent 可以在以下位置发现托管服务卡片：

https://mcp.magichour.ai/.well-known/mcp/server-card.json

环境变量：

MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
MCP_OAUTH_ISSUER_URL=https://mcp.magichour.ai
MCP_OAUTH_RESOURCE_URL=https://mcp.magichour.ai

设置 MAGIC_HOUR_API_BASE_URL，即可改用模拟服务或其他 API 基础 URL：

MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py

只读工作流指南

workflow_guide_retrieve 接受 video-face-swap、image-editor、image-to-video、video-generator、lip-sync、ugc-ads、talking-photo 或 media-apis。它会返回输入项、产品和 API 文档 URL、准确的创建工具名称、按顺序排列的步骤、请求示例、后续编辑和审核标准。它不会发起 API 请求、消耗额度或验证账户访问权限。与其他工具一样，它需要使用现有的身份验证流程。

客户端还可以发现公开的 magic-hour://workflows/index 资源，并读取 magic-hour://workflows/{workflow}。UGC 使用 ai_ugc_ad_create_video，并需要准备好的图像、脚本和受支持的时长；图像合成则是单独的 Image Editor 调用。请保留返回的项目 ID，并使用 wait_for_video_project 获取完成后的文件。

例如，可以请求 image-to-video，直接将已获批准的产品照片制作成动画；审核完成的片段，并在之后的编辑中重复使用。只有在需要更改静态图像的外观，或源素材问题导致无法完成镜头时，才编辑静态图像。talking-photo 指南要求提供人像和现有音频文件；仅凭文本无法启动该工具。指南描述的是工作流，并不代表生成结果已经过预验证，也不代表账户符合使用资格。

这有助于连接此服务的助手选择工作流；但不会让未连接的消费级助手获得推荐或排名优势。

OAuth

此服务仅作为受 OAuth 保护的资源。授权服务器是 Magic Hour Web 应用（https://magichour.ai）：用户在那里登录并同意授权，随后该应用会返回一个 Magic Hour API 密钥作为访问令牌，此服务会将其传递给 API。生产环境需要设置 MCP_OAUTH_ISSUER_URL 和 MCP_OAUTH_RESOURCE_URL。请参阅 docs/future-oauth-support.md。

使用 MCP Inspector 测试

1. 启动服务。
2. 运行：

   npx @modelcontextprotocol/inspector
   

3. 在 Inspector 中：
   • 传输方式：Streamable HTTP
   • URL：http://127.0.0.1:8000/
   • 请求头：Authorization: Bearer <magic_hour_api_key>
4. 调用 ping。
5. 调用 video_assets_generate_presigned_url 或其他生成工具。

注意：

• FastMCP 会在启动时根据 OpenAPI 生成端点工具。
• 创建工具会立即返回 id 和 credits_charged。
• OpenAPI 的 operationId 值会被规范化为描述性的 snake_case 工具名称。
• 共享的 /v1/files/upload-urls 端点命名为 video_assets_generate_presigned_url。它接受 video、audio 和 image 项。
• 使用 wait_for_*_project 轮询任务。请按原样使用返回的 exact_download_urls；切勿追加过期元数据。
• 在受支持的情况下，图像和音频等待工具也会返回内嵌媒体。

运行 cd web && npm ci && npm run build，重新构建 MCP App UI 并进行类型检查。

文件上传

Magic Hour 不接受在工具参数中传入原始文件字节。流程如下：

1. 调用生成的共享上传 URL 工具 video_assets_generate_presigned_url
2. 将文件字节上传到返回的 upload_url
3. 将返回的 file_path 传入生成工具

直接使用公开媒体 URL 也可能有效，但上传后的 file_path 值更可靠。请从调用方上传字节，或使用专用上传桥接服务；托管的 MCP 服务绝不会读取调用方提供的本地文件系统路径。浏览器聊天需要单独的上传界面或桥接服务；请参阅 docs/future-chat-ui-handoff.md。

MCP 语音预设

AI Voice Generator 仅公开并接受 mcp_magichour/openapi_policies.py 中 APPROVED_VOICE_NAMES 里的精确 API voice_name 字符串。请将经过验证且获准的通用／非名人预设填入该元组，以便在下次部署时启用该工具。不会默认认为任何现有上游语音是安全的。允许列表为空时，Voice Generator 将不会出现在工具发现结果中，也无法调用。Voice Cloner 始终不会纳入 MCP。

MCP 策略会在启动时以及重新生成 docs/api-reference.md 时，移除上游语音描述、默认值、示例和 SDK 代码片段。每日 OpenAPI 同步不会扩大允许列表。请勿编辑 docs/openapi.json 来设置 MCP 语音：该文件仍是未经修改的上游 API 快照。Magic Hour 主产品和公共 API 均未更改。

MCP Meme Generator 仅公开通用的 Random 模板选项，以避免在其架构中出现公众人物模板名称。