tidal-cycles-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tidal-cycles-mcp-server Create a four-on-the-floor kick drum pattern"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π 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: MCP Music Studio
π Prerequisites
Before installing, ensure you have:
TidalCycles - Install from tidalcycles.org
Includes GHCi (Glasgow Haskell Compiler Interactive)
Haskell Stack or Cabal
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")
Claude Desktop - Get from claude.ai
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 build2. 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_PATHReplace /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
Restart Claude Desktop to load the MCP server
Start a new conversation
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 sparseLive 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 thed1 $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:
You talk to Claude in natural language
Claude uses MCP tools to generate Tidal code
MCP server either:
File mode: Writes code to
.tidalfile β File watcher evaluates itDirect mode: Sends directly to running GHCi process
TidalCycles/GHCi sends OSC messages to SuperDirt
SuperCollider/SuperDirt plays the audio
π Troubleshooting
"MCP server not connecting"
Check the path in
claude_desktop_config.jsonis absoluteRestart 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.startVerify 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 ghciVerify GHCI_PATH in config matches
which ghciCheck 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:
hushKill 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
π 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!
Available Tools
8 toolstidal_evalB
Evaluate a TidalCycles pattern on a specific channel (d1-d9). This is the main way to make music with Tidal.
Inputs: channel (required), pattern (required).
tidal_get_historyA
Get the history of patterns evaluated in this session.
Inputs: limit.
tidal_get_samplesA
Get list of available sample names from Dirt-Samples folder.
Inputs: no named parameters.
tidal_get_stateA
Get the current state of all channels - what patterns are playing and when they started.
Inputs: no named parameters.
tidal_hushA
Stop all currently playing patterns immediately. Use this to clear everything.
Inputs: no named parameters.
tidal_silenceA
Stop a specific channel. More graceful than hush for single channels.
Inputs: channel (required).
tidal_soloA
Solo a specific channel, muting all others temporarily.
Inputs: channel (required).
tidal_unsoloB
Restore all channels after soloing.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 8 tools
Each tool targets a clearly distinct action: evaluating patterns, stopping all/specific channels, querying state, soloing/unsoloing, and retrieving history or sample lists. The only potential overlap is hush vs. silence, but their descriptions make the all-vs-single-channel distinction unambiguous.
All tools share the tidal_ prefix and use a consistent snake_case imperative style. Queries are uniformly get_ prefixed, and action verbs (eval, hush, silence, solo, unsolo) are simple and predictable.
Eight tools is well-scoped for a TidalCycles live-coding server. Each tool serves a distinct part of the workflow without redundancy or unnecessary bloat.
The set covers the core live-coding lifecycle:play, stop, silence, solo, state inspection, history, and sample discovery. A minor gap is the lack of tempo/global control tools, but these may be outside the intended server scope.
Related MCP Connectors
Generate AI music via the Lacuna Music API from MCP clients like Claude Desktop & Code.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
People and AI agents build software together in persistent cloud sessions for Claude Code.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables natural language control of Pure Data patches through Claude AI, allowing dynamic creation, modification, and DSP control via the Model Context Protocol.1124-
- AlicenseNot gradedqualityBmaintenanceTwo-mode creative music studio for AI: scored composition (ABC notation with sheet music) and live performance (Strudel live coding with TidalCycles), with interactive UI rendering inline in Claude Desktop and other MCP clients.226 npm79AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceConnects Claude Code to SuperCollider for AI-driven music composition, supporting real-time playback and non-realtime audio rendering at 50-150x realtime speed.MIT
- AlicenseAqualityBmaintenanceEnables conversational live coding with Claude AI and TidalCycles, allowing users to create and manipulate algorithmic music patterns through natural language.2042 npm18MIT