WaveSpeed

ai.wavespeedPublished by wavespeed.aiOfficial publisherv1.2.10Updated Nov 6, 2026

Run any model on the live WaveSpeed catalog: image, video, audio, 3D.

VerifiedStreamable HTTPWeb executableMedia & DesignAI & ML

Overview

AI-generated overview

WaveSpeed MCP lets an assistant run image, video, audio and 3D generation models from the live WaveSpeed catalog, with price checks and run history.

What you can do
  • Search the live model catalog and read a model's real input schema before running it
  • Run any catalog model, or use shortcut tools to generate and edit images, generate, edit and extend videos
  • Estimate the cost of a run before submitting it, and check account credit balance
  • Upload local files to hosted URLs, or pass local paths that are uploaded automatically
  • Review run history, fetch a prediction's status and outputs, and delete finished runs
  • List itemized charges and usage statistics (spend, request counts, per-model breakdown)
When to use it
Useful when you want an assistant to produce or edit media (images, video, audio, 3D) through WaveSpeed models, or to check pricing and account usage before spending credits. It fits creative and content workflows more than code or data work.
Requirements
Either the hosted remote endpoint with OAuth approval, or the local npm package run through npx (Node.js). Authentication uses the WAVESPEED_API_KEY secret, or a stored CLI login for local use; billing tools need a key with Billing access. Optional WAVESPEED_BASE_URL and WAVESPEED_CLIENT_NAME overrides. The hosted server cannot read local files, so pass public URLs or uploads.
Before you install
Runs consume paid account credits; get_price gives only an estimate and the charged amount is authoritative. The server can upload local files to WaveSpeed hosting, and delete_predictions removes finished runs from history (soft delete, outputs revoked, not undoable from the tool). Billing and usage tools require a key with Billing access, so scope keys accordingly.

Installation

In SourceWeft

  1. Open WaveSpeed in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

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/ai.wavespeed%2Fmcp/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.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "wavespeed": {
      "type": "http",
      "url": "https://api.wavespeed.ai/mcp"
    }
  }
}

README

WaveSpeed MCP Server

[Add the hosted wavespeed MCP server to Cursor]

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_model executes anything; get_model_schema tells the agent what inputs a model actually accepts, so it reads before it writes. generate_image, edit_image, generate_video, edit_video and extend_video skip 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 @path marker — a "@./photo.jpg" value inside input uploads the file and substitutes its hosted URL. Bare paths are passed through untouched. The shortcut tools (generate_image etc.) are the exception: they pick the endpoint and fit the request to the model, and report what they changed in notes.
  • Quote before you spend. get_price takes the same input as run_model and returns an estimate; the amount actually charged for a run is authoritative.

Tools

ToolWhat it does
list_modelsSearch the live catalog by text or modality type
get_model_schemaA model's real input schema (required, properties, defaults), with a link to the model's playground page
run_modelSubmit + wait; rejects input keys the model doesn't accept; @path inputs upload automatically; returns output URLs
generate_imageImage from a prompt with the /chat image models (default Seedream 5 Pro); reference images use the model's edit endpoint
edit_imageEdit, restyle or combine existing images with the same models
generate_videoVideo from a prompt, a first/last frame or reference images/videos/audio, with the /chat video models (default Seedance 2.5); the mode (text, image, reference) is picked from the inputs
edit_videoEdit an existing video, optionally with reference images/audio
extend_videoContinue an existing video with new footage
get_priceCost estimate for the inputs you pass (no charge), with a link to the model's playground page
get_balanceAccount credit balance, with the top-up link
list_predictionsRun history (default last 24h); filter by model, status, time range
list_billingsItemized charges and refunds (needs a Billing-access key)
get_usageSpend, request counts and per-model breakdown (default last 7 days; needs a Billing-access key)
delete_predictionsDelete finished runs from the history (up to 100; needs confirm: true, cannot be undone from here)
upload_fileLocal file → hosted URL (24h content-hash dedupe)
get_predictionStatus/outputs of any run by id; optional wait_seconds to wait for it

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:

text
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: [Add the hosted wavespeed MCP server to Cursor]

  • VS Code: code --add-mcp '{"name":"wavespeed","type":"http","url":"https://api.wavespeed.ai/mcp"}'

  • Clients that only start local commands: connect through mcp-remote, which opens the same browser approval on first start:

    json
    {  "mcpServers": {    "wavespeed": {      "command": "npx",      "args": ["-y", "mcp-remote", "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

bash
claude mcp add wavespeed -- npx -y @wavespeed/mcp@latest

Claude Desktop / other clients (mcpServers config):

json
{  "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

bash
npm installnpm run dev        # run from source (stdio)npm run lint       # typechecknpm run build      # tsc → dist/

License

MIT

WaveSpeed AI — AI image & video generation platform. Try it in the browser: Image generator · Video generator

Source: README.md at commit 2510e29

Tools

16

list_models

Search the live WaveSpeed model catalog (image, video, audio, 3D). Returns model IDs usable with run_model. Do not invent model IDs — always pick one returned by this tool.

Parameterstypelimitqueryrefresh

get_model_schema

Get a model's real input schema (required fields, properties, defaults). Call this before run_model so inputs match what the model actually accepts.

Parametersmodelrequired

run_model

Run any WaveSpeed model. input keys come from get_model_schema; unknown keys are rejected before submission. Local files: pass "@./path" in a media field (image, images, video, audio, mask …) — it is uploaded and replaced with hosted URLs (bare paths are NOT uploaded). Returns the prediction id right away (done=false); call get_prediction with that id and wait_seconds until done=true to get the output URLs. The task keeps running on the server. Pass wait_seconds here to wait for a quick model in the same call.

Parametersinputrequiredmodelrequiredwait_seconds

generate_image

Create an image from a text description with the same models as the WaveSpeed /chat page (seedream-5-pro, nano-banana-2.1, nano-banana-2, nano-banana-pro, gpt-image-2.6, gpt-image-2.5, gpt-image-2; default seedream-5-pro). Give reference_images to use existing images as subject, product, face or style (the model's edit endpoint is used). To change existing images use edit_image. In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.

Parametersmodelpromptrequiredresolutionaspect_ratiowait_secondsestimate_onlyreference_images

edit_image

Change existing images with the same models as the WaveSpeed /chat page: edits, restyles, backgrounds, adding or removing things, combining several images. In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.

Parametersmodelimagesrequiredpromptrequiredresolutionaspect_ratiowait_secondsestimate_only

generate_video

Create a video with the same models as the WaveSpeed /chat page (default seedance-2.5). Give first_frame to animate an image; give reference_images / reference_videos / reference_audios to keep characters, products, motion, voice or music. The right mode (text, image or reference to video) is picked from what you give. Videos can cost dollars: use estimate_only first when unsure. In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.

Parametersmodelpromptrequireddurationlast_frameresolutionfirst_frameaspect_ratiowait_secondsestimate_onlyreference_audiosreference_imagesreference_videos

edit_video

Edit an existing video with the same models as the WaveSpeed /chat page. Name the video and any references in the prompt (e.g. "replace the cat in @video 1 with the lion from @image 1"). In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.

Parametersmodelvideorequiredpromptrequiredresolutionwait_secondsestimate_onlyreference_audiosreference_images

extend_video

Continue an existing video with new footage after its end, with the same models as the WaveSpeed /chat page. Turbo models cannot extend. In the prompt, name input media as @image 1, @image 2, @video 1, @audio 1 (counted in the order the lists are given); they are renamed to what the model expects.

Parametersmodelvideorequiredpromptrequireddurationlast_frameresolutionwait_secondsestimate_only

get_price

Estimate the cost of a run before executing it (no charge). Provide the same input you would pass to run_model — pricing often depends on inputs like duration or resolution, and a quote made without them can be lower than the real charge.

Parametersinputmodelrequired

get_balance

Show the WaveSpeed account credit balance, with the link to top up.

Takes no parameters.

list_predictions

List past predictions (run history), newest window first. Defaults to the last 24 hours; pass since/until (ISO or YYYY-MM-DD) for other ranges. Use get_prediction with an id for one task in full.

Parameterspagelimitmodelsinceuntilstatus

list_billings

List itemized charges and refunds (billing records). Requires an API key with Billing access.

Parameterskeypagetypelimitmodelsinceuntil

get_usage

Usage statistics: spend, request counts, daily series and per-model breakdown. Defaults to the last 7 days. Requires an API key with Billing access.

Parametersmodelsinceuntil

delete_predictions

Delete finished predictions from this account's run history, up to 100 at a time. This is a soft delete: each record stays, with status "deleted" and without its outputs, and list_predictions and get_prediction still return it that way; the output links are revoked (best effort). This tool cannot undo it. Runs that are still going are left alone, and only the key's own organization's records are deleted. Ask the user first, and pass confirm: true only after they agreed to delete these ids.

Parametersidsrequiredconfirmrequired

upload_file

Upload a local file to WaveSpeed and get its hosted URL (identical bytes reuse the same upload for 24h). Usually unnecessary — run_model handles "@./path" inputs itself.

Parameterspathrequired

get_prediction

Fetch the status and outputs of a past or in-flight prediction by id — use to pick up a run that returned done=false. Pass wait_seconds to keep waiting for it to finish.

Parametersidrequiredwait_seconds

Version history

16
  1. v1.2.10LatestNov 6, 2026
  2. v1.2.8Nov 5, 2026
  3. v1.2.7Nov 3, 2026
  4. v1.2.6Nov 3, 2026
  5. v1.2.4Nov 1, 2026
  6. v1.2.3Nov 1, 2026
  7. v1.2.2Oct 29, 2026
  8. v1.1.0Oct 26, 2026
  9. v1.0.18Oct 21, 2026
  10. v1.0.17Oct 20, 2026
  11. v1.0.14Oct 20, 2026
  12. v1.0.12Oct 19, 2026
  13. v1.0.11Oct 19, 2026
  14. v1.0.10Oct 17, 2026
  15. v1.0.8Oct 1, 2026
  16. v1.0.7Sep 16, 2026

Score

100% 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.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts