io.github.magichourhqPublished by GitHub account magichourhqv0.1.1Updated Nov 4, 2026
Create and edit images and video, generate music, and retrieve existing audio projects.
Hosted Magic Hour server that lets an assistant generate and edit images and video, create music, and fetch finished media using Magic Hour credits.
Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.
Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.
Read https://sourceweft.com/mcp/io.github.magichourhq%2Fmagic-hour/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.Add this to your client's mcpServers config.
{
"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.
Source: README.md at commit 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.
workflowrequiredUpload 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.
imagerequiredPing
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.
Takes no parameters.
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.
idrequiredtimeout_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.
idrequiredtimeout_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.
idrequiredtimeout_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_urlrequiredFetch 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_urlrequiredFetch 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_urlrequiredGet 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.
Takes no parameters.
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.
itemsrequiredGet 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.
idrequiredDetect 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.
assetsrequiredconfidence_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.
idrequiredDelete video project
Deletes the video project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
idrequiredCreate 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.
namestyleassetsrequiredresolutionend_secondsrequiredstart_secondsrequiredCreate 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.
modelassetsrequiredscriptrequiredresolutionend_secondsrequiredEdit 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.
namemodelstylerequiredassetsrequiredresolutionend_secondsrequiredstart_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.
nameassetsrequiredresolutionend_secondsrequiredstart_secondstarget_languagerequiredUpscale 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.
nameassetsrequiredresolutionrequiredend_secondsrequiredstart_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.
fpsrequirednamestylerequiredwidthrequiredassetsrequiredheightrequiredend_secondsrequiredCreate 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.
namestyleassetsrequiredresolutionend_secondsrequiredstart_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.
namestylerequiredassetsrequiredend_secondsrequiredstart_secondsrequiredReplace 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.
namemodelstyleassetsrequiredresolutionend_secondsrequiredstart_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.
namestyleassetsrequiredend_secondsrequiredstart_secondsrequiredCreate 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.
nameaudiomodelstyleassetsrequiredresolutionend_secondsrequiredCreate 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.
namestyleassetsrequiredend_secondsrequiredmax_fps_limitstart_secondsrequiredCreate 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.
nameaudiomodelstylerequiredreferencesresolutionend_secondsrequiredaspect_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.
namestylerequiredassetsrequiredend_secondsrequiredstart_secondsrequiredfps_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.
idrequiredDelete image project
Deletes the image project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
idrequiredChange 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.
nameassetsrequiredEdit 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.
namestylerequiredassetsrequiredCreate 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.
namestylerequiredoutput_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.
namemodelstylerequiredassetsrequiredresolutionimage_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.
namestyleassetsrequiredGenerate 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.
namemodelstylerequiredresolutionimage_countrequiredaspect_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.
namestyleassetsrequiredscale_factorrequiredCreate 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.
namestylerequiredCreate 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.
namestylerequiredcontentrequiredPlace 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.
nameassetsrequiredresolutionrequiredSwap 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.
nameassetsrequiredSwap 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.
nameassetsrequiredmax_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.
nameassetsrequiredColorize photo
Colorizes a black-and-white or faded photo. Costs 10 credits; returns a project id for wait_for_image_project.
nameassetsrequiredGet 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.
idrequiredDelete audio project
Deletes the audio project and attempts to delete its completed output. Cannot be undone; confirm with the user first.
idrequiredGenerate 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.
namestylerequireddurationrequired100% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
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