io.github.magichourhq由 GitHub 账号 magichourhq 发布v0.1.1更新于 Nov 4, 2026
Create and edit images and video, generate music, and retrieve existing audio projects.
托管版 Magic Hour 服务器，让助手用 Magic Hour 额度生成和编辑图片、视频，制作音乐，并获取已完成的媒体文件。
Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。
把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。
阅读 https://sourceweft.com/mcp/io.github.magichourhq%2Fmagic-hour/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。把它添加到你客户端的 mcpServers 配置中。
{
"mcpServers": {
"magic-hour": {
"type": "http",
"url": "https://mcp.magichour.ai/"
}
}
}OpenAPI-backed MCP server for Magic Hour image and video generation and editing, music generation, uploads, completion waiting and retrieval of existing audio projects.
At startup, this server reads docs/openapi.json and builds MCP tools with
FastMCP.from_openapi(). The OpenAPI spec supplies endpoint coverage, while
Magic Hour MCP policies add agent-facing guidance for async polling, uploads,
and project downloads.
Hosted creation endpoint: https://mcp.magichour.ai/
Follow the client setup guide
for Claude, Claude Code, Codex CLI or ChatGPT. After connecting, call
get_account_info to verify API access and inspect the account before generation;
ping alone does not validate the API key.
Try: “Use my portrait to create a cinematic space-pilot still, then animate it with a slow camera push. Keep my face consistent, wait for the render and show the finished video. Check account eligibility and cost before spending credits.”
Use get_workflow_guide for the ordered tool steps and output review.
After a tool-name update, refresh the client’s cached tool catalog or reconnect.
Use the names returned by tools/list; dated example receipts keep their original IDs.
For documentation search while coding, use the separate
API Docs MCP.
Docs:
user.md - hosted endpoint user guideintegration-handoff.md - FastAPI mount checklistdocs/detailed-step-by-step-integration.md - full backend integration guidedocs/api-reference.md - generated API referenceUse the workload evaluation guide to compare a finished image or video job, including its inputs, model, settings, output and cost. Check the current model limits and billing options: the dollar cost of consumed credits and the cash needed to fund an account are different. For example, Creator annual costs $144 paid upfront for 144,000 credits, enough for 600 five-second Kling 3.0 videos at 720p with audio off ($0.24 each at full credit use, before tax). Audio, higher resolutions and video-reference inputs cost more credits.
The account read verifies API authorization and returns account information; it is not a request-specific price or eligibility quote. The current MCP tool contract has no such quote operation. A workflow guide does not validate the requested model, source media or plan access. Resolve unclear costs or access before creating a paid project.
For inspectable video examples, the published image-to-video benchmark provides source images, requests, all attempts and downloadable results. It compares models through Magic Hour and does not establish a provider-quality winner or human acceptance of the clips.
MCP generations use Magic Hour account credits. You can buy a one-time credit pack without a subscription; unused credits never expire. Packs include applicable watermark-free exports and commercial use, subject to the Terms and rights in your source content. They do not unlock subscription-only model or resolution access.
Technical failures generally return credits after processing; completed but unsatisfactory results do not automatically return credits. A wait timeout is not proof of project failure—resume with the existing project ID. Payment refunds follow the separate refund policy.
Trust & Data Use explains Magic Hour's no-training policy for customer prompts, uploads and outputs, and feature-dependent retention.
Local MCP endpoint:
This local dev server runs at /, not /mcp. The host app adds /mcp when it mounts the server.
By default, requests go to the production Magic Hour API:
Tool discovery is public. Tool calls require authentication. Hosted Claude and ChatGPT OAuth connectors handle the token after you sign in and authorize access. For manual bearer clients, include your Magic Hour API key:
Agents can discover the hosted server card at:
Environment variables:
Override MAGIC_HOUR_API_BASE_URL to use a mock or another API base:
get_workflow_guide accepts video-face-swap, image-editor, image-to-video,
video-generator, lip-sync, ugc-ads, talking-photo or media-apis. It returns
inputs, product and API documentation URLs, exact creation-tool names, ordered
steps, example requests, follow-up edits and review criteria. It makes no API
request, spends no credits and does not verify account access. Like other tools, it requires the existing authentication flow.
Clients can also discover the public magic-hour://workflows/index resource and
read magic-hour://workflows/{workflow}. UGC uses create_spoken_ad_video with a
prepared image, script and supported duration; image composition is a separate
Image Editor call. Keep the returned project ID and use wait_for_video_project
to retrieve the finished file.
For example, ask for image-to-video to animate an approved product photo directly,
review the finished clip and reuse it for a later edit. Edit the still only when
the requested appearance must change or a source problem prevents the shot. The talking-photo guide
requires a portrait and an existing audio file; text alone cannot start that tool.
Guides describe workflows, not prevalidated generated outputs or account eligibility.
This helps assistants that connect to this server select workflows; it does not establish a recommendation or ranking benefit in unconnected consumer assistants.
This server is an OAuth protected resource only. The authorization server is the Magic Hour
web app (https://magichour.ai): users sign in and consent there, and it returns a Magic Hour
API key as the access token, which this server passes through to the API. Production requires
MCP_OAUTH_ISSUER_URL and MCP_OAUTH_RESOURCE_URL. See docs/future-oauth-support.md.
Streamable HTTPhttp://127.0.0.1:8000/Authorization: Bearer <magic_hour_api_key>ping.get_upload_urls or another generated tool.Notes:
id and credits_charged immediately.operationId values are normalized to descriptive snake_case tool names./v1/files/upload-urls endpoint is named get_upload_urls. It accepts video, audio, and image items.wait_for_*_project to poll jobs. Use exact_download_urls exactly as
returned; never append expiration metadata.Rebuild and type-check the MCP App UI with cd web && npm ci && npm run build.
Magic Hour does not accept raw file bytes inside tool arguments. The flow is:
get_upload_urlsupload_urlfile_path into the generated creation toolDirect public media URLs may work, but uploaded file_path values are more
reliable. Upload bytes from the caller or a dedicated upload bridge; the hosted
MCP server never reads caller-supplied local filesystem paths. Browser chat needs
a separate upload UI or bridge; see docs/future-chat-ui-handoff.md.
AI Voice Generator exposes and accepts only exact API voice_name strings in
APPROVED_VOICE_NAMES in mcp_magichour/openapi_policies.py. Populate that tuple
with verified approved generic/non-celebrity presets to enable the tool on the
next deployment. No existing upstream voice is assumed safe. An empty allowlist
omits Voice Generator from tool discovery and calls. Voice Cloner is always
excluded from MCP.
The MCP policy removes upstream voice descriptions, defaults, examples and SDK
snippets at startup and when regenerating docs/api-reference.md. Daily OpenAPI
syncs cannot expand the allowlist. Do not edit docs/openapi.json to set MCP
voices: it remains the unmodified upstream API snapshot. The main Magic Hour
product and the public API are unchanged.
MCP Meme Generator exposes only the generic Random template option, keeping
public-figure template names out of its schema.
来源：README.md，提交 47715fa
Choose a media workflow
Returns required inputs, ordered steps, example requests and review criteria for eight supported Magic Hour workflows. Use when planning a generation, not to run one. Requires authentication but does not check account eligibility or spend credits.
workflow必填Upload attached image
Uploads a PNG, JPEG or WebP image attached in ChatGPT to the connected Magic Hour account. Use this for native ChatGPT photo attachments instead of asking the chat's file runtime to PUT bytes to get_upload_urls. Pass the returned file_path to the existing image or video generation tool. Accepts one image up to 20 MiB. Does not generate media or spend generation credits.
image必填Ping
Checks that the Magic Hour server is reachable. Use for connectivity troubleshooting; it does not validate API credentials or account access. Makes no media or project changes.
无需输入参数。
Wait for Video Project
Polls a video project until it completes, errors, is canceled or times out. Use with the id returned by a video create tool. Read-only; returns download URLs when complete. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned. Does not inline video content.
id必填timeout_secondsmax_inline_downloadspoll_interval_secondsinclude_inline_downloadsWait for Image Project
Polls an image project until it completes, errors, is canceled or times out. Use with the id returned by an image create tool. Read-only; returns the project and download URLs, with optional inline image previews sharing an 8 MiB total limit. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned.
id必填timeout_secondsmax_inline_downloadspoll_interval_secondsmax_bytes_per_downloadinclude_inline_downloadsWait for Audio Project
Polls an audio project until it completes, errors, is canceled or times out. Use with the id returned by an audio create tool. Read-only; returns the project and download URLs, with optional inline audio previews sharing an 8 MiB total limit. After a timeout, resume with the same id rather than creating another generation. Use signed download URLs exactly as returned.
id必填timeout_secondsmax_inline_downloadspoll_interval_secondsmax_bytes_per_downloadinclude_inline_downloadsFetch Image Download
Fetch a completed project's image as inline MCP image content for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
max_bytesdownload_url必填Fetch Audio Download
Fetch a completed project's audio as inline MCP audio content for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
max_bytesdownload_url必填Fetch Video Download
Fetch a completed project's video as an embedded MCP binary resource for compatible clients. Use the exact signed download URL, including query parameters. Requires HTTPS at the configured Magic Hour media host. Read-only; limited to 8 MiB, or a smaller requested max_bytes. Use the signed URL directly for larger files.
max_bytesdownload_url必填Get account info
Returns credit balance and subscription details for the connected account. Use to inspect account information before generation. Read-only; this is not a request-specific cost quote or model-eligibility check.
无需输入参数。
List saved items
Lists the account's active saved characters, references, voice recordings, moodboards and brand kits, newest first. Reusable paths are in each item's assets[].file_path; temporary signed URLs support preview/download. Read-only; pass next_cursor as cursor for the next page.
typelimitcursorGet upload URLs
Creates presigned upload URL and file-path pairs for local media. Use when a generation needs a file the user has locally: upload raw bytes to the returned upload_url, then pass its file_path to the create tool. Does not upload file bytes or start a generation.
items必填Get face detection results
Returns a face-detection job's status and detected faces. Use with the id from detect_faces to inspect progress and choose face mappings before a selected-face swap. Read-only; faces may populate while processing.
id必填Detect faces
Starts an asynchronous face-detection task for a supplied image or video and returns its id and charge information. Use before a selected-face swap, then retrieve its status and detected faces with get_face_detection_results. Current API documentation describes detection as free; pricing may change.
assets必填confidence_scoreGet video project
Returns a video project's status and, once complete, its download URLs. Use to check progress with the id from a video create tool. Read-only.
id必填Delete video project
Deletes the video project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
id必填Create talking photo
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Animates a still portrait so it speaks an existing audio recording. Use with a portrait photo and an audio file; text alone is not accepted and this tool does not synthesize speech. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyleassets必填resolutionend_seconds必填start_seconds必填Create spoken ad video
Creates a creator-style spoken ad video from a prepared image and a text script. Use when the image is ready and the dialogue should be generated from text. Starts a background job that costs credits; returns a project id for wait_for_video_project.
modelassets必填script必填resolutionend_seconds必填Edit video
Edits the appearance or content of a supplied video segment using a text prompt. Use with a source video, the requested changes and the clip end time. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namemodelstyle必填assets必填resolutionend_seconds必填start_secondsTranslate video
Translates speech in a supplied video segment into a supported target language. Starts a background job that costs credits; returns a project id for wait_for_video_project.
nameassets必填resolutionend_seconds必填start_secondstarget_language必填Upscale video
Upscales a supplied video segment to a selected output resolution while preserving its aspect ratio. Starts a background job that costs credits; returns a project id for wait_for_video_project.
nameassets必填resolution必填end_seconds必填start_secondsCreate animation
Creates a stylized animated video with art and camera settings, using a custom prompt or an audio-derived prompt mode. Can use an initial image and audio. Credits depend on frame rate and duration; returns a project id for wait_for_video_project.
fps必填namestyle必填width必填assets必填height必填end_seconds必填Create video from audio
Generates an audio-guided video from a supplied audio track, with an optional starting image and visual prompt. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyleassets必填resolutionend_seconds必填start_secondsAdd subtitles to video
Adds automatically generated subtitles to a supplied video segment using a subtitle preset or custom text styling. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyle必填assets必填end_seconds必填start_seconds必填Replace character in video
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Replaces a subject in a video with a character from a reference image, or transfers the video's motion onto that character. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namemodelstyleassets必填resolutionend_seconds必填start_secondsSwap face in video
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps faces in an existing video: all faces with a reference image, or selected faces using detect_faces results. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyleassets必填end_seconds必填start_seconds必填Create video from image
Animates a supplied image into a video using motion instructions and available model options. Starts a background job that costs credits; returns a project id for wait_for_video_project.
nameaudiomodelstyleassets必填resolutionend_seconds必填Create lip sync video
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Adjusts an existing video's lip movements to match supplied replacement audio. For a still portrait plus audio, use create_talking_photo. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyleassets必填end_seconds必填max_fps_limitstart_seconds必填Create video from text
Generates a video from a text prompt, with optional supported reference inputs and model settings. To animate an existing starting image, use create_video_from_image. Starts a background job that costs credits; returns a project id for wait_for_video_project.
nameaudiomodelstyle必填referencesresolutionend_seconds必填aspect_ratioRestyle video
Restyles an existing video clip with an art-style preset or a custom prompt. Supports v1/v2 presets, not v3. Starts a background job that costs credits; returns a project id for wait_for_video_project.
namestyle必填assets必填end_seconds必填start_seconds必填fps_resolutionGet image project
Returns an image project's status and, once complete, its download URLs. Use to check progress with the id from an image create tool. Read-only.
id必填Delete image project
Deletes the image project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
id必填Change clothes in photo
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Changes clothing in a person photo using a supplied garment reference image. Costs 25 credits. Starts a background job; returns a project id for wait_for_image_project.
nameassets必填Edit face in photo
Adjusts facial expression, pose and gaze in a supplied photo using numeric controls. Costs 1 credit per edit; output size depends on the subscription tier. Starts a background job; returns a project id for wait_for_image_project.
namestyle必填assets必填Create GIF or short video
Generates a short animation from a text prompt, with GIF, MP4 or WebM output. Costs 50 credits. Starts a background job; returns a project id for wait_for_image_project.
namestyle必填output_formatEdit image
Edits one or more supplied images using a text prompt. For prompt-only creation use generate_image. Costs credits; returns a project id for wait_for_image_project. Model eligibility depends on the account plan; the default model is not available on every plan.
namemodelstyle必填assets必填resolutionimage_countaspect_ratioGenerate headshot
Creates a headshot from a supplied photo containing one detectable face, with optional appearance instructions. Costs 50 credits. Starts a background job; returns a project id for wait_for_image_project.
namestyleassets必填Generate image
Generates one or more images from a text prompt, with model, output size and image count options. Costs credits; returns a project id for wait_for_image_project.
namemodelstyle必填resolutionimage_count必填aspect_ratioUpscale image
Upscales a supplied image 2x or 4x. Cost depends on scale and mode (25-200 credits); returns a project id for wait_for_image_project.
namestyleassets必填scale_factor必填Create meme
Creates a meme from a topic and template selection. Costs 10 credits. Starts a background job; returns a project id for wait_for_image_project.
namestyle必填Create QR code
Creates a stylized QR code from supplied text or a URL and an art-style description. Currently costs 0 credits. Starts a background job; returns a project id for wait_for_image_project.
namestyle必填content必填Place person in scene
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Places a person from one supplied photo into a supplied scene image. Cost depends on resolution (from 50 credits at 640px); returns a project id for wait_for_image_project.
nameassets必填resolution必填Swap face in photo
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps faces in a supplied photo using a source face image or selected face mappings. Costs 10 credits; output size depends on subscription. Returns a project id for wait_for_image_project.
nameassets必填Swap head in photo
Use only with the user's own likeness or content they are authorized to use. Do not use for impersonation, deception, sexual content, or content involving minors. Swaps a head from a supplied image onto a supplied body image. Costs 10 credits; returns a project id for wait_for_image_project.
nameassets必填max_resolutionRemove image background
Removes an image's background, optionally replacing it with another supplied image. Costs 5 credits. Starts a background job; returns a project id for wait_for_image_project.
nameassets必填Colorize photo
Colorizes a black-and-white or faded photo. Costs 10 credits; returns a project id for wait_for_image_project.
nameassets必填Get audio project
Returns an audio project's status and, once complete, its download URLs. Use to check progress with the id from an audio create tool. Read-only.
id必填Delete audio project
Deletes the audio project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
id必填Generate music
Generates music from a description, with optional custom lyrics or instrumental-only output. Costs 1 credit per requested second; returns a project id for wait_for_audio_project.
namestyle必填duration必填已满足适用检查项的 100%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
pip install -e .python main.pyhttp://127.0.0.1:8000/https://api.magichour.aiAuthorization: Bearer <magic_hour_api_key>https://mcp.magichour.ai/.well-known/mcp/server-card.jsonMAGIC_HOUR_API_BASE_URL=https://api.magichour.aiMAGIC_HOUR_OPENAPI_PATH=docs/openapi.jsonMCP_OAUTH_ISSUER_URL=https://mcp.magichour.aiMCP_OAUTH_RESOURCE_URL=https://mcp.magichour.aiMAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.pynpx @modelcontextprotocol/inspector