WaveSpeed MCP Server
An MCP server for the WaveSpeed platform: run any model on the live catalog — image, video, audio, 3D — from Claude Code, Claude Desktop, Cursor, Cline, or any MCP client.
Built on the same design as the open-source @wavespeed/cli:
- No hardcoded models for
run_model. The catalog comes from the live API (1h cache); new platform models work the day they ship. - One general verb, five shortcuts.
run_modelexecutes anything;get_model_schematells the agent what inputs a model actually accepts, so it reads before it writes.generate_image,edit_image,generate_video,edit_videoandextend_videoskip that: they use the same models as the WaveSpeed /chat page, pick the endpoint for what you give them and fit the request to its live schema. - Inputs are never mutated. The one explicit transform is the
@pathmarker — a"@./photo.jpg"value insideinputuploads the file and substitutes its hosted URL. Bare paths are passed through untouched. The shortcut tools (generate_imageetc.) are the exception: they pick the endpoint and fit the request to the model, and report what they changed innotes. - Quote before you spend.
get_pricetakes the same input asrun_modeland returns an estimate; the amount actually charged for a run is authoritative.
Tools
The five shortcut tools take wait_seconds like run_model, and estimate_only: true returns the price and the exact request that would run without submitting or charging anything. In their prompts, media is named @image 1, @video 1, @audio 1 (in the order given); it is renamed to what each model expects. Models and defaults follow /chat: an unknown model is rejected, and a named model is never switched.
Some generations take minutes to hours. run_model submits the run and returns the prediction id right away (done: false); the assistant then calls get_prediction with that id and wait_seconds (max 1800) until done is true. The task keeps running server-side, so a dropped connection loses nothing. Pass wait_seconds to run_model to wait for a quick model in the same call. While waiting, both tools send MCP progress notifications that carry the prediction id.
Setup
Remote (nothing to install)
The same server is hosted at:
https://api.wavespeed.ai/mcp
- Claude on the web / ChatGPT: add a custom connector with that address and approve the connection on the WaveSpeed page that opens. Approving creates a dedicated API key (named
MCP · <app>) that you can delete on the API Keys page to disconnect. - Claude Code:
claude mcp add --transport http wavespeed https://api.wavespeed.ai/mcp - Cursor:
- VS Code:
code --add-mcp '{"name":"wavespeed","type":"http","url":"https://api.wavespeed.ai/mcp"}' - Any other client that sends request headers: point it at the URL with
Authorization: Bearer <your API key>.
The hosted server has the same tools, with one difference for files: it cannot read files on your computer, so pass public URLs, use create_upload from a tool that can send HTTP requests (it returns a temporary upload address and the download_url to use as an input), or, in ChatGPT, attach the file to the chat (the upload_attachment tool, which only ChatGPT can fill, imports it and returns a download_url). Full guide: wavespeed.ai/docs/mcp.
Local (npx)
@latest makes npx fetch the newest release on each start; without it, npx runs a globally installed @wavespeed/mcp if one exists, however old.
Auth resolves from WAVESPEED_API_KEY, or from the CLI's stored login (wavespeed login) — one login covers both tools. Keys: wavespeed.ai/accesskey.
Claude Code
claude mcp add wavespeed -- npx -y @wavespeed/mcp@latest
Claude Desktop / other clients (mcpServers config):
{
"mcpServers": {
"wavespeed": {
"command": "npx",
"args": ["-y", "@wavespeed/mcp@latest"],
"env": { "WAVESPEED_API_KEY": "wsk_..." }
}
}
}
Example prompts
- "Generate a 16:9 hero image of a cyberpunk skyline at golden hour."
- "Take ./photo.jpg and replace the background with a sunlit kitchen." (the agent passes
"@./photo.jpg") - "Animate ./hero.png with subtle parallax — check the price first."
Development
npm install
npm run dev # run from source (stdio)
npm run lint # typecheck
npm run build # tsc → dist/
License
WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator
