Design & MediaMCP Registrynpm16 toolsA · 92

Wavespeed MCP

Name: Wavespeed MCP
Author: wavespeed.ai

ai.wavespeed · Updated today

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

At a glance

Wavespeed MCP is an MCP server in the Design & Media category. It runs locally over stdio via `npx -y @wavespeed/mcp`, and needs WAVESPEED_API_KEY. It exposes 16 tools, including list_models, get_model_schema and run_model. It scores A (92/100) on the MCP Skills Hub health score as of Oct 27, 2026.

Source 35

One-click install

VS Code VS Code Insiders Cursor

Opens your editor and pre-fills the config. Your editor will ask before adding it.

How to install Wavespeed MCP in your AI client

Setup for Claude Code, Claude Desktop, Cursor, Codex, Windsurf, Cline and VS Code — copy-paste ready.

How to install Wavespeed MCP in Claude CodeAnthropic's agentic CLI

Add the server

bash

claude mcp add wavespeed -e 'WAVESPEED_API_KEY=<WAVESPEED_API_KEY>' -- npx -y @wavespeed/mcp

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
3
Verify it's connected
bash
```
claude mcp list
```
Sharing it with your team?
Add `--scope project` to write it to .mcp.json in the repository root, which you can commit (with the secrets left as environment variables).
Use it in a session
Ask Claude to use the tools this server exposes (e.g. list_models, get_model_schema, run_model). It discovers them automatically.

How to install Wavespeed MCP in Claude DesktopDesktop app (MCP config)

Open your MCP config
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this server

json

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": [
        "-y",
        "@wavespeed/mcp"
      ],
      "env": {
        "WAVESPEED_API_KEY": "<WAVESPEED_API_KEY>"
      }
    }
  }
}

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
Restart Claude Desktop
The tools appear under the 🔌 menu once the app reloads.

How to install Wavespeed MCP in CursorAI-first code editor

Create / edit .cursor/mcp.json in your project

json

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": [
        "-y",
        "@wavespeed/mcp"
      ],
      "env": {
        "WAVESPEED_API_KEY": "<WAVESPEED_API_KEY>"
      }
    }
  }
}

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
Enable it
Cursor Settings → MCP → toggle the server on. Tools become available to the Composer/Agent.

How to install Wavespeed MCP in Codex CLIOpenAI coding agent

Add to ~/.codex/config.toml

toml

[mcp_servers.wavespeed]
command = "npx"
args = ["-y", "@wavespeed/mcp"]
env = { WAVESPEED_API_KEY = "<WAVESPEED_API_KEY>" }

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
Run Codex
Codex loads MCP servers from config.toml on startup and exposes their tools to the agent.

How to install Wavespeed MCP in WindsurfCodeium's agentic IDE

Edit ~/.codeium/windsurf/mcp_config.json

json

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": [
        "-y",
        "@wavespeed/mcp"
      ],
      "env": {
        "WAVESPEED_API_KEY": "<WAVESPEED_API_KEY>"
      }
    }
  }
}

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
Reload
Windsurf → Cascade → refresh MCP servers. Cascade can now call the tools.

How to install Wavespeed MCP in ClineVS Code autonomous agent

Open Cline → MCP Servers → Configure
Adds to cline_mcp_settings.json.

Add the server

json

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": [
        "-y",
        "@wavespeed/mcp"
      ],
      "env": {
        "WAVESPEED_API_KEY": "<WAVESPEED_API_KEY>"
      }
    }
  }
}

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.

How to install Wavespeed MCP in VS CodeCopilot / MCP support

Create .vscode/mcp.json

json

{
  "servers": {
    "wavespeed": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@wavespeed/mcp"
      ],
      "env": {
        "WAVESPEED_API_KEY": "<WAVESPEED_API_KEY>"
      }
    }
  }
}

Fill in your credentials
Replace <WAVESPEED_API_KEY> with your real value. Keep secrets out of any config file you commit.
Start it
VS Code shows a ▶ Start action above the server entry. Agent mode (Copilot Chat) can then use the tools.

