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.mp4

Everything is billed to your normal Deepy balance. No separate card, no separate invoice.

Before you start

You need two things:

1. Node.js 22 or newer. Free, from nodejs.org. This is what runs the connector.

2. 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 install

Then 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

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

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 lint

dist/ 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.