🌀 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

📋 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!