What does Wavespeed MCP need from you?

API key — WaveSpeed API key (https://wavespeed.ai/accesskey). Optional when the wavespeed CLI is logged in.

WAVESPEED_API_KEYoptionalsecretEnvironment variable
WaveSpeed API key (https://wavespeed.ai/accesskey). Optional when the wavespeed CLI is logged in.
WAVESPEED_BASE_URLoptionalEnvironment variable
Override the WaveSpeed API base URL. Defaults to https://api.wavespeed.ai.
WAVESPEED_CLIENT_NAMEoptionalEnvironment variable
Override the client name reported for channel attribution. Defaults to wavespeed-mcp.

Pass secrets through your shell environment rather than committing them into a config file.

What tools does Wavespeed MCP expose? (16)

Taken from the project's README — the server itself was not queried, so check its docs for the exact schemas.

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

What the code can do

Read from the published package source — never executed. Parsed 11 of 11 source files.

This server can read and write files, make network requests and read your environment variables.

How it was published

Published by a verified CI identity (github trusted publishing) rather than a personal token.
Has a provenance attestation tying this artifact to the commit it was built from.
2 npm maintainers · last published by GitHub Actions.

Maintainer of this package and think something here is wrong? Tell us and we'll correct it.

Before you install

Signals gathered from the source repo and package registry — not a safety verdict.

What it can reach

Runs code on your machine — Executes as a local process with your user's permissions, including filesystem access.
Downloads at launch — The package is fetched from its registry each run unless you pin a version.

Last commit today — Actively maintained.
35 GitHub stars — Community adoption signal.
1.5k weekly downloads — Regularly installed by other developers.

Client compatibility

Claude Code: NativeClaude Desktop: NativeCursor: NativeCodex CLI: NativeWindsurf: NativeCline: NativeVS Code: Native

Health score

A · 92

Maintenance, adoption, transparency and packaging — not a safety audit. How this is calculated

Maintenance30%100%
Last commit 0 days ago.
Adoption20%61%
35 stars, 1530 weekly downloads.
Transparency20%100%
4/4: ✓ public source repo, ✓ declared license, ✓ documentation, ✓ discoverable tool list.
Provenance15%100%
Package and registry entry point at the same repository.
Packaging15%100%
Publishes a pinned version (1.1.3).

Documentation

Full README

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_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

| Tool | What it does | |---|---| | list_models | Search the live catalog by text or modality type | | get_model_schema | A model's real input schema (required, properties, defaults), with a link to the model's playground page | | run_model | Submit + wait; rejects input keys the model doesn't accept; @path inputs upload automatically; returns output URLs | | generate_image | Image from a prompt with the /chat image models (default Seedream 5 Pro); reference images use the model's edit endpoint | | edit_image | Edit, restyle or combine existing images with the same models | | generate_video | Video 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_video | Edit an existing video, optionally with reference images/audio | | extend_video | Continue an existing video with new footage | | get_price | Cost estimate for the inputs you pass (no charge), with a link to the model's playground page | | get_balance | Account credit balance, with the top-up link | | list_predictions | Run history (default last 24h); filter by model, status, time range | | list_billings | Itemized charges and refunds (needs a Billing-access key) | | get_usage | Spend, request counts and per-model breakdown (default last 7 days; needs a Billing-access key) | | delete_predictions | Delete finished runs from the history (up to 100; needs confirm: true, cannot be undone from here) | | upload_file | Local file → hosted URL (24h content-hash dedupe) | | get_prediction | Status/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:

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

Excerpt — the full document is on GitHub.

Alternatives to Wavespeed MCP

Maintain Wavespeed MCP? Add a badge to your README

Shows its health grade, and links readers to install steps for every client.

markdown

[![Wavespeed MCP on MCP Skills Hub](https://mcp-skills-hub.vercel.app/badge/ai-wavespeed-mcp)](https://mcp-skills-hub.vercel.app/mcps/ai-wavespeed-mcp)

Catalog data refreshed Oct 27, 2026. Something wrong? Report it.