Mirelo MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mirelo MCP Server generate a sound effect of a thunderstorm"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mirelo MCP Server
A Model Context Protocol (MCP) server that wraps the Mirelo v2 HTTP API, exposing Mirelo's sound-effects generation, audio extension, inpainting, and account tooling to any MCP-compatible client (Claude Desktop, Kiro, and others).
The server speaks MCP over stdio and advertises 21 tools covering six generation families plus job polling, asset uploads, and account lookup.
Features
Six generation families, each available as a sync generate, async submit, and preflight tool:
Text → SFX
Video → SFX
Extend audio (audio-only)
Extend audio (with video)
Inpaint audio (audio-only)
Inpaint audio (with video)
Async job polling (
mirelo_job_status) for long-running submissions.Asset upload slots with optional direct upload of a local file to the presigned S3 URL.
Account/quota lookup (
mirelo_get_account).Eager config validation at startup, with a clear error and non-zero exit on invalid configuration.
Starts and advertises every tool even without an API key — credential-requiring calls return a structured missing-credential error instead of failing at startup.
Related MCP server: higgsfield-mcp
Requirements
Node.js
>=20
Installation
npm install
npm run buildnpm run build compiles TypeScript to dist/ and produces the executable entrypoint dist/index.js (with a #!/usr/bin/env node shebang, exposed as the mirelo-mcp-server bin).
Configuration
The server reads three environment variables at startup:
Variable | Required | Default | Notes |
| No | — | Mirelo API key (bearer token). If absent, the server still starts and advertises all tools; calls that need credentials return a missing-credential error. |
| No |
| Must be an absolute |
| No |
| Request timeout in ms. Must be an integer in |
Invalid MIRELO_BASE_URL or MIRELO_TIMEOUT_MS values cause a ConfigError, printed to stderr with a non-zero exit code.
MCP client configuration
Add the server to your MCP client's config (e.g. mcp.json).
Recommended — run via npx (no clone or build; npx fetches the published package on demand):
{
"mcpServers": {
"mirelo": {
"command": "npx",
"args": ["-y", "mirelo-mcp-server"],
"env": {
"MIRELO_API_KEY": "your-mirelo-api-key",
"MIRELO_BASE_URL": "https://api.mirelo.ai",
"MIRELO_TIMEOUT_MS": "60000"
}
}
}
}Global install (installs the mirelo-mcp-server bin on PATH):
npm install -g mirelo-mcp-server{
"mcpServers": {
"mirelo": {
"command": "mirelo-mcp-server",
"env": {
"MIRELO_API_KEY": "your-mirelo-api-key"
}
}
}
}From source (clone + build, then point at the built entrypoint):
{
"mcpServers": {
"mirelo": {
"command": "node",
"args": ["/absolute/path/to/mirelo-mcp/dist/index.js"],
"env": {
"MIRELO_API_KEY": "your-mirelo-api-key"
}
}
}
}Tools
The server advertises 21 tools.
Generation families
Each family provides three tools:
_generate— synchronous generation; returnsresult_urlswhen the job completes inline._submit— asynchronous submission; returns ajob_id/job_urlto poll._preflight— validates inputs and reports what would be sent without calling the generation endpoint.
Family | Tools | Notes |
Text → SFX |
| Model versions v1.5 / v1.6. |
Video → SFX |
| Requires a |
Extend audio (audio-only) |
| v1.6. |
Extend audio (with video) |
| v1.6. |
Inpaint audio (audio-only) |
| v1.6. |
Inpaint audio (with video) |
| v1.6. |
Management tools
Tool | Purpose |
| Poll an async job by |
| Create an asset upload slot ( |
| Fetch account details ( |
Input sources
Tools that take audio or video accept an Input_Source in one of two shapes:
{ "type": "url", "audio_url": "https://..." }{ "type": "asset", "asset_id": "asset_..." }(Use video_url for video sources.) To reference an uploaded file, create an asset with mirelo_create_asset_upload_slot, then pass { "type": "asset", "asset_id": "..." }.
Example prompts to test
These are natural-language prompts you can give an MCP client (Claude Desktop, Kiro, etc.) once the server is connected and MIRELO_API_KEY is set. Each is phrased so the client maps it to the right tool and parameters. Durations are in milliseconds and stay within each tool's valid range.
Account and connectivity
"Check my Mirelo account — what's my email and how many credits do I have left?"
"Is overage enabled on my Mirelo account?"
Text → SFX
"Generate a 5-second sound effect of heavy rain on a tin roof." (sync generate,
duration_ms: 5000)"Create the sound of a sword being drawn from a metal scabbard, about 2 seconds long, and give me 3 variations." (
duration_ms: 2000,num_samples: 3)"Make a seamless 10-second looping campfire crackle." (sets
loop: true,duration_ms: 10000)"Generate a distant thunder rumble using model v1.5." (
model_version: "v1.5")"Estimate the cost and time to generate a 30-second forest ambience before actually making it." (preflight)
"Submit a long 45-second cinematic whoosh as a background job and give me the job id." (async submit)
Video → SFX
"Generate sound effects for this video and match them to its first 8 seconds: https://example.com/clip.mp4." (
videourl source,duration_ms: 8000)"Add foley to my video asset asset_123 starting at the 2-second mark, and return the result as a muxed video." (
start_offset_ms: 2000,output: "video")"Preflight the cost of scoring a 12-second video clip." (preflight,
duration_ms: 12000)"Submit a video-to-SFX job for https://example.com/scene.mp4 covering 20 seconds and give me the job id to poll." (async submit)
Extend audio (audio-only)
"Take this audio https://example.com/loop.wav and extend it by 8 more seconds." (
append_duration_ms: 8000)"Extend my audio asset asset_456 by 15 seconds and guide the new part with the prompt 'building to a crescendo'." (
append_duration_ms: 15000,prompt)"Loop-extend this 3-second clip so it plays seamlessly, adding 5 seconds." (
loop: true,append_duration_ms: 5000)
Extend audio (with video)
"I have a video at https://example.com/ad.mp4 and its audio at https://example.com/ad.wav — extend the audio by 6 seconds to match the video tail." (
append_duration_ms: 6000)"Extend the soundtrack of my video asset by 30 seconds starting 4 seconds in." (
append_duration_ms: 30000,start_offset_ms: 4000)
Inpaint audio (audio-only)
"In this audio https://example.com/take.wav, replace the section from 2s to 5s with a clean guitar strum." (
segment: { start_ms: 2000, end_ms: 5000 },prompt)"Fix my audio asset asset_789 by regenerating the 10000-14000ms region." (
segment: { start_ms: 10000, end_ms: 14000 })"Preflight replacing a 3-second segment (from 6s to 9s) of a clip." (preflight)
Inpaint audio (with video)
"For my video asset (video asset_v1, audio asset_a1), replace the audio between 3s and 7s to fix a glitch." (
segment: { start_ms: 3000, end_ms: 7000 })
Assets
"Create an upload slot for a WAV file and upload /Users/me/sfx/input.wav to it." (
content_type: "audio/wav",file_path)"Create an asset upload slot for content type video/mp4 and give me the presigned URL." (slot only, no local upload)
Async job polling
"Check the status of Mirelo job job_abc123." (
mirelo_job_status)"Poll job job_abc123 and, once it's succeeded, give me the result URLs."
Tip: the
_preflighttools never generate audio or spend credits, so they're the safest way to smoke-test connectivity and your API key.
Async job flow
Call a family's
_submittool to get ajob_id.Poll
mirelo_job_statuswith thatjob_id.When the status is
succeeded, read theresult_urlsfrom the response.
Synchronous _generate tools skip this loop and return result_urls directly when the job finishes inline.
Architecture
Transport: stdio via the
@modelcontextprotocol/sdkserver. The SDK owns the handshake, version negotiation, and request dispatch.Startup sequence: load and validate config → read the API key once → build a single configured HTTP client → bind each registry tool's handler → register
ListTools+CallTooland connect the stdio transport.The entrypoint (
src/index.ts) exportscreateServer,connectStdio, andmain, and is import-safe (importing it has no side effects) so it can be exercised by tests without spawning stdio.Tool definitions live in
src/tools/*and are aggregated bysrc/registry.ts, which enforces the 21-tool invariant at load time.
Development
npm test # run the test suite once (vitest)
npm run test:watch # watch mode
npm run build # type-check and emit dist/The suite includes property-based tests using fast-check alongside unit and integration tests.
License
MIT
Available Tools
21 toolsmirelo_create_asset_upload_slotA
Create an asset upload slot (POST /v2/assets) for a given content_type, returning an asset_id and a presigned upload_url. When an optional local file_path is provided, the file's bytes are uploaded to that URL so the asset_id is immediately usable in generation and editing operations.
Inputs: content_type (required), file_path.
mirelo_extend_audio_generateA
Extend Audio (audio-only), synchronous: append newly generated audio to an existing audio input and return the result URL(s).
Inputs: audio (required), append_duration_ms (required), loop, prompt, +2 more.
mirelo_extend_audio_preflightA
Extend Audio (audio-only) preflight: estimate the credit cost and processing time for an extend-audio request.
Inputs: duration_ms, num_samples, model_version.
mirelo_extend_audio_submitA
Extend Audio (audio-only), asynchronous submission: submit an extend-audio job and return its job_id and job_url for later polling.
Inputs: audio (required), append_duration_ms (required), loop, prompt, +2 more.
mirelo_extend_audio_with_video_generateA
Extend an existing audio input with newly generated audio conditioned by a video (synchronous). Returns result URLs. Requires audio and video Input_Sources and append_duration_ms (1000-57000 ms). Model v1.6 only.
Inputs: audio (required), video (required), append_duration_ms (required), prompt, +3 more.
mirelo_extend_audio_with_video_preflightA
Estimate the credit cost and processing time for an Extend_Audio with-video generation before committing. Requires append_duration_ms (1000-57000 ms); num_samples defaults to 1. Model v1.6 only.
Inputs: append_duration_ms (required), num_samples, model_version.
mirelo_extend_audio_with_video_submitA
Submit an asynchronous Extend_Audio with-video job (append audio conditioned by a video). Returns a job_id and job_url to poll with mirelo_job_status. Requires audio and video Input_Sources and append_duration_ms (1000-57000 ms). Model v1.6 only.
Inputs: audio (required), video (required), append_duration_ms (required), prompt, +3 more.
mirelo_get_accountA
Retrieve the authenticated Mirelo account identity and available credit balance: id, email, credits_available, and overage_enabled.
Inputs: no named parameters.
mirelo_inpaint_audio_generateB
Synchronously replace a bounded segment of an audio clip with newly generated audio (Inpaint_Audio, audio-only). Returns the resulting audio URL(s).
Inputs: audio (required), segment (required), prompt, num_samples, +1 more.
mirelo_inpaint_audio_preflightA
Estimate the credit cost and processing time of an Inpaint_Audio (audio-only) request before generating.
Inputs: segment (required), num_samples, model_version.
mirelo_inpaint_audio_submitA
Submit an asynchronous Inpaint_Audio (audio-only) job that replaces a bounded audio segment, returning a job identifier to poll with mirelo_job_status.
Inputs: audio (required), segment (required), prompt, num_samples, +1 more.
mirelo_inpaint_audio_with_video_generateA
Synchronously replace a bounded segment of an audio clip with newly generated audio conditioned by a video (Inpaint_Audio, with-video). Requires audio and video Input_Sources and a segment. Returns the resulting audio URL(s). Model v1.6 only.
Inputs: audio (required), video (required), segment (required), prompt, +2 more.
mirelo_inpaint_audio_with_video_preflightA
Estimate the credit cost and processing time of an Inpaint_Audio (with-video) request before generating. Requires a segment; num_samples defaults to 1. Model v1.6 only.
Inputs: segment (required), num_samples, model_version.
mirelo_inpaint_audio_with_video_submitA
Submit an asynchronous Inpaint_Audio (with-video) job that replaces a bounded audio segment conditioned by a video, returning a job identifier to poll with mirelo_job_status. Requires audio and video Input_Sources and a segment. Model v1.6 only.
Inputs: audio (required), video (required), segment (required), prompt, +2 more.
mirelo_job_statusA
Poll the status of an asynchronous Mirelo generation job by its job_id via the shared GET /v2/jobs/{job_id} endpoint. Surfaces processing progress, succeeded result URLs, or the failure reason.
Inputs: job_id (required).
mirelo_text_to_sfx_generateB
Generate sound effects synchronously from a text prompt and return the result URLs.
Inputs: prompt (required), loop, duration_ms, num_samples, +1 more.
mirelo_text_to_sfx_preflightA
Estimate the credit cost and processing time for a Text-to-SFX generation without generating audio.
Inputs: duration_ms, num_samples, model_version.
mirelo_text_to_sfx_submitA
Submit an asynchronous Text-to-SFX generation job and return the job id and job URL for later polling.
Inputs: prompt (required), loop, duration_ms, num_samples, +1 more.
mirelo_video_to_sfx_generateC
Generate a synced sound track for a supplied video synchronously and return the result URLs. Requires a video Input_Source and duration_ms.
Inputs: video (required), duration_ms (required), output, num_samples, +2 more.
mirelo_video_to_sfx_preflightA
Estimate the credit cost and processing time for a Video_To_SFX generation without generating. Uses duration_ms and num_samples.
Inputs: duration_ms, num_samples, model_version.
mirelo_video_to_sfx_submitA
Submit a Video_To_SFX generation as an asynchronous job and return the job id and job URL for later polling. Requires a video Input_Source and duration_ms.
Inputs: video (required), duration_ms (required), output, num_samples, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct operation: generation, preflight estimation, or asynchronous submission for specific audio tasks (extend, inpaint, text-to-sfx, video-to-sfx), with clear separation between audio-only and with-video variants. Additional tools for account, asset upload, and job polling are unique and non-overlapping.
All tools follow a consistent snake_case pattern with the 'mirelo_' prefix, using verb_noun combinations like 'extend_audio_generate' and 'job_status'. The naming is predictable and uniform across synchronous, preflight, and submit variants.
21 tools is slightly above the typical range, but each tool is justified for a comprehensive audio generation and editing service covering synchronous and asynchronous modes, preflight cost estimation, and support for multiple input types. The count is well-scoped and not excessive.
The tool set covers core generation and editing workflows (extend, inpaint, text-to-sfx, video-to-sfx), including cost estimates and async submission. Missing features include job cancellation, listing assets, and asset deletion, but these are minor gaps for the primary audio generation purpose.
Related MCP Connectors
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
AI voice generation: text-to-speech and voice cloning from any MCP client.
Generate AI video, images and audio, and browse your history, from any MCP client.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI agents the ability to listen to and understand music/audio files, enabling semantic analysis, stem separation, lyrics transcription, and signal processing via tool calls.1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered image and video generation using Higgsfield AI models through MCP-compatible clients like Claude Desktop and Perplexity.MIT
- AlicenseNot gradedqualityDmaintenanceEnables generating AI-powered soundtracks for videos via Muzaic AI from any MCP client.MIT
- AlicenseAqualityDmaintenanceA full-featured MCP server for the ElevenLabs API that brings text-to-speech, speech-to-text, voice cloning, sound effects, music, audio isolation, dubbing, and account tools to any MCP client.28MIT