@pixelbananas/mcp

MCP server for the PixelBananas AI audio API. Lets Claude Code (and any MCP client) generate SFX, chiptune BGM, and themed audio kits as part of multi-step workflows.

Tools

| Tool | What | Cost | |---|---|---| | generate_sfx | Text prompt → 8-bit SFX. Auto-saves .wav (+ .mp3 if format="both"). | 1 / 2 / 4 credits | | generate_bgm | Text prompt → chiptune BGM. Auto-saves .wav + .mid (8/16/32 bars). | 5–20 credits | | generate_kit | Template → cohesive audio kit ZIP (Studio tier). | 50–200 credits | | download_audio | Re-render an existing generation by ID to disk. | free | | list_generations | List your recent generations. | free | | get_generation | Full details of one generation by ID. | free | | share_patch | Public share URL for a patch. | free |

Setup

1. Create a Personal Access Token

Log in at https://pixelbananas.pages.dev/login → visit /settings/tokens → + CREATE. Copy the pba_live_... token (shown once).

2. Register with your MCP client

Claude Code (~/.claude/mcp.json or per-project .claude/mcp.json):

{
  "mcpServers": {
    "pixelbananas": {
      "command": "npx",
      "args": ["-y", "@pixelbananas/mcp"],
      "env": {
        "PIXELBANANAS_TOKEN": "pba_live_REPLACE_ME"
      }
    }
  }
}

Claude.ai desktop (~/Library/Application Support/Claude/claude_desktop_config.json): same shape as above.

3. Verify

Restart your client and ask Claude:

List my PixelBananas generations

You should see the list_generations tool run and return recent items.

Output files

By default, generate_sfx and generate_bgm write the rendered audio to disk so you don't need a second tool call.

Where files go (in order of precedence):

1. The outputDir tool argument (per call).
2. The PIXELBANANAS_OUTPUT_DIR env var.
3. ./pixelbananas-audio/ under the cwd of the MCP process (auto-created).

Filename: a slug of the prompt (lowercase, non-alphanumeric → -, truncated to 50 chars), with -2, -3, … appended on collision. Override with the filename tool argument.

Formats: format: "wav" | "mp3" | "both" (default "wav"). For generate_bgm, a .mid file is also written unless includeMidi: false.

Skip saving entirely: save: false (still returns the patch JSON).

Note on BGM rendering: the MCP renderer is a chiptune approximation using plain Web Audio nodes. The web app uses Tone.js wrappers (MembraneSynth/MetalSynth) for slightly different drum timbres. Patch / song JSON is identical between the two; only timbre differs slightly.

Example workflows

"Make 4 boss-fight SFX variants"

Use generate_sfx with prompt="boss explosion, heavy impact, low-end rumble, 8-bit"
and effort=2 (best-of-2). Then save each audio URL to /assets/sfx/boss_N.wav.

Claude fires generate_sfx four times, each with a slight prompt variation (e.g. "...faster decay", "...metallic"), and reports back with the URLs + credit balance.

"Generate intro/explore/boss BGM for Thyrsus Act II"

Use generate_bgm three times:
- prompt="calm sunrise intro, pentatonic, slow tempo" bars=16 effort=1
- prompt="wandering exploration, dorian mode, medium tempo" bars=16 effort=1
- prompt="intense boss battle, harmonic minor, driving drums" bars=32 effort=2

Environment variables

| Var | Default | Meaning | |---|---|---| | PIXELBANANAS_TOKEN | (required) | Personal access token (pba_live_...) | | PIXELBANANAS_API_URL | https://pixelbananas-api.nano122090.workers.dev | Worker base URL | | PIXELBANANAS_FRONTEND_URL | https://pixelbananas.pages.dev | Frontend URL (used for share links) | | PIXELBANANAS_OUTPUT_DIR | (unset) | Default directory for saved audio. Per-call outputDir overrides. |

Cost & rate limits

Every generate call deducts credits server-side; free tier gets 20/month. Rate limit: 5 requests/minute for SFX, 3/minute for BGM. Tools return creditsRemaining on every success so Claude can self-throttle.

Insufficient credits → tool throws insufficient_credits error with the upgrade URL. Run list_generations to review what you've spent on.

Development

npm install
npm run build
npm test

# Run locally with stdio:
PIXELBANANAS_TOKEN=pba_live_xxx node dist/index.js

# Test the protocol handshake:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | PIXELBANANAS_TOKEN=dummy node dist/index.js

Third-party

This package depends on @breezystack/lamejs (LGPL-3.0) for MP3 encoding. lamejs is loaded as a runtime dependency, not modified or bundled. To replace it with a different MP3 encoder, fork this package and substitute the implementation in src/encode/mp3.ts.

License

MIT © PixelBananas