tidal-cycles-mcp-server

Benedict/tidal-cycles-mcp-server

3.3

If you are the rightful owner of tidal-cycles-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The TidalCycles MCP Server enables conversational live coding with Claude AI, allowing for AI-assisted algorithmic music composition through natural language interaction.

Tools
7
Resources
0
Prompts
0

🌀 TidalCycles MCP Server

Conversational live coding with Claude AI + TidalCycles

License: MIT Node Version

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

🚀 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 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

📄 License

MIT License - see 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

Made with 🌀 for the live coding community

Go forth and make some algorithmic noise!