🌀 TidalCycles MCP Server

Conversational live coding with Claude AI + TidalCycles

This MCP (Model Context Protocol) server enables Claude to control TidalCycles through natural conversation, creating a powerful AI-assisted live coding experience for algorithmic music composition.

✨ Features

• 🎵 Evaluate TidalCycles patterns through conversational AI

• 📊 State awareness - Claude knows what's currently playing

• 🕰️ Pattern history - Track and recall previous patterns

• 🎛️ Channel management - Solo, silence, or hush specific channels

• 💬 Natural conversation - Talk to Claude about your music in plain English

• 🔄 Real-time feedback - Immediate pattern evaluation

• 🚀 Dual transport modes: stdio for Claude Desktop + WebSocket for external clients

• 🌐 Network accessible - Web UIs and remote clients can connect via WebSocket

• 🔄 Auto-recovery - Robust GHCi process management with automatic reconnection

Related MCP server: Ableton MCP

📋 Prerequisites

Before installing, ensure you have:

1. TidalCycles - Install from tidalcycles.org

   • Includes GHCi (Glasgow Haskell Compiler Interactive)

   • Haskell Stack or Cabal

2. SuperCollider + SuperDirt - Required for audio output

   • Download from supercollider.github.io

   • Install SuperDirt: In SuperCollider, run Quarks.install("SuperDirt")

   • Install samples: Quarks.install("Dirt-Samples")

3. Claude Desktop - Get from claude.ai

4. Node.js 18+ - For running the MCP server

   • Download from nodejs.org

   • Verify: node --version

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/yourusername/tidal-mcp-server.git
cd tidal-mcp-server

# Install dependencies
npm install

# Build the server
npm run build

2. Start SuperCollider

Open SuperCollider and run:

// Start SuperDirt
SuperDirt.start;

// Verify it's listening
// Should see: "SuperDirt: listening to Tidal on port 57120"

3. Configure Claude Desktop

Add this to your Claude Desktop configuration file:

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

File-based Mode (Recommended for stability):

{
  "mcpServers": {
    "tidal": {
      "command": "node",
      "args": [
        "/absolute/path/to/tidal-mcp-server/dist/index.js"
      ],
      "env": {
        "TIDAL_FILE": "/absolute/path/to/tidal-mcp-server/tidal-mcp-output.tidal"
      }
    }
  }
}

Direct GHCi Mode (Experimental - no restarts):

{
  "mcpServers": {
    "tidal": {
      "command": "node",
      "args": [
        "/absolute/path/to/tidal-mcp-server/dist/index.js"
      ],
      "env": {
        "TIDAL_FILE": "/absolute/path/to/tidal-mcp-server/tidal-mcp-output.tidal",
        "TIDAL_USE_GHCI": "true",
        "TIDAL_BOOT_PATH": "/absolute/path/to/tidal-mcp-server/BootTidal.hs",
        "GHCI_PATH": "/usr/local/bin/ghci"
      }
    }
  }
}

Finding your ghci path:

which ghci
# Use this path for GHCI_PATH

Replace /absolute/path/to/ with the actual path to your installation.

4. File Watching Setup (File-based mode only)

For file-based mode, you need to watch the output file and evaluate it in TidalCycles:

Option A: Using watchexec (recommended)

# Install watchexec
brew install watchexec  # macOS
# or
cargo install watchexec-cli  # Any OS with Rust

# Watch and auto-reload patterns
cd /path/to/tidal-mcp-server
watchexec --restart -w tidal-mcp-output.tidal \
  "ghci -ghci-script BootTidal.hs -ghci-script tidal-mcp-output.tidal"

Option B: Using your editor

Open tidal-mcp-output.tidal in your preferred editor with TidalCycles support and manually evaluate patterns when Claude writes them.

5. Start Using

1. Restart Claude Desktop to load the MCP server

2. Start a new conversation

3. Make music!

You: Create a funky drum pattern

Claude: [calls tidal_eval]
       I'll create a syncopated funk groove:
       d1 $ sound "bd ~ bd ~ bd ~ ~ ~"

You: Add a bassline

Claude: [calls tidal_eval on d2]
       Added a groovy bassline:
       d2 $ sound "bass2*8" # n "0 3 5 7"

🎹 Usage Examples

Basic Patterns

You: Play a simple drum beat
You: Make it faster
You: Add some hi-hats
You: What's playing right now?

Advanced Composition

You: Create a glitchy breakbeat with euclidean rhythms
You: Add a wobbling bassline with filter sweeps
You: Layer some atmospheric pads over the top
You: Make the whole thing more sparse

Live Performance

You: Solo channel d2
You: Bring back everything
You: Hush
You: Show me the last 5 patterns I evaluated

🛠️ Available Tools

The MCP server exposes these tools to Claude:

tidal_eval

Evaluate a TidalCycles pattern on a specific channel (d1-d9).

Parameters:

• channel: String (d1-d9)

• pattern: String (TidalCycles code without the d1 $ prefix)

Example:

{
  "channel": "d1",
  "pattern": "sound \"bd sd bd sd\" # gain \"1.2\""
}

tidal_hush

Stop all currently playing patterns immediately.

tidal_silence

Stop a specific channel gracefully.

Parameters:

• channel: String (d1-d9)

tidal_get_state

Get current state of all channels - what's playing and when it started.

tidal_solo

Solo a specific channel, muting all others.

Parameters:

• channel: String (d1-d9)

tidal_unsolo

Restore all channels after soloing.

tidal_get_history

Get pattern history from the current session.

Parameters:

• limit: Number (optional, default: 10)

📁 Project Structure

tidal-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server implementation
│   └── websocket-transport.ts # WebSocket transport layer
├── dist/                     # Compiled JavaScript output
├── BootTidal.hs             # TidalCycles initialization
├── tidal-mcp-output.tidal   # Generated pattern output file
├── start-websocket.sh       # WebSocket server startup script
├── test-websocket-client.js # WebSocket connection test
├── examples.tidal            # Example patterns
├── WEBSOCKET-USAGE.md       # WebSocket setup and usage guide
├── package.json             # Node.js dependencies
├── tsconfig.json            # TypeScript configuration
├── README.md                # This file
├── QUICKSTART.md            # Quick reference guide
├── CONTRIBUTING.md          # Contribution guidelines
└── LICENSE                  # MIT License

🎨 Use Cases

Live Performance

• Generate patterns on the fly during algoraves

• Quick iterations and experimentation

• Emergency pattern generation when stuck

• AI-assisted improvisation

Learning & Exploration

• Ask Claude to explain TidalCycles concepts

• Generate example patterns for specific techniques

• Explore new rhythmic and harmonic ideas

• Learn by conversation

Composition

• Rapid prototyping of musical ideas

• Generate pattern variations

• Collaborative composition with AI

• Build complex layered arrangements

🔧 Architecture

┌─────────┐         ┌──────────────┐         ┌──────────────┐
│ Claude  │ ◄─MCP─► │  MCP Server  │ ◄─────► │ TidalCycles  │
│   AI    │         │  (Node.js)   │         │    (GHCi)    │
└─────────┘         └──────────────┘         └──────────────┘
                            │                         │
                            │ (File mode)             │
                            ▼                         ▼
                    ┌──────────────┐         ┌──────────────┐
                    │ .tidal file  │         │ SuperCollider│
                    │   (watch)    │         │  SuperDirt   │
                    └──────────────┘         └──────────────┘

Flow:

1. You talk to Claude in natural language

2. Claude uses MCP tools to generate Tidal code

3. MCP server either:

   • File mode: Writes code to .tidal file → File watcher evaluates it

   • Direct mode: Sends directly to running GHCi process

4. TidalCycles/GHCi sends OSC messages to SuperDirt

5. SuperCollider/SuperDirt plays the audio

🐛 Troubleshooting

"MCP server not connecting"

• Check the path in claude_desktop_config.json is absolute

• Restart Claude Desktop after config changes

• Check Node.js version: node --version (need 18+)

• Check MCP server logs in Claude Desktop

"Patterns not playing" (File mode)

• Ensure SuperCollider is running: SuperDirt.start

• Verify file watcher (watchexec) is running

• Check the TIDAL_FILE path is correct

• Try manually evaluating the file in your editor

"Patterns not playing" (Direct GHCi mode)

• Check ghci is in PATH: which ghci

• Verify GHCI_PATH in config matches which ghci

• Check MCP server logs for "GHCi/TidalCycles started and connected"

• Ensure only one GHCi instance is running

"spawn ghci ENOENT"

• GHCi not found in PATH

• Set GHCI_PATH environment variable with full path

• On macOS with ghcup: usually /Users/username/.ghcup/bin/ghci

"No samples found" / Empty sound library

• Install Dirt-Samples in SuperCollider:

  Quarks.install("Dirt-Samples");
  // Recompile (Cmd+K)
  SuperDirt.start;

• Verify: ~dirt.soundLibrary.buffers.keys.do({|x| x.postln});

"Late" messages in SuperCollider

• Normal at fast tempos (jungle/DnB)

• If severe (>1 second), restart SuperDirt

• Check system audio settings

• Reduce pattern complexity

Music continues after stopping MCP server

• Patterns run in SuperCollider, independent of MCP server

• Stop in SuperCollider: s.freeAll;

• Or in any GHCi/Tidal session: hush

• Kill all ghci processes: pkill -9 ghci

🚧 Known Limitations

• File mode: Restarts GHCi on every change (causes brief audio dropout)

• Direct GHCi mode: Experimental, may have edge cases

• No visual feedback: Pattern changes aren't visible in editor (file mode)

• Single instance: Can't run multiple MCP servers simultaneously

• No undo: Pattern changes are immediate and can't be undone

🗺️ Roadmap

✅ Completed Features

• Direct GHCi integration - Real-time pattern evaluation without file watching

• WebSocket transport - Network-accessible server for web UIs and collaboration

• Robust error handling - GHCi process recovery and connection monitoring

• Session logging - Complete pattern history with timestamps

🚀 Next Up (Priority Features)

• MIDI Controller Input - Physical knobs/faders control Tidal parameters

  • MIDI learn mode for easy mapping

  • Support for popular controllers (Push, Launchpad, etc.)

  • Macro controls for complex parameter automation

• Pattern Version Control - Git-like history for your patterns

  • Undo/redo system with branching

  • Save/restore snapshots

  • Compare pattern versions

• Browser-based UI - Real-time pattern visualization

  • Live waveform display

  • Channel timeline view

  • WebSocket integration for multiple UIs

🌟 Advanced Features

• Real-time Audio Analysis - AI gets audio feedback

  • Frequency analysis to inform pattern choices

  • Beat detection for tempo sync

  • Amplitude monitoring for mix balance

• AI Pattern Suggestions - Context-aware recommendations

  • ML-based pattern generation

  • Style-specific suggestions (techno, ambient, breaks)

  • Automatic complementary pattern creation

• Multi-user Collaboration - Live coding sessions

  • Multiple users control different channels

  • Turn-based jamming modes

  • Shared pattern library

🎨 Creative Integrations

• Hydra Visual Integration - Reactive visuals

  • Auto-generate visuals from audio patterns

  • Synchronized visual effects with beat events

  • Live visual coding alongside audio

• DAW Integration - Professional workflow

  • MIDI output to hardware synths

  • Audio recording of Tidal sessions

  • Timeline sync with Ableton Live/Logic

• AI Composition Tools - Advanced creativity

  • Generate full track structures

  • Style transfer between genres

  • Harmony analysis and suggestions

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick start for contributors:

# Clone and setup
git clone https://github.com/yourusername/tidal-mcp-server.git
cd tidal-mcp-server
npm install

# Development mode (with auto-rebuild)
npm run dev

# Run tests
npm test

# Build for production
npm run build

📚 Resources

• TidalCycles Documentation

• Model Context Protocol

• SuperCollider Documentation

• Algorave Community

• TOPLAP - Live Coding

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Alex McLean (yaxu) for creating TidalCycles

• The TOPLAP and algorave communities for live coding culture

• Anthropic for the Model Context Protocol and Claude

• Everyone who live codes and makes weird music with computers

📞 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• TidalCycles Community: Discord

Made with 🌀 for the live coding community

Go forth and make some algorithmic noise!