WaveSpeed MCP

npx add-mcp 'https://api.wavespeed.ai/mcp'

Every WaveSpeed model — from your terminal and agent

One open-source CLI to run any WaveSpeed AI model. Image, video, audio, 3D. Built for terminals and coding agents like Codex, Claude Code, Claude Cowork, and Cursor.

ClaudeChatGPTCodexCursorVS CodeGeminiWindsurfClineGitHub CopilotPerplexity

MCP

@wavespeed/mcp

$claude mcp add --transport http wavespeed https://api.wavespeed.ai/mcp

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

CLI

@wavespeed/cli

$npm install -g @wavespeed/cli

Prefer MCP? Connect any MCP client

The WaveSpeed MCP server gives Claude Desktop, Claude Code, Cursor, Cline and any other MCP client the same live catalog: search models, read a model's real inputs, quote the price, then run it.

Local server: signed in with wavespeed login? It uses the same login. Otherwise set WAVESPEED_API_KEY.

Remote server — add by URL

Nothing to install. In Claude on the web or ChatGPT, add a custom connector with this address and sign in with your WaveSpeed account. Tools that can send request headers can use an API key as a Bearer token instead. In ChatGPT: open Plugins, choose Add custom MCP server, keep /mcp in the address, and choose OAuth.

$https://api.wavespeed.ai/mcp

Claude Code

$claude mcp add --transport http wavespeed https://api.wavespeed.ai/mcp

Codex

$codex mcp add wavespeed --url https://api.wavespeed.ai/mcp && codex mcp login wavespeed

VS Code

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

Cursor

Add to Cursor

Claude Code — local (npx)

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

Cursor

Install it in Cursor with one click.

Add to Cursor

Claude Desktop and other clients

Add this to the mcpServers section of your client's config.

{
  "mcpServers": {
    "wavespeed": {
      "command": "npx",
      "args": ["-y", "@wavespeed/mcp@latest"],
      "env": {
        "WAVESPEED_API_KEY": "wsk_..."
      }
    }
  }
}

Tools

list_models

Search the live catalog by text or type

get_model_schema

A model's real inputs, required fields and defaults

run_model

Run any model; local @file inputs upload automatically

get_price

Quote the cost before you spend

get_balance

Check your credit balance

upload_file

Turn a local file into a hosted URL

get_prediction

Pick up a long-running generation by its id

list_predictions

Browse your run history

list_billings

See itemized charges and refunds

get_usage

Check spend and usage by day and model

delete_predictions

Delete finished runs from your history (asks you first)

upload_file is only in the local server. The remote server can't read your files: pass public URLs, use create_upload from a tool that can send HTTP requests, or, in ChatGPT, attach the file to the chat.

GitHub npm Docs

Three commands and you're shipping

1

Install

Node 18+ required. One global install gives you the wavespeed binary everywhere.

$npm install -g @wavespeed/cli

3

Run any model

Same shape for all models. Pass the model ID and inputs — get a CDN URL back, or pipe --json to your scripts.

$wavespeed run wavespeed-ai/z-image/turbo -p "a cat"

No Node.js?

On macOS and Linux, install a standalone executable instead. On Windows, download it from GitHub Releases.

$curl -fsSL https://raw.githubusercontent.com/WaveSpeedAI/wavespeed-cli/main/install.sh | bash

Stay up to date

Upgrade to the latest version with one command.

$wavespeed upgrade

Use WaveSpeed models in your coding agent

Configure Claude Code, Codex, OpenCode and more to use the WaveSpeed LLM API. Undo any time.

$wavespeed setup

Built for humans and agents

Dynamic per-model help

Run wavespeed run <model> -h and the CLI fetches that model's input schema live and prints the exact flags it accepts — no guessing.

Aliases that ship with your repo

Define named shortcuts in wavespeed.json that bundle a model + default inputs. Teams pull the file, type wavespeed run hero, get on-brand output.

Agent-native by design

Every command supports --json on stdout and progress on stderr. Drop a SKILL.md so Codex, Claude Code, Claude Cowork, and Cursor know how to call it.

No magic, no daemon

The CLI never mutates your prompt and never opens a background process. It calls api.wavespeed.ai directly. Open source, MIT licensed.

What a real session looks like

From catalog browse to JSON output — three commands.

# 1. browse the catalog
$ wavespeed models --type text-to-image --popular

# 2. inspect a model's inputs — schema fetched live
$ wavespeed run wavespeed-ai/z-image/turbo -h
  * prompt          string
    size            string   default: "1024*1024"
    strength        number   default: 0.6   range: 0..1
    output_format   string   default: "jpeg"   enum: jpeg | png | webp

# 3. run — JSON out so you can pipe it
$ wavespeed run wavespeed-ai/z-image/turbo \
    -p "a cyberpunk skyline at golden hour" --json
{
  "model": "wavespeed-ai/z-image/turbo",
  "outputs": ["https://example.com/output/skyline.jpeg"],
  "elapsed_ms": 4718
}

Plug into your coding agent in one step

No extra config. Coding agents like Codex, Claude Code, and Claude Cowork already know how to run shell commands — the SKILL.md tells them how to use the CLI.

$wavespeed skill install

Works with Codex, Claude Code, Claude Cowork, Cursor, and any agent that auto-loads.claude/skills/*.

Open source. Ready today.

MIT licensed, scoped under @wavespeed on npm, hosted on GitHub. Issues and PRs welcome.

Prefer a graphical app? Try WaveSpeed Desktop See every way to connect WaveSpeed