Deepy MCP Server
OfficialDeepy MCP Server allows an AI assistant to generate videos, images, and audio via Deepy's API, managing the full lifecycle from model selection and prompt improvement to cost estimation, user-confirmed creation, status polling, and local result retrieval.
List available models: Browse all accessible AI models, optionally filtered by type, group, or family.
Get model details: Fetch parameters, limits, and max prompt length for a specific model.
Improve a prompt: Rewrite a draft prompt for better generation results (image/video/audio).
Upload reference files: Send images, videos, or audio (up to 50 MiB) to use as inputs for generation.
Estimate generation cost: Obtain token cost and resulting balance without any charge.
Create a generation (paid): Start a generation after explicit user confirmation; uses idempotency to avoid double charges.
Check generation status: Poll for completion or failure using the returned public ID.
Retrieve result media: Download generated files locally; small images/audio are inlined in chat, large media saved to disk, videos stream with no size limit.
Open top-up page: Open the Deepy credits page in the browser when balance is insufficient.
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., "@Deepy MCP Server generate a 10-second video of a sunset over the ocean"
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.
Deepy MCP server
Let your AI assistant make videos, images and audio on Deepy for you. You describe what you want in a normal chat message, the assistant handles the model choice, the parameters and the download.
Works with Cursor, Claude Desktop, Claude Code, VS Code, Windsurf, Zed and anything else that speaks MCP.
You: make me a 5-second clip of a cat knocking a glass off a table
Agent: That's bytedance/seedance-2.0, 133 credits. Go ahead?
You: yes
Agent: Done — saved to ~/Downloads/deepy-8f3a…-0.mp4Everything is billed to your normal Deepy balance. No separate card, no separate invoice.
Before you start
You need two things:
Node.js 22 or newer. Free, from nodejs.org. This is what runs the connector.
A Deepy API key. Create one in the Deepy web app under API access. It looks like
sk_live_…and is shown only once, so copy it right away.
Related MCP server: multimodal-mcp
Setup
Add this to your MCP client's config, replacing the key with your own.
Cursor — ~/.cursor/mcp.json for every project, or .cursor/mcp.json for
just one:
{
"mcpServers": {
"deepy": {
"command": "npx",
"args": ["-y", "github:deepy-to/deepy-mcp-server"],
"env": {
"DEEPY_API_BASE_URL": "https://deepy.to",
"DEEPY_API_KEY": "sk_live_your_key_here"
}
}
}
}Claude Desktop — the same block in claude_desktop_config.json, then restart
the app. Copy-paste versions of both live in mcp-configs/.
Other clients take the same three fields but not always under mcpServers: VS
Code and Windsurf use servers, Zed uses context_servers. Check your client's
own MCP docs for the wrapper key.
Then restart your client and ask it to list Deepy models. If it answers, you're connected.
The first start is slow. npx downloads the connector before the client gets
a reply, which can take half a minute or so. If your client gives up early, raise
its MCP startup timeout to 60 seconds. Later starts are fast.
Running from a local clone instead
Useful if you're working on the connector itself, or you want a pinned version:
git clone https://github.com/deepy-to/deepy-mcp-server
cd deepy-mcp-server
npm installThen point the config at the built file — "command": "node",
"args": ["/absolute/path/to/deepy-mcp-server/dist/index.js"], same env block.
Not on npm yet
npx -y @deepy/mcp-server gives you a 404 — the package hasn't been published.
Install from GitHub as shown above.
What the assistant can do
Tool | What it's for |
| the whole job: price it, then create, wait and download |
| see which models are available |
| read one model's parameters and limits (or several at once) |
| turn a rough idea into a stronger prompt |
| send a reference image, video or audio (up to 50 MiB) |
| open the top-up page when your balance runs out |
generate is the one the assistant normally uses. Called without confirmation
it just quotes the price; called again with the same arguments and your approval
it creates the generation, waits for it and hands back the finished file. That's
two steps instead of the eight the granular tools need.
Those granular tools — estimate_generation, create_generation,
get_generation, get_result — are still there for step-by-step control, and
for the case where a long video outlives generate's wait window.
The connector also ships prompt templates and short guides that teach the agent the flow below, so you don't have to explain it every time.
How spending works
This is the part worth reading.
Nothing is charged without your explicit yes. The agent has to price the
generation first (free), show you the number, and get an answer. Both paths
enforce this: generate stops after pricing and returns the cost, and
create_generation refuses to run unless it's told the user confirmed. When
either refuses, no paid request reaches the Deepy backend at all.
The quoted price is the price. The estimate and the create send byte-identical requests, so the number you approved is the number you pay.
You are never charged twice for one generation. Each create derives its
idempotency key from the request itself, so a retry of identical arguments
replays the existing generation instead of buying a second one. If the agent
ever reports IDEMPOTENCY_CONFLICT, the generation already exists — it should
check its status, not start over.
If you deliberately want another copy of the same request (for a model that
varies by seed), the tools support a copy argument: set it to 2 for a second
copy, 3 for a third, and so on. Asking for copy 2 twice (a timeout-retry, an
agent loop) still replays — it's an ordinal, not a nonce.
Out of credits isn't a dead end. When your balance can't cover a generation, the agent can open the Deepy top-up page in your browser. Add credits, tell it you're done, and it picks up where it left off.
The Deepy backend, not this connector, decides prices, moderation and limits.
Where your files land
Finished results are saved to ~/Downloads (or your temp folder if that isn't
writable), and the agent tells you the path. Small images and audio also render
right in the chat.
Videos and large files stream straight to disk, so a long clip is limited only by your free space — nothing is held in memory. If a download fails halfway, the partial file is deleted rather than left looking complete.
When something goes wrong
No Deepy tools show up. Check Node.js is installed (node --version), that
the config is in the right file, and that you fully restarted the client — not
just reopened the window.
"Unauthorized". The key is wrong, expired or disabled. Issue a new one under API access and update the config.
"Insufficient balance". Top up and ask the agent to try again. It can open the page for you.
"Model not found". The catalog changed. Ask the agent to list models and pick from what's there.
Your API key
The key is read only from the config's env block. The connector never accepts
it from chat text, never prints it in a log line, and never passes it back to the
agent — when the agent fetches your finished video, the connector does the
authenticated request itself.
It also never hands out raw storage URLs, never talks to the generation providers directly, and refuses to follow HTTP redirects, so your key can't be replayed to another host.
Configuration reference
Variable | Required | What it does |
| yes | Deepy API origin, no trailing slash |
| yes | your personal key ( |
| no |
|
| no | request deadline in ms, default 30000 |
| no | runaway-download guard in MiB, default 2048 |
Downloads get a longer deadline than DEEPY_HTTP_TIMEOUT_MS — at least two
minutes, and it resets on every chunk received, so a slow but healthy transfer
isn't cut off mid-file.
Working on the connector
npm install
npm run build # compile src/ to dist/
npm test # vitest
npm run dev # run from source
npm run lintdist/ is committed on purpose: that's what makes installing straight from
GitHub work without a build step on the user's machine. Rebuild before you commit
a source change.
License
MIT.
Available Tools
9 toolsdeepy_create_generationCreate a generation (paid)ADestructive
Start a PAID generation. Requires confirmed=true — the tool refuses otherwise and contacts no backend. Params must be byte-identical to the estimate (quote == charge). An X-Idempotency-Key is auto-generated to prevent double-charging.
Inputs: prompt (required), confirmed (required), modelName (required), parameters, +2 more.
deepy_estimate_generationEstimate generation costA
Get the integer token cost and resulting balance for a generation, without charging anything. Always estimate and confirm with the user before creating. The exact same params must be passed to deepy_create_generation (quote == charge).
Inputs: prompt (required), modelName (required), parameters, referenceFiles.
deepy_get_generationGet generation statusA
Fetch a generation's current status, error info, and result indexes by publicId. Poll this after create until status is COMPLETED or FAILED.
Inputs: publicId (required).
deepy_get_modelGet Deepy model detailsA
Fetch the full schema for one model: its parameters, reference-file limits, generation type, and max prompt length. A closed or unknown model returns MODEL_NOT_FOUND (closed models are never revealed).
Inputs: modelName (required).
deepy_get_resultGet a generation resultA
Fetch a COMPLETED generation's result media. The server fetches the bytes with its own API key, saves the full-resolution file locally on the user's device and returns its path, and inlines small images/audio (base64) so they render in-chat. Videos and large media are streamed straight to the saved local file (never inlined as base64), so there is no practical size limit. Never exposes the API key or a raw URL.
Inputs: publicId (required), index.
deepy_improve_promptImprove a generation promptA
Rewrite a draft prompt into a stronger one for the given modality (image/video/audio). Returns the improved prompt text to use as the base in estimate/create — review it first, the rewriter can invent style references that do not exist.
Inputs: prompt (required), modality (required), style.
deepy_list_modelsList Deepy modelsA
List the AI models available to your Deepy API key (only opened/available models are returned). Returns every matching model grouped by generation type; [refs] marks models that accept reference files. One call is enough — pass type/family/group only to narrow the catalogue, never to work around a truncated result. Use this before estimating or creating a generation.
Inputs: type, group, family.
deepy_open_topup_pageOpen the Deepy top-up pageARead-onlyIdempotent
Open the Deepy credits top-up page in the user's default browser and return its URL. Call this when a balance is too low to cover a generation (deepy_estimate_generation returned canAfford=false, or a create failed with INSUFFICIENT_CREDITS) and the user wants to add credits. Opens a page only — it never moves money or charges anything.
Inputs: no named parameters.
deepy_upload_fileUpload a generation referenceA
Upload an image, video, or audio attachment (up to 50 MiB) to Deepy and return its fileId. For files attached directly to the agent window, pass their absolute local path as filePath. Call this before estimate/create and pass the returned id in referenceFiles.
Inputs: base64, filePath, filename, mimeType.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct step in the AI generation workflow: model discovery, schema lookup, prompt refinement, file upload, cost estimation, paid creation, status polling, result retrieval, and top-up navigation. There is no overlap or ambiguity between them.
All tool names share the 'deepy_' prefix and follow a consistent verb_noun pattern (list_models, get_model, improve_prompt, upload_file, estimate_generation, create_generation, get_generation, get_result, open_topup_page). The naming is uniform and predictable.
With 9 tools, the server is well-scoped for the domain of AI media generation. Each tool covers a necessary step in the process, and the count feels neither excessive nor sparse.
The toolset covers the full generation lifecycle: model exploration, prompt enhancement, file upload, cost estimation, creation, status tracking, result retrieval, and credit top-up. No critical operations are missing for the stated purpose.
Maintenance
Related MCP Connectors
AI video, image and audio generation with 140+ AI models from any MCP agent
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Stivio MCP server - AI image-to-video generator via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceMCP server for programmatic video generation. Send a prompt, get an MP4.-
- AlicenseAqualityDmaintenanceMulti-provider media generation MCP server that generates images, videos, audio, and transcriptions from text prompts using OpenAI, xAI, Gemini, ElevenLabs, and BFL through a single unified interface.6169 npm2MIT
- AlicenseAqualityAmaintenanceStateless MCP server that wraps OpenAI's Sora, Whisper, GPT-4o Audio, and TTS APIs for generating videos, images, and processing audio.962 PyPI6MIT
- AlicenseAqualityBmaintenanceLocal MCP server that plans, generates, and assembles production assets (images, audio, video) through multi-agent personas and official APIs, with free-tier budget guard.15MIT