Claude DJ MCP

An MCP server that lets Claude act as an autonomous radio DJ using Strudel live-coded music.

Features

• 🎵 Live-coded music — Claude generates Strudel patterns in real-time
• 🎙️ DJ announcements — Text-to-speech commentary (macOS)
• 🎚️ Dynamic tempo control — Adjust BPM mid-session
• 📻 Audience requests — Take song/vibe requests from browser UI
• 🔄 Autonomous DJ loop — Play → announce → wait → adapt → repeat

Security Notice

⚠️ This project is designed for local development and personal use only.

Important security considerations:

• Local use only — The HTTP server binds to localhost but has open CORS headers (Access-Control-Allow-Origin: *)
• Code execution — Claude sends arbitrary Strudel code that is evaluated in the browser without sandboxing
• Command execution — The dj_speak tool executes shell commands (macOS say) with user-controlled input
• No authentication — Anyone with access to localhost can interact with active sessions
• No rate limiting — Request queue and endpoints are not protected against abuse

Recommendations:

• Only run on trusted machines with trusted Claude instances
• Do not expose the HTTP server to network interfaces beyond localhost
• Do not run in multi-user environments without additional security hardening
• Review the code before use if you have security concerns

Architecture

Claude (MCP client)
  │ stdio (JSON-RPC)
  ▼
MCP Server (Node.js)
  │ In-memory state: pendingCode, pendingAction, browserState, requestQueue
  │
  ├─ HTTP Server (port 6002, auto-increment if busy)
  │   GET /              → HTML page with <strudel-editor> + request bar
  │   GET /api/poll      → Browser polls: returns pending code/action
  │   POST /api/state    → Browser posts: started, activeCode, error, cps
  │   POST /api/request  → User submits song/vibe request from browser UI
  │   GET /api/health    → Health check
  │
  └─ Browser (opened via `open` package)
      <strudel-editor> web component (loaded from unpkg CDN)
      Polls /api/poll every 1s, executes pending actions
      Posts state back via /api/state after each action
      Request bar at bottom for user input

Installation

1. Build the MCP server

npm install
npm run build

2. Configure in Claude Code / Claude Desktop

Add to your MCP settings (e.g., ~/.config/claude-code/mcp.json):

{
  "mcpServers": {
    "claude-dj": {
      "command": "node",
      "args": ["~/claude-dj-mcp/dist/index.js"]
    }
  }
}

Usage

Quick start

In Claude Code or Claude Desktop:

Use the claude-dj skill to start a DJ session

Or call tools directly:

Call start_session, then tell me when audio is ready

The DJ Loop

Once the session is started and audio is active:

1. Claude plays a pattern — Calls play_pattern with Strudel code
2. Claude announces — Calls dj_speak with DJ commentary
3. Claude waits — Calls wait(30-90) to let the music play
4. Claude checks requests — The wait tool returns any pending audience requests
5. Claude adapts — Creates the next pattern based on requests, mood, flow
6. Repeat

Audience requests

Users can type requests in the browser UI:

• "something funky"
• "chill lo-fi beats"
• "90s techno"
• "more cowbell"

Claude will acknowledge and incorporate requests into the next patterns.

MCP Tools (9 total)

Tool	Description
start_session	Starts HTTP server and opens browser with Strudel REPL
play_pattern	Sends Strudel code to browser for evaluation
stop_music	Stops the current pattern
get_session_state	Returns browser state (started, activeCode, error, cps)
set_tempo	Sets BPM or CPS
dj_speak	macOS text-to-speech announcement (fire-and-forget)
check_requests	Drains user request queue from browser UI
wait	Blocks N seconds, then returns pending requests (core DJ loop tool)
get_available_sounds	Returns curated sound list by category

Strudel Examples

Basic beat

s("bd sd:1 hh sd:2").gain(0.8)

Layered pattern

stack(
  s("bd:1 ~ bd:1 ~").gain(0.9),
  s("~ sd ~ sd:3").gain(0.7),
  s("hh*8").gain(0.4),
  note("c2 ~ e2 ~ g2 ~ e2 ~").sound("bass1").gain(0.6)
)

Lo-fi chill

stack(
  s("bd ~ [~ bd] ~, ~ sd ~ sd").gain(0.7),
  note("<c3 e3 g3 b3>/4").sound("piano").room(0.7).gain(0.3),
  s("hh*4").gain(0.2).pan(sine)
).lpf(2000)

Techno

stack(
  s("bd*4").gain(0.9),
  s("~ hh:2 ~ hh:3").gain(0.5),
  s("~ ~ cp ~").room(0.5).gain(0.6),
  note("c2 c2 [c2 c3] c2").sound("sawtooth").lpf(400).gain(0.5)
)

Available Sounds

• Drums: bd, sd, hh, oh, cp, rm, cb, lt, mt, ht, cr, rd, perc, tabla
• Synths: sine, square, sawtooth, triangle, supersaw, supersquare
• Instruments: piano, bass1, bass2, gtr, flute, jazz, metal, east, pluck, casio
• Effects: .lpf() .hpf() .delay() .room() .gain() .pan() .crush() .vowel() .phaser() .speed()

Use get_available_sounds tool for the full categorized list with examples.

Mini-Notation Reference

• *N — repeat N times per cycle
• /N — spread over N cycles (slow down)
• ~ — rest / silence
• <a b c> — alternate each cycle
• [a b] — group into one step
• ? — random chance of playing
• , — play in parallel

Development

# Install dependencies
npm install

# Development mode (with hot reload)
npm run dev

# Build
npm run build

# Run manually (stdio mode)
node dist/index.js

File Structure

claude-dj-mcp/
├── src/
│   ├── index.ts          # MCP server entry: tool registrations, main()
│   ├── http-server.ts    # HTTP server, state stores, endpoints
│   ├── html-page.ts      # HTML template with Strudel REPL
│   ├── logger.ts         # stderr-only logger
│   ├── prompts.ts        # MCP prompt for DJ workflow
│   └── sounds.ts         # Curated Strudel sound list
├── claude-dj/
│   └── SKILL.md          # Agent skill definition
├── package.json
├── tsconfig.json
└── README.md

Agent Skills Support

This project includes an Agent Skills definition at claude-dj/SKILL.md. Compatible agents can discover and use the claude-dj skill automatically.

License

AGPL-3.0

Credits

• Strudel — The live coding environment for algorithmic patterns
• Built with @modelcontextprotocol/sdk