Skip to main content

MCP Server (Beta)

Welcome to the official documentation for the Epidemic Sound Model Context Protocol (MCP) Server (Beta). This guide is designed for developers and partners who want to integrate Epidemic Sound's extensive music, sound effects and voices catalog into their AI-powered applications for automated content creation. It outlines how to connect to our MCP server to discover audio assets (music, sound effects and voiceovers) and adapt tracks to specific styles or matching music to a specific video length.

Terms of Service​

The Terms of Service for using the Epidemic Sound MCP Server (Beta) are available here.

Overview​

What is the Epidemic Sound MCP Server (Beta)?​

The Epidemic Sound MCP Server (Beta) is a powerful tool that acts as a bridge between your AI applications and our vast catalog of high-quality music, sound effects, and voiceovers. By leveraging the open MCP standard, our ES MCP server allows AI agents to intelligently and dynamically search for, discover, and retrieve information about our audio assets in real-time. This enables you to build applications that can seamlessly find the perfect soundtrack for any context, whether for a video, a game, a podcast, or any other creative project.

The Epidemic Sound MCP server is designed to be developer-friendly, providing a simple and efficient way to interact with our platform and ensuring compatibility with a wide range of AI development environments and tools.

Getting Started​

Remote Server​

The Epidemic Sound MCP server is available at https://www.epidemicsound.com/a/mcp-service/mcp.

Epidemic Sound is also an official listing in Claude's Connector Directory, the shared catalog behind Claude.ai, Claude Desktop, Claude Mobile, Claude Code, and Claude Cowork — so it can be added with one click, with no manual configuration, from any of those surfaces.

Directory listing excludes voiceover creation

The directory listing exposes a subset of the tools listed below and does not include voiceover creation. To use the full set of tools, including voiceovers, connect to the server URL above directly instead of through the directory — see Connecting with AI Clients below.

Authentication & Setup​

The Epidemic Sound MCP server supports two authentication methods:

  1. OAuth Authentication - For AI clients like Cursor that support OAuth flows
  2. API Key Authentication - For programmatic access and custom integrations

Option 1: OAuth Authentication​

The Epidemic Sound MCP server uses OAuth Dynamic Client Registration to connect MCP clients as per the MCP spec. This method is used by AI clients like Cursor and provides a seamless authentication experience.

Connecting to the Epidemic Sound MCP Server uses an OAuth flow that links directly to your Epidemic Sound account. This ensures a secure and seamless integration. You must be logged into www.epidemicsound.com to authenticate.

Allowlist of client redirect URIs: Epidemic Sound maintains an allowlist of vetted MCP client redirect URIs to protect our users from malicious phishing attacks. If there's an MCP client application that you want to allowlist, email us at mcp@epidemicsound.com.

Option 2: API Key Authentication​

For programmatic access and building custom integrations, you can use API key authentication. The API key is tied to your Epidemic Sound account.

Obtaining Your API Key:

  1. Navigate to your Epidemic Sound account: https://www.epidemicsound.com/account/api-keys
  2. Generate or copy your API key from the API Keys page
  3. Store your API key securely - treat it like a password and never commit it to version control

Using Your API Key:

Keys are valid for one year from the date they are created, after which they must be regenerated.

Include your API key in the Authorization header of all HTTP requests to the MCP server:

Authorization: Bearer YOUR_API_KEY

Best Practice: Store your API key in environment variables rather than hardcoding it:

# Set environment variable
export EPIDEMIC_SOUND_API_KEY="your_api_key_here"
// Reference in your code
const apiKey = process.env.EPIDEMIC_SOUND_API_KEY

Connecting with AI Clients​

You can connect to the Epidemic Sound MCP Server from various AI-powered tools that support custom MCP integrations.

Claude​

Claude Desktop​

Claude Desktop connects over OAuth, so no API key is needed. Make sure you are logged in to www.epidemicsound.com first.

  1. Open Claude Desktop → Settings → Connectors
  2. Click Add custom connector
  3. Name it (e.g. Epidemic Sound) and paste the URL: https://www.epidemicsound.com/a/mcp-service/mcp
  4. Click Add. Claude opens a browser window to sign in
  5. Log in with your Epidemic Sound account and approve access

Claude Code​

OAuth is not yet supported in Claude Code

Use API key authentication instead. OAuth support for Claude Code is in progress.

If you've connected Epidemic Sound in Claude.ai through Claude's Connector Directory, that connector is automatically available in Claude Code too — but it's still the directory listing, so it won't include voiceover creation. Follow the steps below to register the full server directly and get the complete tool set.

  1. Generate a new MCP key under Account → API keys
  2. Expose it as an environment variable, so the key is never written to your Claude Code configuration:
