beatport-mcp

An MCP (Model Context Protocol) server that lets Claude search the Beatport catalog and manage your Beatport playlists. Hand Claude a list of track names and say "add these to my Sunset Set playlist" — it resolves each one to a Beatport track and writes them to the playlist for you.

Beatport has no obtainable official API access, so this server uses the same auth workaround as the beets-beatport4 plugin: it borrows the public client_id from Beatport's own /v4/docs/ page and runs a cookie-session authorization_code OAuth flow against your own account.

Disclaimer: This is an unsanctioned workaround in a ToS grey area. Use it for personal, non-commercial purposes on your own account only. It can break without notice whenever Beatport changes their docs page or API.

Use cases

• Tracklist → playlist. Paste a tracklist from 1001Tracklists, a radio show, a festival set, or a screenshot, and have Claude rebuild it as a Beatport playlist ready to buy from.
• Migrate playlists from other platforms. Export a Spotify/Apple Music playlist (or a rekordbox collection) as text and let Claude re-match every track on Beatport.
• Set prep with BPM/key data. Search results include BPM and musical key, so you can ask for things like "find these tracks and add the ones between 122–126 BPM, prefer extended mixes" — useful for harmonic mixing prep.
• Digging assistant. "Search Beatport for the new remixes of X and stage anything interesting in my 'To Review' playlist" — Claude searches, filters, and files them.
• Crate building by brief. Describe a vibe ("peak-time melodic techno, 128–132"), let Claude propose tracks it knows, verify each exists on Beatport, and build the playlist in one conversation.

Tools

Tool	Description
whoami	Returns the authenticated account. Auth smoke test.
search_tracks	Search the catalog. Returns id, title, mix, artists, BPM, key, release per match.
list_playlists	List all your playlists (id, name, track count, visibility).
create_playlist	Create a playlist by name.
add_tracks_to_playlist	Batch-add tracks (by id) to a playlist (by id).

Tools are deliberately atomic — the "list of songs → playlist" orchestration happens in the model at runtime: it searches each line, picks the best match, then makes one add call.

Requirements

• Bun ≥ 1.0 (curl -fsSL https://bun.sh/install | bash)
• A Beatport account (username + password)
• Claude Code or Claude Desktop (or any other MCP client)

Install

git clone https://github.com/BadWasabeee/beatport-mcp.git
cd beatport-mcp
bun install
cp .env.example .env   # then edit .env with your Beatport credentials

.env lives in the project root and is read by the server itself, so your credentials never need to appear in any MCP client config:

BEATPORT_USERNAME=you@example.com
BEATPORT_PASSWORD=your-password

Verify it works

bun run smoke "Bicep Glue"

Expected output: your account name, then five candidate tracks with BPM and key. This exercises the full auth flow plus catalog search.

Register with Claude

Claude Code:

claude mcp add --scope user beatport -- bun run /ABSOLUTE/PATH/TO/beatport-mcp/src/index.ts

Claude Desktop — add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "beatport": {
      "command": "/ABSOLUTE/PATH/TO/bun",
      "args": ["run", "/ABSOLUTE/PATH/TO/beatport-mcp/src/index.ts"]
    }
  }
}

Use the absolute path to bun (which bun) — Claude Desktop doesn't inherit your shell's PATH. Fully quit and relaunch Claude Desktop afterwards, then start a new conversation.

Local MCP servers only work in clients running on the same machine (Claude Code, Claude Desktop). They are not reachable from claude.ai in a web browser or the mobile apps.

Usage

In a fresh Claude session:

Add these to my Sunset Set playlist: Bicep — Glue, Charlotte de Witte — Doppler, Overmono — So U Kno

Claude will search each track, pick the best match (asking you when it's ambiguous), and batch-add them. If the playlist doesn't exist, ask it to create one first.

How auth works

1. Scrapes the public client_id from the script bundles on api.beatport.com/v4/docs/ (override with BEATPORT_CLIENT_ID if the scrape breaks).
2. POST /auth/login/ with your credentials establishes a cookie session.
3. GET /auth/o/authorize/ with those cookies yields an authorization code.
4. POST /auth/o/token/ exchanges the code for access + refresh tokens.

Tokens persist to ~/.beatport-mcp/token.json (chmod 600, override the path with BEATPORT_TOKEN_PATH) and refresh automatically on expiry, falling back to a full re-login if the refresh is rejected. Credentials and tokens are never logged.

Troubleshooting

• "BEATPORT_USERNAME and BEATPORT_PASSWORD must be set" — no .env in the project root and no env vars passed by the MCP client.
• "Beatport login failed (HTTP 4xx)" — wrong credentials, or Beatport is challenging the login (try logging into the website once, then retry).
• "API_CLIENT_ID not found in any /docs/ script bundle" — Beatport changed their docs page. Find the new client id (DevTools → Network on the docs page) and set BEATPORT_CLIENT_ID in .env.
• Stale auth weirdness — delete ~/.beatport-mcp/token.json; the next call re-runs the full flow.

Development

bun run start        # start the stdio MCP server
bun run smoke [q]    # auth smoke test + optional catalog search
bunx tsc --noEmit    # typecheck

• src/auth.ts — OAuth flow, token persistence/refresh
• src/client.ts — Beatport API client (search, playlists)
• src/index.ts — MCP server and tool definitions
• src/smoke.ts — standalone CLI check, no MCP client needed

License

MIT