{
  "markdown": "# @aetherwave-studio/mcp\n\n[![aetherwave-mcp MCP server](https://glama.ai/mcp/servers/AetherWave-Studio/aetherwave-mcp/badges/card.svg)](https://glama.ai/mcp/servers/AetherWave-Studio/aetherwave-mcp)\n\n[![aetherwave-mcp MCP server](https://glama.ai/mcp/servers/AetherWave-Studio/aetherwave-mcp/badges/score.svg)](https://glama.ai/mcp/servers/AetherWave-Studio/aetherwave-mcp)\n\nModel Context Protocol server for [AetherWave Studio](https://aetherwavestudio.com). Drop it into any MCP-compatible client (Claude Code, Cursor, Continue, Claude Desktop, custom agents) and your LLM can generate, edit, upscale, reframe, and master across every flagship creative AI provider through one API key, one credit pool.\n\nOne install. One token. Sixteen tools covering:\n\n- **Music** - Suno V3.5 / V4 / V4.5 / V5 / V5.5\n- **Image gen** - Grok Imagine, GPT Image 2, Seedream V4, Wan 2.7, Imagen 4, Nano Banana, Ideogram V3, Z-Image Turbo\n- **Image edit** - Grok Imagine I2I, Seedream V4 Edit, Flux Kontext, Wan 2.5 Spicy, Qwen Edit, Midjourney I2I, GPT Image 1.5\n- **Image utility** - Topaz upscale, Recraft background removal (with fal BiRefNet v2 fallback), Ideogram V3 Reframe\n- **Video** - Grok Imagine (KIE+fal fallback), Wan 2.7, Hailuo 02, Seedance Pro/Lite, Kling 2.6 (audio), VEO 3.1, Happy Horse\n- **Video utility** - Atlas upscaler (1080p/2K), rembg u2netp background removal, Luma Ray 2 Flash reframe\n- **Audio mastering** - 12 genre/style presets via the AetherWave Python service\n- **Gallery read** - paginated list of your saved creations\n\nEvery generation tool submits the job, polls until terminal state, and returns the final URL. The agent gets a single round-trip, no manual polling loop. Results auto-save to your Cloudflare R2 gallery so URLs don't expire.\n\n## Quick start\n\n```bash\n# 1. Get a key at https://aetherwavestudio.com/profile (Developer tab)\n# 2. Add to your MCP client config (see below)\n# 3. Restart the client\n# 4. Ask your agent to \"generate a synthwave album cover, then animate it\"\n```\n\n### Claude Code\n\n```bash\nclaude mcp add aetherwave \\\n  -e AETHERWAVE_API_KEY=aw_live_your_key_here \\\n  -- npx -y @aetherwave-studio/mcp\n```\n\n### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"aetherwave\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aetherwave-studio/mcp\"],\n      \"env\": {\n        \"AETHERWAVE_API_KEY\": \"aw_live_...\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop.\n\n### Cursor\n\nIn Cursor Settings -> MCP -> Add new server:\n\n```json\n{\n  \"aetherwave\": {\n    \"command\": \"npx\",\n    \"args\": [\"-y\", \"@aetherwave-studio/mcp\"],\n    \"env\": { \"AETHERWAVE_API_KEY\": \"aw_live_...\" }\n  }\n}\n```\n\n### Continue (VS Code / JetBrains)\n\nIn your `~/.continue/config.yaml`:\n\n```yaml\nmcpServers:\n  - name: aetherwave\n    command: npx\n    args: [\"-y\", \"@aetherwave-studio/mcp\"]\n    env:\n      AETHERWAVE_API_KEY: aw_live_...\n```\n\n### Custom / programmatic clients\n\nStandard stdio MCP server. Any client that speaks JSON-RPC 2.0 over stdio per the [MCP spec](https://spec.modelcontextprotocol.io/) can connect:\n\n```bash\nAETHERWAVE_API_KEY=aw_live_... npx -y @aetherwave-studio/mcp\n```\n\n## Tools at a glance\n\n| Tool | Purpose |\n|------|---------|\n| `aetherwave_balance` | Current credit balance + plan |\n| `aetherwave_list_image_models` | Enumerate every image model with cost, speed, I2I support |\n| `aetherwave_list_video_models` | Enumerate every video model with cost-per-second, durations, resolutions |\n| `aetherwave_list_master_presets` | Enumerate the 12 mastering presets with target LUFS, tags, descriptions |\n| `aetherwave_generate_image` | T2I or I2I across 8+ models. Default `grok-imagine-t2i` (5 cr, 6 outputs) |\n| `aetherwave_generate_video` | T2V or I2V across 7+ model families. Default `grok-imagine-t2v` with KIE+fal fallback |\n| `aetherwave_generate_music` | Suno V5.5 by default. Two tracks per submission, lyrics + instrumental |\n| `aetherwave_edit_image` | I2I editing. Default `grok-imagine-i2i` (3 cr/image effective, 2 variations) |\n| `aetherwave_upscale_image` | Topaz upscale 1x / 2x / 4x / 8x |\n| `aetherwave_reframe_image` | Ideogram V3 Reframe to a new aspect ratio (outpaints edges) |\n| `aetherwave_remove_background` | Recraft primary + fal BiRefNet v2 fallback (auto failover). Output auto-saved to gallery |\n| `aetherwave_upscale_video` | Atlas Video Upscaler, 1080p or 2K |\n| `aetherwave_remove_background_video` | Frame-by-frame bg removal via rembg u2netp. Transparent WebM or solid color output. 2 cr/sec |\n| `aetherwave_reframe_video` | Luma Ray 2 Flash reframe to new aspect ratio |\n| `aetherwave_master_audio` | AI mastering across 12 genre/style presets. 20 cr/track, free on Producer / Mogul / Ultimate plans |\n| `aetherwave_list_my_creations` | Paginated gallery read for chained workflows |\n\nEvery generation tool includes a model-selection rubric in its description. Your agent can pick the right model from prompt intent without round-tripping `list_image_models` or `list_video_models`.\n\n## Tools reference\n\n### `aetherwave_balance`\n\nReturns current credit balance. No inputs.\n\n**Returns:** `{ credits, plan, ... }`\n\n### `aetherwave_list_image_models`\n\nReturns every image model with credit cost, supported inputs, resolution/aspect options. No inputs.\n\n**Returns:** `{ models: [...] }`\n\n### `aetherwave_list_video_models`\n\nReturns every video model with per-second credit cost, durations, resolutions, aspect ratios. No inputs.\n\n**Returns:** `{ models: [...] }`\n\n### `aetherwave_list_master_presets`\n\nReturns every mastering preset with target LUFS, tags, descriptions, difficulty. No inputs. Call this before `master_audio` when you don't know which preset fits the track.\n\n**Returns:** `{ presets: [...] }` (each: `{ id, name, description, target_lufs, tags, difficulty, icon }`)\n\n### `aetherwave_generate_image`\n\nT2I or I2I. Submits, polls, returns final URLs.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `prompt` | string | yes | — | Text description of the image |\n| `model` | string | no | `grok-imagine-t2i` | Model ID. Use `list_image_models` for full list |\n| `aspectRatio` | string | no | model default | e.g. `1:1`, `16:9`, `9:16` |\n| `resolution` | string | no | model default | `1K`, `2K`, some accept `480p`/`720p` |\n| `referenceImages` | string[] | no | — | URLs for I2I; required if model is I2I |\n| `numImages` | int (1-8) | no | model default | For multi-output models |\n| `negative_prompt` | string | no | — | Supported by some models |\n| `seed` | int | no | — | Deterministic generation, supported by some |\n\n**Selection signals (built into the tool description):** photoreal → `z-image-turbo` or `imagen-4`. Text-in-image → `ideogram-v3-t2i`. NSFW → `wan-2.5-spicy-t2i`. Premium → `grok-imagine-quality-t2i` or `imagen-4-ultra`. Cheapest → `z-image-turbo` (3 cr).\n\n**Returns:** `{ taskId, state, images, autoSaved, creationIds }`\n\n### `aetherwave_generate_video`\n\nT2V or I2V. Submits, polls up to 8 min, returns final URL.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `prompt` | string | yes | — | Text description of the scene |\n| `model` | string | no | `grok-imagine-t2v` | Model ID. Use `list_video_models` |\n| `duration` | int (2-30) | no | model default | Seconds. Grok accepts 6-15 |\n| `resolution` | enum | no | model default | `480p`, `720p`, `1080p`, `2K` |\n| `aspectRatio` | string | no | model default | e.g. `16:9`, `9:16`, `1:1` |\n| `imageUrl` | string | no | — | Required for I2V models |\n| `endImageUrl` | string | no | — | Some I2V models support first+last frame |\n| `mode` | enum | no | `normal` | Grok Imagine: `fun`, `normal`, `spicy` |\n\n**Returns:** `{ taskId, state, videoUrl, fallbackProvider, autoSaved, creationId, kieTaskId }`\n\n### `aetherwave_generate_music`\n\nSuno music generation. Two tracks per submission.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `prompt` | string | yes | — | Style/mood/topic description |\n| `instrumental` | boolean | no | `false` | If true, no vocals |\n| `model` | enum | no | `V5_5` | `V3_5`, `V4`, `V4_5`, `V5`, `V5_5` |\n| `title` | string | no | — | Optional title for the tracks |\n| `lyrics` | string | no | — | Custom lyrics, omit to let Suno write them |\n\n**Returns:** `{ taskId, status, tracks }`\n\n### `aetherwave_edit_image`\n\nI2I editing guided by a text prompt.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `prompt` | string | yes | — | Text description of the edit |\n| `imageUrl` | string | yes | — | Public URL of source image |\n| `model` | string | no | `grok-imagine-i2i` | 3 cr/image effective, 2 outputs |\n| `aspectRatio` | string | no | source ratio | e.g. `1:1`, `16:9` |\n| `resolution` | string | no | model default | Some models: `1K`, `2K`, `4K` |\n| `quality` | enum | no | model default | `low`, `medium`, `high` (GPT Image) |\n| `maxImages` | int (1-8) | no | — | For multi-output models |\n| `renderingSpeed` | enum | no | model default | `turbo`, `balanced`, `quality` |\n| `negative_prompt` | string | no | — | Supported by some models |\n\n**Selection signals:** subtle edits / character consistency → `flux-kontext-pro`. NSFW → `wan-2.5-spicy-i2i`. Highest quality → `gpt-image-1.5-i2i` or `grok-imagine-quality-i2i`. Stylized → `midjourney-i2i`. Single-output / 4K → `seedream-v4-edit`.\n\n**URL gotcha:** source URLs with spaces or parentheses may fail upstream. Prefer clean URLs without special characters.\n\n**Returns:** `{ taskId, state, images, autoSaved, creationIds }`\n\n### `aetherwave_upscale_image`\n\nTopaz upscaler.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `imageUrl` | string | yes | — | Public URL of source image |\n| `upscaleFactor` | enum | no | `2x` | `1x`, `2x`, `4x`, `8x`. Use 8x only on small sources |\n\nCredit cost scales with source resolution × factor.\n\n**Returns:** `{ taskId, state, images, autoSaved, creationIds }`\n\n### `aetherwave_reframe_image`\n\nIdeogram V3 Reframe. Outpaints edges to fit a new aspect ratio.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `imageUrl` | string | yes | — | Public URL of source image |\n| `aspectRatio` | string | yes | — | Target ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `21:9` |\n| `speed` | enum | no | `balanced` | `turbo` (5 cr), `balanced` (10 cr), `quality` (14 cr) |\n\n**Returns:** `{ taskId, state, images, autoSaved, creationIds }`\n\n### `aetherwave_remove_background`\n\nRecraft primary + fal.ai BiRefNet v2 fallback. ~5 cr per image.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `imageUrl` | string | yes | — | Public URL of source image |\n\n**Returns:** `{ taskId, state, images }` (PNG with transparent alpha)\n\n### `aetherwave_upscale_video`\n\nAtlas Video Upscaler. Targets 1080p or 2K.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `videoUrl` | string | yes | — | Public URL of source video (MP4) |\n| `targetResolution` | enum | no | `1080p` | `1080p` (7 cr/s, ≤53s) or `2k` (9 cr/s, ≤23s). Source must be ≤30fps |\n\n**Returns:** `{ taskId, status, videoUrl, autoSaved, creationId }`\n\n### `aetherwave_remove_background_video`\n\nFrame-by-frame background removal via rembg u2netp on AetherWave's Python service. 2 cr/sec.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `videoUrl` | string | yes | — | Public URL of source video (MP4) |\n| `bgType` | enum | no | `transparent` | `transparent` = alpha WebM, `color` = solid replacement |\n| `customColor` | string | no | `#00ff00` | Hex color for solid replacement when `bgType: \"color\"` |\n\n**Returns:** `{ taskId, status, videoUrl, autoSaved, creationId }`\n\n### `aetherwave_reframe_video`\n\nLuma Ray 2 Flash reframe to a new aspect ratio. 17 cr/sec.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `videoUrl` | string | yes | — | Public URL of source video (MP4) |\n| `reframeAspectRatio` | enum | yes | — | `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9` |\n| `reframePrompt` | string | no | — | Optional steering prompt for new edge content (e.g. \"extend the sky with sunset clouds\") |\n\n**Returns:** `{ taskId, status, videoUrl, autoSaved, creationId }`\n\n### `aetherwave_master_audio`\n\nAI mastering via the AetherWave Python service. Synchronous response (route polls internally, expect 30s-5min). 20 credits per track. Free for Producer, Mogul, and Ultimate plans. Output is WAV (~50MB per 3-min track) and auto-rehosted to Cloudflare R2.\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `audioUrl` | string | yes | — | Public URL to MP3 or WAV |\n| `preset` | string | yes | — | One of 12 (see below) |\n| `trackTitle` | string | no | — | Optional title for gallery row |\n\n**Preset list (12, retrieved live from `/api/master-presets`):**\n\n| Preset | Name | Target LUFS | Use for |\n|--------|------|-------------|---------|\n| `streaming` | Streaming Ready | -14 | Spotify, Apple Music, YouTube |\n| `loud` | Loud & Punchy | -9 | Competitive loudness |\n| `gentle` | Gentle Touch | -16 | Acoustic, classical, jazz |\n| `hip_hop` | Hip Hop / Trap | -11 | Heavy low + crisp highs + 808s |\n| `edm` | EDM / Electronic | -10 | House, techno, dubstep, drops |\n| `pop` | Pop / Top 40 | -12 | Radio-ready polish |\n| `rock` | Rock / Alternative | -12 | Punchy mids, gritty edge |\n| `lofi` | Lo-Fi / Chill | -14 | Warm, relaxed |\n| `rnb` | R&B / Soul | -13 | |\n| `acoustic` | Acoustic / Folk | -16 | Preserves dynamics |\n| `cinematic` | Cinematic / Orchestral | -18 | Wide dynamics |\n| `podcast` | Podcast / Voice | -16 | Voice-forward |\n\n**Returns:** `{ success, masteredUrl, preset, trackTitle, creditsCharged, isFree }`\n\n### `aetherwave_list_my_creations`\n\nPaginated gallery read. Useful for chaining (\"reframe my last 5 images to 9:16\").\n\n| Param | Type | Required | Default | Notes |\n|-------|------|----------|---------|-------|\n| `type` | enum | no | all | `image`, `video`, `audio` |\n| `limit` | int (1-500) | no | 100 | Max items |\n| `offset` | int | no | 0 | Pagination offset |\n| `favoritesOnly` | boolean | no | `false` | Filter to favorites |\n\n**Returns:** `{ items, total, offset, limit, hasMore }`. Each item: `{ id, type, title, prompt, model, createdAt, isFavorite, contentUrl, thumbnailUrl, visibility, rating, duration?, width?, height?, likeCount, totalPlays, metadata }`.\n\n## Credits & pricing\n\nAetherWave uses a single credit pool. Buy bundles starting at $4.99 / 500 credits (bundle credits never expire) or subscribe to Studio ($9.99/mo, 1,700 credits, 3-day free trial). Both work for API calls.\n\nTypical costs:\n\n- **Image gen** - 3 cr (Z-Image Turbo) to 22 cr (Grok Imagine Quality at 2K)\n- **Image edit** - 3 cr/image (Grok Imagine I2I) to 22 cr (Grok Imagine Quality I2I at 2K)\n- **Image utility** - 5 cr (background removal, reframe at turbo speed), 5-25+ cr (Topaz upscale, resolution-dependent)\n- **Video** - 4-6 cr/sec (Grok Imagine) up to ~80 cr/sec (VEO 3.1)\n- **Music** - 12 cr per generation (2 tracks)\n- **Mastering** - 20 cr/track (free on Producer / Mogul / Ultimate)\n\nSee live pricing at https://aetherwavestudio.com/buy-credits or via `aetherwave_list_*_models`.\n\n## Environment variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `AETHERWAVE_API_KEY` | yes | — | Your API key. Get one at /profile -> Developer tab. Must start with `aw_live_`. |\n| `AETHERWAVE_BASE_URL` | no | `https://aetherwavestudio.com` | Override the API base URL (useful for staging or self-hosted). |\n\n## Troubleshooting\n\n**\"AETHERWAVE_API_KEY environment variable is required\"**\nYour MCP client isn't passing the env var. Make sure the `env` block in your client config has `AETHERWAVE_API_KEY` set. After editing config, fully restart the client.\n\n**\"AetherWave API ... failed: 401 - Invalid API key\"**\nThe key has been revoked or regenerated. Visit https://aetherwavestudio.com/profile -> Developer tab and copy a fresh key.\n\n**\"AetherWave API ... failed: 402 - Insufficient credits\"**\nYour balance is too low for the requested operation. Call `aetherwave_balance` to confirm, then top up at https://aetherwavestudio.com/buy-credits.\n\n**\"AetherWave generation timed out after Xs\"**\nThe provider is queueing. The job may still complete server-side - check the AetherWave gallery at https://aetherwavestudio.com/gallery.html. If timeouts persist for a particular model, try a different one (e.g. switch from `grok-imagine-t2v` to `wan-2-7-t2v`, or `gpt-image-1.5-i2i` to `grok-imagine-i2i`).\n\n**\"Unprocessable Entity\" on reframe**\nIdeogram's URL fetcher chokes on source URLs containing spaces, parentheses, or other special characters. Use clean URLs (try downloading and re-uploading to a clean R2 path if needed).\n\n**\"internal error, please try again later\" on remove_background**\nKIE Recraft transient outage. The tool will auto-fall-back to fal.ai BiRefNet v2 on retry, but a single call returning this error means both providers refused. Wait a minute and retry.\n\n**Soul Forge band generation**\nNot exposed via MCP. Soul Forge remains a consumer feature on the web at https://aetherwavestudio.com/soul-forge.\n\n## Versioning\n\nThis package follows semver. Tools that change behavior in a breaking way will bump the major version. New tools and additive parameters bump the minor version. Bug fixes bump the patch version.\n\nThe MCP protocol version itself (currently `2024-11-05`) is negotiated at handshake time by the SDK; no client config needed.\n\n## Links\n\n- AetherWave Studio: https://aetherwavestudio.com\n- Developer docs: https://aetherwavestudio.com/developers\n- Get an API key: https://aetherwavestudio.com/profile (Developer tab)\n- Buy credits: https://aetherwavestudio.com/buy-credits\n- GitHub: https://github.com/AetherWave-Studio/aetherwave-mcp\n- npm: https://www.npmjs.com/package/@aetherwave-studio/mcp\n\n## License\n\nMIT. See LICENSE.\n",
  "bytes": 18157,
  "sha": "992c2a1c808eba40e1dba2c0b0b032d9d7c62e4fed256bbc5296c80e06b9b0e7",
  "repo_slug": "aetherwave-studio/aetherwave-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aetherwave_studio_aetherwave_m_5b623059/readme"
}