export EPIDEMIC_SOUND_API_KEY="your_api_key_here"
  1. Register the server (-s user writes to ~/.claude.json):
claude mcp add -s user --transport http epidemic-sound https://www.epidemicsound.com/a/mcp-service/mcp \
  --header 'Authorization: Bearer ${EPIDEMIC_SOUND_API_KEY}'

Use single quotes so your shell leaves ${EPIDEMIC_SOUND_API_KEY} untouched — Claude Code expands it when it reads the configuration.

  1. Verify the connection:
claude mcp list

epidemic-sound should report ✔ Connected.

info

If it reports ✘ Failed to connect then EPIDEMIC_SOUND_API_KEY is most likely not set in the shell you launched Claude Code from, verify by making sure that the environment variable is exported and non-empty for your current shell.

To persist the environment variable across sessions, add the export line to your shell profile (e.g. ~/.zshrc).

Keys are valid for one year. To rotate, generate a new key on the same page and update EPIDEMIC_SOUND_API_KEY — no changes to your MCP configuration are needed.

If you would like to remove the MCP for any reason, you could use the command:

claude mcp remove epidemic-sound -s user

Cursor​

Cursor provides native support for custom MCP servers and supports both OAuth and API Key authentication methods.

  1. Open Settings: In Cursor, navigate to Settings > MCP.
  2. Click the New MCP server button. This will open a configuration file named mcp.json.
  3. Configure the Server: Add the following JSON configuration:
{
  "mcpServers": {
    "epidemic-sound": {
      "url": "https://www.epidemicsound.com/a/mcp-service/mcp"
    }
  }
}
  1. In the MCP settings tab, you will now see your newly configured server. Click the Connect button.
  2. Authorize Access: A browser tab will open, prompting you to login with your Epidemic Sound account.
  3. Start Querying: Once connected, the toggle next to the server name will be active. You can now begin making requests to the Epidemic Sound MCP server directly from Cursor prompts!

Using API Key Authentication (Alternative)​

