strudel-mcp-bridge by phildougherty - MCP Server

Strudel MCP Server

Bridge Claude Code and Claude Desktop to Strudel, the browser-based live coding music environment.

What is This?

This MCP server lets Claude AI assistants generate and play live-coded music directly in your browser using Strudel's powerful pattern language. Just describe what you want, and Claude will create the code and play it instantly.

Quick Start

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Install the MCP server:

claude mcp add strudel node /path/to/strudel-mcp-bridge/mcp-server/dist/server.js -s user

4. Open strudel.cc in your browser and install the browser extension

5. Ask Claude to make music!

"Create a dark synthwave beat with heavy bass"
"Add UK garage drums"
"Make it faster and add reverb"

Architecture

User → Claude (generates Strudel code) → MCP Server (bridge) → Browser → 🎵

Key Design: This is a simple bridge. Claude generates the Strudel code, the server just forwards it to your browser.

Features

✅ No AI dependencies - Claude generates the code itself
✅ No API keys required - Zero configuration
✅ Real-time - Instant music playback
✅ Comprehensive docs - Embedded Strudel API reference
✅ Fast & lightweight - 336 lines of code
✅ Works everywhere - Claude Code, Claude Desktop, any MCP client

Installation

For Development / Local Use

# Clone and install
git clone <repo-url>
cd mcp-server
npm install
npm run build
npm start

For Claude Desktop

1. Build the server:

cd /path/to/strudel-mcp-bridge/mcp-server
npm install
npm run build

2. Add to Claude Desktop config:

Open your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "strudel": {
      "command": "node",
      "args": ["/absolute/path/to/strudel-mcp-bridge/mcp-server/dist/server.js"]
    }
  }
}

3. Restart Claude Desktop

For Browser Extension

1. Install the extension:

Open Chrome/Edge and navigate to chrome://extensions/
Enable "Developer mode" in the top-right corner
Click "Load unpacked"
Select the browser-extension folder from this project
The extension should appear in your extensions list

2. Connect to strudel.cc:

Open strudel.cc in your browser
The extension will automatically connect to the MCP server
Look for a connection indicator (should turn green when connected)

3. Start making music!

"Create a jazzy beat with piano and brushed drums"
"Make a dark techno track with 808 drums"
"Add UK garage drums to this"

Usage

How It Works

You ask Claude to create music (e.g., "make a techno beat")
Claude reads the Strudel API reference (via MCP Resources)
Claude generates valid Strudel code
MCP server forwards the code to your browser via WebSocket
Browser plays the music through Strudel

Browser Extension

The browser extension bridges the MCP server to strudel.cc:

Connects to WebSocket server at ws://localhost:3001
Injects code execution capabilities into Strudel
Provides visual connection status indicator
See installation instructions in the "Installation" section above

Example Session

