@bunnystudio/mcp

Model Context Protocol (MCP) server for Bunny Studio. Exposes every Bunny Studio API endpoint as an MCP tool and provides built-in prompts that prepare any AI agent to use the API correctly — even when the user's request is plain text.

Works with: Claude Desktop, Claude Code, Cursor, VS Code (Copilot / Continue), Windsurf, and any other MCP-compatible client.

Table of Contents

• Quick Start
• Agent Configuration
  • Claude Desktop
  • Claude Code (CLI)
  • Cursor
  • VS Code
  • Windsurf
• Authentication
• Built-in Prompts (AI Preparation)
• Tools Reference
• Usage Examples (Natural Language)
• Tips for Better Results
• Environment Variables
• Development
• Publishing to npm

Quick Start

No installation required — run directly with npx:

# With a pre-obtained JWT token
npx @bunnystudio/mcp --token=YOUR_JWT_TOKEN

# With environment variable
BUNNY_API_TOKEN=YOUR_JWT_TOKEN npx @bunnystudio/mcp

Get a token: Contact a Bunny Studio representative to enable API access on your account. Once enabled, log in through the bunnystudio_login tool or retrieve the token from the authentication endpoint.

If you see ERR_MODULE_NOT_FOUND for zod-to-json-schema when using npx: clear the npx cache and try again: rm -rf ~/.npm/_npx (Linux/macOS) or delete the _npx folder under your npm cache, then run the npx command again.

What you need to know

• Token — You need a Bunny Studio API token (JWT). Get it by logging in via the bunnystudio_login tool, or set BUNNY_API_TOKEN / use --token=….
• Project creation — Creating a project is a two-step flow: the AI runs a preview (quote, validation), then asks for your confirmation before creating the project.
• Services — Only voice over and audio ads are supported. voice_ai is not available in this MCP.

Agent Configuration

Claude Desktop

1. Open (or create) ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
2. Add the Bunny Studio server:

{
  "mcpServers": {
    "bunnystudio": {
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp"],
      "env": {
        "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}

Or pass the token as an argument:

{
  "mcpServers": {
    "bunnystudio": {
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp", "--token=YOUR_JWT_TOKEN"]
    }
  }
}

3. Restart Claude Desktop. The Bunny Studio tools and prompts will appear in the / menu.

Claude Code (CLI)

Add to .claude/settings.json in your project root, or to the global ~/.claude/settings.json:

{
  "mcpServers": {
    "bunnystudio": {
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp"],
      "env": {
        "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}

Then in Claude Code:

/mcp

to verify the server is running and list available tools.

Cursor

1. Open Cursor Settings → MCP.
2. Click Add new MCP server and enter:

{
  "name": "bunnystudio",
  "command": "npx",
  "args": ["-y", "@bunnystudio/mcp"],
  "env": {
    "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
  }
}

Or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "bunnystudio": {
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp", "--token=YOUR_JWT_TOKEN"]
    }
  }
}

VS Code (Copilot / Continue)

With GitHub Copilot (VS Code 1.99+)

Add to .vscode/mcp.json in your workspace, or to your User settings:

{
  "servers": {
    "bunnystudio": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp"],
      "env": {
        "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}

With Continue extension

Add to ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@bunnystudio/mcp"],
          "env": {
            "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
          }
        }
      }
    ]
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bunnystudio": {
      "command": "npx",
      "args": ["-y", "@bunnystudio/mcp"],
      "env": {
        "BUNNY_API_TOKEN": "YOUR_JWT_TOKEN"
      }
    }
  }
}

Authentication

Token resolution order (first available wins):

1. Session token — set by calling bunnystudio_login (used for all later calls in that session)
2. CLI flag — --token=YOUR_JWT_TOKEN
3. Environment variable — BUNNY_API_TOKEN

Option A — Environment variable (recommended)

export BUNNY_API_TOKEN="YOUR_JWT_TOKEN"
npx @bunnystudio/mcp

Option B — CLI flag

npx @bunnystudio/mcp --token=YOUR_JWT_TOKEN

Option C — Login via MCP tool

Call the bunnystudio_login tool from your AI client. The returned token is stored for the session and used automatically for all subsequent calls.

Log me in to Bunny Studio with email [email protected] and password your-password

Authenticate me to the Bunny Studio API.

Custom API URL

For testing against a staging/local instance:

npx @bunnystudio/mcp --api-url=http://localhost:3000 --token=YOUR_JWT

Built-in Prompts (AI Preparation)

The server registers four MCP Prompts that load Bunny Studio domain knowledge into the AI before it starts calling tools. This is how plain-text user requests get correctly mapped to structured API calls.

| Prompt | When to use | |--------|-------------| | bunnystudio_overview | First message in a session — loads all concepts, service types, lifecycle states, and the service config shape | | bunnystudio_create_project_guide | User says something like "I need a 30-second English commercial voice over" — converts a plain brief to a valid create_project payload | | bunnystudio_review_deliverable_guide | User wants to review, approve, reject, or revise deliverables | | bunnystudio_search_and_quote_guide | User wants to find talents or get a price estimate before creating a project |

How to invoke a prompt

In Claude Desktop or Claude Code, type / and look for the Bunny Studio prompts, or ask the AI to use them:

Use the bunnystudio_overview prompt.

Use the bunnystudio_overview prompt to understand how to use the Bunny Studio API.

Use the bunnystudio_create_project_guide prompt with brief: "I need a 30 second upbeat
English female voice over for a TV commercial"

After loading the right prompt, you can continue in natural language (e.g. "Create that project" or "Get me a quote for the same").

Tools Reference

Authentication

| Tool | Description | |------|-------------| | bunnystudio_login | Authenticate with email/password. Token is stored for the session. |

Projects

| Tool | Description | |------|-------------| | bunnystudio_preview_project | Validate inputs and get a price quote before creating (read-only) | | bunnystudio_create_project | Create a voice over or audio ads project (requires confirmation) | | bunnystudio_get_project | Get a project by ID | | bunnystudio_list_projects | List your projects (paginated, filterable) | | bunnystudio_cancel_project | Cancel a project with reason | | bunnystudio_get_quote | Get a price estimate without creating a project |

Deliverables

| Tool | Description | |------|-------------| | bunnystudio_get_deliverable | Get a single deliverable | | bunnystudio_get_deliverables_by_project | Get all deliverables for a project | | bunnystudio_approve_deliverable | Approve a single deliverable | | bunnystudio_select_winner_deliverable | Select winner (contest fulfillment only) | | bunnystudio_approve_deliverables_by_project | Approve all pending deliverables at once | | bunnystudio_reject_deliverable | Reject a deliverable with reason code | | bunnystudio_create_revision | Request a revision with instructions | | bunnystudio_get_deliverable_versions | Get all versions of a deliverable |

Categories

| Tool | Description | |------|-------------| | bunnystudio_get_categories | All categories and subcategories | | bunnystudio_get_category_attributes | Attributes for a subcategory (language, gender/age, etc.) | | bunnystudio_get_category_attribute_values | Valid values for a category attribute | | bunnystudio_get_available_voice_over | Available voice over sub-categories | | bunnystudio_get_available_audio_ads | Available audio ads sub-categories |

Music / Tracks

| Tool | Description | |------|-------------| | bunnystudio_get_track_types | All music track types | | bunnystudio_get_track_subtypes | Subtypes for a track type | | bunnystudio_get_track | Get a specific track by ID | | bunnystudio_get_all_tracks | Browse tracks with filters and pagination | | bunnystudio_get_music_library | Combined mode-based music library browser |

Search

| Tool | Description | |------|-------------| | bunnystudio_search | Search talents/samples by category, filters, and purpose (numeric ID, auto-inferred) |

Definitions (reference data)

| Tool | Description | |------|-------------| | bunnystudio_get_status_types | All status types | | bunnystudio_get_project_status_types | Project status types | | bunnystudio_get_service_status_types | Service status types | | bunnystudio_get_deliverable_status_types | Deliverable status types | | bunnystudio_get_revision_reasons | Reasons for requesting revisions | | bunnystudio_get_cancellation_reasons | Reasons for canceling projects | | bunnystudio_get_rejection_reasons | Reasons for rejecting deliverables |

Response format

Every tool accepts an optional response_format parameter:

• "markdown" (default) — human-readable output
• "json" — raw JSON for programmatic use

Important validation rules

• voice_ai is disabled — only voice_over and audio_ads are available as mainService
• services array is required — at least one service object must be provided when creating projects
• title max length — 100 characters
• purpose (search) — numeric ID, not a string. Valid IDs: 6 (Movie trailers), 7 (Phone systems), 9 (Product videos), 10 (Presentations/Educational), 11 (Commercials/Advertising), 14 (Characters/Videogames), 16 (Live announcements), 19 (Audiobooks/Podcasts), 20 (Radio/TV tags). The AI auto-infers purpose from context — no need to specify the number manually
• Two-phase project creation — For creating projects, the AI calls bunnystudio_preview_project first (validates inputs, returns price quote), then waits for your confirmation before calling bunnystudio_create_project. This avoids creating projects by mistake.

Usage Examples (Natural Language)

You can drive the MCP entirely with plain language. The AI translates your request into the correct tool and parameters. Below are examples you can type (or adapt) in your MCP client.

Getting started

Load the overview so the AI has full Bunny Studio context:

Use the bunnystudio_overview prompt.

Authentication

Log me in to Bunny Studio with email [email protected] and password mypassword123

Authenticate me to the Bunny Studio API.

Project preview (no creation)

Preview validates inputs and returns a price quote without creating anything:

I need a voice over in English (US), young adult female voice.
Script: "Welcome to our platform. We make project management simple and fast."

How would a 30-second audio ad look in Italian with a middle-aged male voice?
Script: "Scopri le nostre offerte esclusive. Visita il nostro sito oggi."

Project creation

The AI will run preview first, show you the quote, and ask for confirmation before creating.

Voice over — speedy (single talent)

I need a voice over in English (US), female voice, adult tone.
Script: "Welcome to our platform. We make project management simple, fast, and stress-free."

Create a voice over project: Language English (US), adult female, speedy fulfillment.
Script: "Hello and welcome to TechCorp. Our mission is to help your business grow."

Voice over — booking (specific talent)

I want to book talent 9VUMQ2C for a voice over in Italian, young adult male.
Script: "Benvenuto nel nostro negozio. Scopri le nostre offerte esclusive oggi stesso."

Voice over — contest (multiple talents compete)

Create a contest for a voice over in English (US), male voice.
Script: "At HomeGlow, we believe everyone deserves a beautiful home."
I want to hear from multiple talents and pick the best one.

Multi-part voice over

I need a voice over with 3 parts in English (US), female voice:
- Part 1 (intro): "Welcome to the annual report for 2024."
- Part 2 (main): "This year, our company achieved record revenue."
- Part 3 (outro): "Thank you for your continued trust and support."

Audio ads — with your script

I need a 30-second audio ad, English US, young adult female voice.
Script: "Tired of overpaying for insurance? Switch to SafeGuard and save up to 40%.
Visit safeguard.com or call 1-800-SAFE-NOW."

Audio ads — Bunny Studio writes the script

I need a 30-second radio ad for my coffee brand but I don't have a script yet.
Target audience: coffee lovers aged 25-45, US market.
Product: premium Colombian single-origin coffee. Goal: drive online sales.
Female voice, adult.

Test / sandbox (no billing)

Create a test voice over project in English, young male voice.
Script: "This is a test recording." Don't charge me.

Adding "test", "fake", "sandbox", or "don't charge me" sets fake: true.

Get / list / cancel project

Show me the details for project abc-123.

What's the status of project abc-123?

Show me my projects.

List all my voice over projects.

Cancel project abc-123. Reason: we decided to go a different direction.

Get quote (no project)

How much would a 30-second audio ad cost in English (US) with an adult female voice?
I'll provide the script myself.

Get me a price quote for a voice over: Language German, young male, about 200 words.

Search talents

The purpose filter is inferred from your description — you don't specify a number.

Find me a female voice for a voice over project in Italian.

Find a voice for a phone system IVR message in English US, female.

I need a talent for a movie trailer narration. Deep male voice, English.

Search for someone to narrate an e-learning course in Spanish (Latin America).

Find a voice for a 30-second radio commercial, upbeat female, English US.

Purpose ID reference (for advanced use; the AI infers these):

| Purpose ID | Category | Trigger keywords | |------------|----------|------------------| | 6 | Movie trailers | cinema, film, trailer | | 7 | Phone systems | IVR, hold message, voicemail, phone tree | | 9 | Product videos | product demo, explainer, how-to, tutorial | | 10 | Presentations / Educational | e-learning, training, course, webinar | | 11 | Commercials / Advertising | radio ad, TV ad, commercial, streaming ad | | 14 | Characters / Videogames | character voice, game, animation, cartoon | | 16 | Live announcements | event, conference, PA system, stadium | | 19 | Audiobooks / Podcasts | audiobook, podcast, narration, storytelling | | 20 | Radio/TV tags | station ID, bumper, intro, outro, jingle tag |

Deliverables

Show me deliverable xyz-456.

Show me the deliverables for project abc-123.

Approve deliverable xyz-456.

Approve all deliverables for project abc-123.

Reject deliverable xyz-456 — the voice doesn't match what we requested.
Use reason: wrong gender.

Request changes on deliverable xyz-456:
"The pronunciation of 'TechCorp' should be 'tek-corp'. Add a slight pause after the first sentence."

Deliverable xyz-456 is the winner for the contest. Select it.

Show me all versions of deliverable xyz-456.

Approval and selecting a winner are irreversible. The AI will confirm before proceeding.

Categories and attributes

What categories are available on Bunny Studio?

What attributes are available for voice over projects?

What languages are available for voice over?

What genderAndAge options are there for audio ads?

What voice over sub-categories are available?

What audio ads sub-categories are available?

Music / tracks

What types of music tracks are available?

Show me subtypes for track type "type-1".

Get details for track 34.

Browse available music tracks.

Show me the music library types.

Definitions (reference data)

What status types exist in Bunny Studio?

What are the possible project statuses?

What are the valid reasons for requesting a revision?

What are the valid reasons for canceling a project?

What are the valid reasons for rejecting a deliverable?

Tips for Better Results

• Script formatting — Single part: write naturally; the AI wraps it as one part. Multiple parts: number or label them (e.g. "Part 1: intro. Part 2: main body. Part 3: CTA.").
• Voice selection — Be specific: "young adult male" → youngAdultMale, "adult woman" → middleAgeFemale. Avoid vague requests like "nice voice"; use gender + age range.
• Language codes — The AI converts plain language to ISO codes: "English US" → eng-us, "British English" → eng-uk, "Italian" → ita-it, "German" → deu-de, "Spanish (Latin America)" → spa-mx, "French" → fra-fr, "Arabic" → ara, "Brazilian Portuguese" → por-br.
• Voice over vs audio ads — Voice over: narration, e-learning, podcast, IVR, YouTube (audio is the final product). Audio ad: broadcast commercial (radio, streaming, jingle) with post-production.
• Purpose (search) — You don't need to know purpose IDs. Describe the use case: "phone system" → 7, "e-learning course" → 10, "radio commercial" → 11; the AI infers the correct purpose.

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | BUNNY_API_TOKEN | JWT authentication token | (none) | | BUNNY_PUBLIC_API_URL | API base URL (e.g. for staging or local) | https://api.bunnystudio.com |

API Documentation

The server talks to https://api.bunnystudio.com. Refer to the official Bunny Studio API docs for detailed schemas:

• Authentication
• Projects
• Deliverables
• Revisions
• Categories
• Search
• Tracks

License

ISC © Bunny Studio