Alternatively, you can use API Key authentication:

  1. Open Settings: In Cursor, navigate to Settings > MCP.
  2. Click the New MCP server button. This will open a configuration file named mcp.json.
  3. Configure the Server: Add the following JSON configuration:
{
  "mcpServers": {
    "epidemic-sound": {
      "url": "https://www.epidemicsound.com/a/mcp-service/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API key from https://www.epidemicsound.com/account/api-keys.

  1. In the MCP settings tab, you will now see your newly configured server. Click the Connect button.
  2. Start Querying: Once connected, the toggle next to the server name will be active. You can now begin making requests to the Epidemic Sound MCP server directly from Cursor prompts!

Core Capabilities for AI-driven Workflows​

Our MCP tools are designed to help AI agents and automated production flows intelligently discover, adapt, and integrate audio content into creative projects. The following capabilities enable seamless integration of music, sound effects, and voiceovers into your AI-powered applications.

Available Tools​

ResourceToolDescription
Music DiscoverySearchRecordingsSearches the music catalog by keyword or topic, with filters for BPM, mood, duration, instruments, key, and vocals, along with various sorting options.
SearchSimilarToRecordingDiscovers tracks with similar musical characteristics to a given Epidemic Sound trackID.
SearchExternalReferencesFinds external reference IDs (e.g., Spotify) that can be used to find Epidemic Sound tracks matching the style of external tracks.
Sound effectsSearchSoundEffectsQueries the sound effects catalog by search term, duration, and tags.
SearchSimilarToSoundEffectFinds variations and alternatives for a given sound effect ID.
Track AdaptationEditRecordingCreates one or more edited versions of a track adapted to a target duration.
PollEditRecordingJobChecks the status of a track-adaptation job and, once complete, returns the generated edit's ID and preview URL. May not be available on all connections (e.g. OAuth).
DownloadRecordingEditDownloads the high-quality audio file for a completed track edit.
VoiceoversListVoicesExplores available AI voices, including their voice characteristics and available languages.
ListUserGeneratedVoicesLists the voice replicas created using your own voice.
GenerateVoiceoverConverts a text script into an AI voiceover using a specified voice artist.
PollVoiceoverGenerationStatusChecks the generation status (e.g., DONE, GENERATING) of a voiceover job.
GetVoiceoverRetrieves complete metadata, audio URLs, and waveform data for a generated voiceover.
DownloadVoiceoverDownloads the high-quality audio file of a completed voiceover.
Asset DownloadsDownloadRecordingDownloads original music tracks in full or as individual stems (bass, drums, etc.).
DownloadSoundEffectDownloads original sound effect files in MP3 or WAV format.

Tool names above are the literal identifiers returned by the MCP server's tools/list and required for direct JSON-RPC calls.

The voiceover tools are not part of the Claude directory connector — see Remote Server above.

Music Discovery​

Find the perfect track for any creative project through intelligent search and similarity matching. Each tool below supports a range of filters, sorting, and pagination — the exact fields are defined in the tool's schema (returned by tools/list), which MCP clients resolve automatically from natural language, so they aren't repeated here.

Search Recordings (SearchRecordings)​

Search the catalog by keyword or topic, filtering by things like BPM, duration, mood, instruments, key, and vocal presence.

Example: An AI agent analyzing a fitness video script searches for "energetic workout music" with 120–140 BPM, filters out vocals, and sorts by popularity.

Find Similar Tracks (SearchSimilarToRecording)​

Given a recording ID from Epidemic Sound's catalog, returns tracks with similar musical characteristics.

Reference External Music (SearchExternalReferences)​

Finds external reference IDs (currently Spotify) for a search term. Feed the result into Search Recordings to find catalog tracks matching that style.

Workflow: Search for an external reference (e.g. "Taylor Swift") → take the returned Spotify track ID → pass it to Search Recordings as the externalID parameter.

Sound effects​

Enhance your content with the right audio atmosphere through our comprehensive sound effects library.

Search Sound Effects (SearchSoundEffects)​

Search the catalog by term (e.g. "door slam", "ocean waves"), filtering by duration and tags.

Find Similar Sound Effects (SearchSimilarToSoundEffect)​

Given a sound effect ID, returns variations and alternatives.

Track Adaptation (Beta)​

Transform any track to fit your exact content requirements with intelligent editing that preserves musical integrity.

Edit Recordings for Custom Lengths (EditRecording, beta)​

Adapts a track to a target duration (up to 300,000ms / 5 minutes) while preserving musical structure, builds, drops, and key moments. Notable options include forcing an exact duration, making the result loop seamlessly, and pinning specific sections to exact timestamps in the output (requiredRegionsAtOffsets).

note

maxResults requests multiple edit variations per job, but currently only one edit is retrievable via PollEditRecordingJob regardless of this value.

Workflow:

  1. Select a track using Search Recordings
  2. Call EditRecording with the recording ID and target duration
  3. Poll with PollEditRecordingJob until status is COMPLETED (or FAILED) — not available on all connections (e.g. OAuth)
  4. Download the result with DownloadRecordingEdit, using the job ID and the edit ID returned by the poll call

Example: An AI agent needs a 47-second track for a product video, with the energetic chorus landing at the 15-second mark (using requiredRegionsAtOffsets).

Download Edited Tracks (DownloadRecordingEdit)​

Returns a direct download URL for a completed edit, given its job ID and edit ID.

Note: Unlike original track downloads, edited tracks are only available as a single full mix — individual stems aren't currently downloadable for edits, regardless of the skipStems setting used when creating the edit.

Voiceover Creation​

Generate professional AI voiceovers with natural-sounding voice artists from our library.

Browse Voice Artists (ListVoices)​

Lists available AI voices with their characteristics (gender, location, biography) and supported languages.

List User-Generated Voices (ListUserGeneratedVoices)​

Lists custom voice replicas you've created.

Generate Voiceovers (GenerateVoiceover)​

Converts a text script into narration using a chosen voice, with an optional language code (IETF BCP 47, e.g. en-US) and speed adjustment.

Check Voiceover Status (PollVoiceoverGenerationStatus)​

Given a voiceover ID, returns its generation status (DONE, GENERATING, or FAILED) and a failure reason if applicable.

Get Voiceover Details (GetVoiceover)​

Given a voiceover ID, returns full metadata — playback URL, duration, and waveform — once generation is done.

Download Voiceover (DownloadVoiceover)​

Returns a direct download URL for a completed voiceover.

Example workflow: An AI agent creating localized video ads generates voiceovers in English, Spanish, and French simultaneously, polls their generation status, and downloads the completed files for each language.

Asset Downloads​

All discovered and generated assets can be downloaded in production-ready formats (MP3 or WAV).

Download Music Tracks (DownloadRecording)​

Downloads a track in full or as an individual stem (BASS, DRUMS, INSTRUMENTS), with an option to bundle multiple stems together.

Download Sound Effects (DownloadSoundEffect)​

Downloads a sound effect file, with an option to bundle multiple files together.

Reach out to us​

Do you have questions or feedback on the Epidemic Sound MCP Server (Beta)? Email us at mcp@epidemicsound.com or join our Discord server.