You: "Create a house beat with 808 drums"
Claude: [reads strudel://reference resource]
Claude: [generates Strudel code]
Claude: [calls execute_pattern]
Browser: 🎵 Music plays!

You: "Add a deep bass line"
Claude: [modifies the code]
Claude: [calls execute_pattern]
Browser: 🎵 Updated music plays!

MCP Resources

strudel://reference

The complete Strudel API reference is exposed as an MCP Resource. This allows Claude Code and Claude Desktop to automatically access the documentation without needing file system access.

Resource Details:

URI: strudel://reference
Name: Strudel API Reference
MIME Type: text/markdown
Description: Complete Strudel live coding API reference with syntax, sounds, effects, and examples

Usage: MCP clients can fetch this resource at session start to provide the LLM with complete Strudel API knowledge. The documentation is embedded directly in the compiled server, making it fully portable even when installed via npm globally.

How to Fetch:

{
  "method": "resources/read",
  "params": {
    "uri": "strudel://reference"
  }
}

The resource returns the complete markdown documentation including:

Mini-notation syntax and operators
300+ sound sources (drums, synths, GM instruments, samples)
70+ audio effects with parameters
Pattern structure and factories
Time modifiers and transformations
Style templates with examples
Critical rules and best practices

MCP Tools

execute_pattern

Execute raw Strudel code in the connected browser.

Parameters:

code (string): Raw Strudel code to execute

Example:

execute_pattern({
  code: `setcps(0.5)
stack(
  s("bd*4, ~ sd ~ sd, hh*8").bank("tr808"),
  note("c2*8").s("sawtooth").lpf(300)
)`
});

stop_pattern

Stop all currently playing patterns.

Parameters: None

get_connection_status

Check if browser is connected and ready.

Parameters: None

Returns: Connection status information

Project Structure

strudel-mcp-bridge/
├── mcp-server/                # MCP server (bridge to browser)
│   ├── src/
│   │   ├── server.ts          # Main MCP server
│   │   └── websocket/
│   │       └── bridge-server.ts  # WebSocket communication
│   ├── STRUDEL_REFERENCE.md   # Strudel API docs (embedded in server)
│   ├── MIGRATION_GUIDE.md     # v1.0 → v2.0 migration guide
│   └── package.json
├── browser-extension/         # Chrome extension (connects strudel.cc)
│   ├── manifest.json
│   ├── content-script.js
│   ├── background.js
│   └── popup.html
└── README.md                  # This file

Why This Architecture?

Simple Bridge = Reliable:

Claude generates the code (it's good at this!)
Server just forwards it (keeps it simple)
No double-AI translation issues
No API keys or configuration needed

Previous version had AI-in-server which caused:

Double AI calls (slow, expensive)
Pattern complexity loss in translation
API key requirements
1600+ lines of fragile validation code

Current version: Direct execution = Fast, reliable, simple.

See MIGRATION_GUIDE.md if upgrading from v1.0.

Development

MCP Server Development

cd mcp-server

# Install dependencies
npm install

# Build
npm run build

# Development mode with watch
npm run dev

# Clean build
rm -rf dist
npm run build

Browser Extension Development

cd browser-extension

# No build step needed - just load the extension in Chrome:
# 1. Open chrome://extensions/
# 2. Enable "Developer mode"
# 3. Click "Load unpacked"
# 4. Select the browser-extension folder

Testing the Full Stack

Start MCP server (via Claude Desktop or manually)
Install browser extension (developer mode)
Open strudel.cc
Check connection status (indicator should be green)
Ask Claude to create music
Verify pattern plays in browser

Strudel Reference

The complete Strudel API documentation is available in two ways:

MCP Resource (Recommended): Access via strudel://reference resource - no file system access needed
File: Read STRUDEL_REFERENCE.md if you have file system access

The documentation includes:

Mini-notation syntax
300+ sound sources (drums, synths, instruments, samples)
70+ audio effects
Pattern factories and time modifiers
Style templates and examples
Critical rules and best practices

Troubleshooting

No Browser Connected

Symptoms: execute_pattern returns "No browser connected"

Solutions:

Open strudel.cc in your browser
Install the browser extension
Check that WebSocket server is running on port 3001
Use get_connection_status to verify

Invalid Strudel Code

Symptoms: Pattern doesn't play or errors in browser

Solutions:

Ensure code starts with setcps(NUMBER)
Check all sound names are valid (see STRUDEL_REFERENCE.md)
Validate mini-notation syntax
Check for balanced brackets and quotes

Build Errors

Solutions:

rm -rf node_modules package-lock.json
npm install
npm run build

Architecture Details

WebSocket Protocol

Server → Browser:

{
  "type": "execute_code",
  "code": "setcps(0.5)\\nstack(...)"
}

{
  "type": "stop_all"
}

Browser → Server:

{
  "type": "execution_result",
  "data": { "success": true }
}

{
  "type": "browser_ready"
}

MCP Protocol

Standard MCP protocol via stdio:

tools/list - List available tools
tools/call - Execute a tool

Contributing

Keep It Simple! This server should remain a simple bridge.

Do NOT add:

❌ AI generation logic (Claude does this)
❌ Pattern validation (adds complexity)
❌ Code transformation (fragile)
❌ API dependencies (increases setup friction)

Do add:

✅ Better WebSocket reliability
✅ Improved error messages
✅ Additional MCP resources (if useful)
✅ Documentation improvements

Philosophy: The intelligence is in Claude, not in this server.

FAQ

Q: Do I need an API key? A: No! Zero configuration required.

Q: Can I use this with other LLMs besides Claude? A: Yes! Any MCP-compatible AI can use this server. They'll need to read the strudel://reference resource and generate valid Strudel code.

Q: Does this work offline? A: The MCP server works offline, but you need internet to access strudel.cc in your browser.

Q: Can I use a different port? A: Currently hardcoded to 3001. Open an issue if you need this configurable.

Q: Does the browser extension work with Firefox/Safari? A: Currently Chrome/Edge only (Manifest V3). Firefox support planned.

Q: Can I publish patterns to share with others? A: Yes! Strudel has built-in sharing features. The patterns are just Strudel code.

Q: What if I want to use a different live coding environment? A: The architecture is extensible - you could create a bridge to other environments like TidalCycles, Sonic Pi, etc.

License

MIT

Credits

Strudel - Alex McLean, Felix Roos, and contributors
MCP - Anthropic
Built with ❤️ for live coding music

phildougherty/strudel-mcp-bridge

Strudel MCP Server

What is This?

Quick Start

Architecture

Features

Installation

For Development / Local Use

For Claude Desktop

For Browser Extension

Usage

How It Works

Browser Extension

Example Session

MCP Resources

strudel://reference

MCP Tools

execute_pattern

stop_pattern

get_connection_status

Project Structure

Why This Architecture?

Development

MCP Server Development

Browser Extension Development

Testing the Full Stack

Strudel Reference

Troubleshooting

No Browser Connected

Invalid Strudel Code

Build Errors

Architecture Details

WebSocket Protocol

MCP Protocol

Contributing

FAQ

License

Credits