TidalCycles MCP Server
This MCP server lets an MCP client control TidalCycles and Strudel: evaluate and manage patterns, layers, tempo, controls, samples, playback state, and web-based Strudel playback.
Evaluate, silence, hush, solo, and unsolo TidalCycles patterns on channels
d1–d9.Build channels layer by layer using transforms, sources, and controls; replace or remove named layers and provide autopilot variants.
Set tempo, change named
cF/cScontrol values without re-evaluation, and optionally glide numeric values over time.Query current channel state, evaluation history, server/Tidal status, and installed sample banks or synths.
Get a palette of working Tidal transforms, sources, and controls.
Run autopilot to keep layered channels evolving between turns.
Control Strudel blocks, tempo, hush, and state when the web UI is enabled.
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., "@TidalCycles MCP Server Create a funky 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
An MCP server that lets Claude (or any MCP client) play TidalCycles patterns. You describe what you want, Claude writes the Tidal code, and the server evaluates it on d1–d9.
It keeps track of what's playing on each channel, so you can say "make the hi-hats busier" and Claude knows what the hi-hats currently are.
How it works
The server doesn't make music itself, and there's no AI inside it. It gives an MCP client a set of tools, such as "evaluate this pattern on d2" or "hush". The language model in the client decides what to call and writes the Tidal code.
What comes back keeps the model honest:
Tidal's own errors. In GHCi mode, each pattern runs in a real Tidal session. If it doesn't type-check, the model gets GHC's error message and can fix it. Nothing changes on that channel in the meantime.
What's actually installed.
tidal_list_sampleslists your sample banks and synths, and the server warns when a pattern uses one that doesn't exist. Tidal accepts those patterns, but they're silent.What's playing.
tidal_get_stateshows each channel's code, including anything you've played yourself in a shared session.Idioms that work.
tidal_palettelists transforms and effects that are checked against real Tidal.
Everything the model sends is ordinary Tidal code, and it appears in the conversation and in the session log. You can read it, copy it into your own editor, or learn from it.
It works with any MCP client, not only Claude, including clients that run local models.
Related MCP server: supercollider-mcp
Requirements
Node.js 22 or later
TidalCycles, which includes GHCi
SuperCollider with SuperDirt and the Dirt-Samples: in SuperCollider run
Quarks.install("SuperDirt")andQuarks.install("Dirt-Samples"), then recompile the class libraryAn MCP client, such as Claude Desktop or Claude Code
Install
Claude Desktop: download tidal-mcp-server.mcpb from the latest release and open it. Claude Desktop shows an install dialog with the settings: whether to run Tidal for you, your ghci path, and an optional port for the web pages. You can switch the server on and off in Claude Desktop's settings. A bundle doesn't update itself: tidal_status says when a newer release is out, and you install its .mcpb the same way.
Other clients, or configuring by hand: your MCP client runs the server with npx, which downloads it on first use. See Configure your client. npx checks npm each time the client starts the server, so you get new releases by restarting it. The examples ask for tidal-mcp-server@^1, so a 2.0 with breaking changes never installs itself. To update only when you choose, pin an exact version, like tidal-mcp-server@1.2.0.
To work on the server itself, see Development.
Start SuperDirt in SuperCollider before you use the server. Plain SuperDirt.start fails with "No more buffer numbers" once the full Dirt-Samples library is installed, because SuperCollider's default buffer limit is too low. Raise the limit first:
(
s.reboot {
s.options.numBuffers = 1024 * 256;
s.options.memSize = 8192 * 32;
s.options.numWireBufs = 2048;
s.options.maxNodes = 1024 * 32;
s.options.numOutputBusChannels = 2;
s.options.numInputBusChannels = 2;
s.waitForBoot {
~dirt = SuperDirt(2, s);
~dirt.loadSoundFiles;
s.sync;
~dirt.start(57120, 0 ! 12);
};
s.latency = 0.3;
};
)To run this every time SuperCollider starts, put it in your startup file (File → Open startup file).
Configure your client
The server has two ways of getting code to Tidal.
Direct GHCi mode (recommended)
The server starts GHCi with BootTidal.hs itself and sends each command to it. If Tidal rejects a pattern, for example because it doesn't type-check, the error goes back to Claude, and the server's state stays as it was. Tidal also keeps playing whatever was on that channel before. If GHCi dies or stops responding, the server restarts it on the next call.
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"tidal": {
"command": "npx",
"args": ["-y", "tidal-mcp-server@^1"],
"env": {
"TIDAL_USE_GHCI": "true",
"GHCI_PATH": "/path/to/ghci"
}
}
}
}Claude Code:
claude mcp add tidal \
-e TIDAL_USE_GHCI=true \
-e GHCI_PATH="$(which ghci)" \
-- npx -y "tidal-mcp-server@^1"If you leave out GHCI_PATH, the server looks for ghci on its PATH, then where ghcup and Homebrew install it (~/.ghcup/bin, /opt/homebrew/bin, /usr/local/bin; C:\ghcup\bin on Windows). Apps started from the Dock or Start menu don't get your shell's PATH, so if your ghci is somewhere else, set GHCI_PATH (which ghci, or where ghci on Windows, tells you where it is). Path settings can start with ~.
Code runs on your computer. In GHCi mode the code Claude sends runs straight away, with your permissions. Tidal code is Haskell, and GHCi runs any Haskell, not only patterns, including code that reads or changes your files. The server says so once, in its first reply after you install it. If you'd rather read code before it runs, use file mode.
The server boots Tidal with the BootTidal.hs it ships with. To use your own instead, for example the one your editor uses, set TIDAL_BOOT_PATH.
Playing alongside Claude in your editor
By default, the server's Tidal and your editor's Tidal are separate. You hear both, but hush only stops one of them, and Claude can't see what you're playing. To share one Tidal session instead, set TIDAL_SHARE_SESSION=true. It needs GHCi mode, and it isn't available on Windows yet.
When sharing is on, the server writes a stand-in ghci into ~/.tidal-mcp/bin. Point your editor at that folder; in Pulsar, set the TidalCycles package's Ghci Path to ~/.tidal-mcp/bin. Then:
Your code runs in the server's Tidal, so there's one
hushand one clock.What you play shows up in
tidal_get_state, so Claude can play along with it.Your errors appear in your editor's console, and Claude's go back to Claude.
Your editor's
:script BootTidal.hsis skipped, because the server has already booted Tidal. UseTIDAL_BOOT_PATHto make the server use your boot file instead.When the server isn't running, the stand-in runs your real
ghci, so your editor still works on its own.
The connection is a socket in ~/.tidal-mcp that only your user can open.
File mode
Nothing runs GHCi for you. Each tool call overwrites TIDAL_FILE with the latest command, and you evaluate it yourself, for example from an editor with Tidal support.
"env": {
"TIDAL_FILE": "/path/to/tidal-mcp-output.tidal"
}The file only ever holds the most recent command. Use file mode when you want to see and approve each command before it plays.
The control page and Strudel
Set TIDAL_UI_PORT (for example 7070) and the server also serves two web pages:
http://localhost:7070/, the control page: what's playing on each channel, with each layer, plus the tempo, controls, autopilot and Tidal's status. It has a big Hush button, autopilot start/pause/stop, and Restart Tidal. It updates live.http://localhost:7070/strudel, a Strudel page: it plays Strudel programs that Claude builds with thestrudel_*tools, using the same Dirt-Samples. Click Start sound once, because browsers only play audio after a click. Anyone who opens the page hears the same program on their own device.
Strudel programs are built from named blocks, like layers: strudel_set_block adds or replaces one, and every block plays at once. If Strudel rejects the code, Claude gets the error, and what was playing keeps playing. A page that opens later picks up the current program.
The pages listen on 127.0.0.1. For an event where the audience opens the Strudel page on their phones, set TIDAL_UI_HOST=0.0.0.0 and share http://<your-ip>:7070/strudel. Other machines can watch and listen, but only this machine can press the buttons. The pages load Strudel from unpkg.com and the samples from GitHub, so the browser needs internet access.
Tools
Tool | Arguments | What it does |
|
| Runs |
|
| Runs |
| — | Stops everything |
|
| Runs |
| — | Unsolos every channel that was soloed |
|
| Lists what's playing on each channel, when it started, and the tempo. |
| — | Shows the settings in use (ghci, boot file, as resolved), whether Tidal starts and its version, the control port, the last error and the log file. Starts Tidal in GHCi mode, so it reports whether it actually starts |
|
| Sets the tempo, assuming four beats per cycle |
|
| Lists recent patterns, newest first |
|
| Adds or replaces one layer of a channel and re-evaluates it |
|
| Removes a layer and re-evaluates the channel |
|
| Keeps layered channels changing between turns |
| — | Lists Tidal transforms, sources and controls that combine well |
|
| Changes a value that patterns read with |
|
| Adds or replaces a block in the Strudel program (needs |
|
| Removes a block; removing the last one hushes Strudel |
|
| Sets Strudel's tempo ( |
| — | Stops Strudel and clears its blocks |
| — | Shows the program, its blocks, and how many pages are open |
|
| Lists the sample banks and synths SuperDirt has installed |
Layers
Instead of one pattern string, a channel can be built from named layers:
every 3 (jux rev) $ chop 4 $ s "bd*2 [~ sd]" # crush 4 # n "0 1"
└── transform ──┘ └ tr ┘ └─── source ───┘ └ control ┘ └ control ┘Claude can change one layer, such as swapping chop 4 for striate 8, without rewriting the rest. Transforms apply in the order they were added, outermost first. Each channel has one source. tidal_eval on a channel replaces its layers.
Changing values while a pattern plays
Re-evaluating a pattern swaps it in all at once. For smooth changes, a pattern can read a named value with cF (numbers) or cS (strings):
d1 $ s "bd*4 hh*8" # lpf (cF 1000 "cutoff")tidal_set_control then changes cutoff through Tidal's control port, with no re-evaluation. With seconds, the value glides there, for example a filter sweep over 16 seconds. The value number in cF is what's used until the control has been set. The server sends to the cCtrlPort set in the boot file (6011 in the bundled BootTidal.hs), or to Tidal's default 6010 in file mode.
Autopilot
Claude can only change the music when you message it. The autopilot keeps layered channels moving in between. Each layer that has variants, and every transform layer, changes on its own random timer (10–40 seconds by default). A layer either switches to another of its variants, or, if it's a transform, sometimes drops out for a while and comes back later. pause freezes things as they are. stop also hushes everything.
If a pattern uses a sound SuperDirt doesn't have, Tidal still accepts it, but that part is silent. So the server checks every name used with s or sound against your Dirt-Samples folder and SuperDirt's synths, and warns Claude about any it can't find.
Each session is logged to its own file in tidal-mcp-sessions/, next to TIDAL_FILE, named by its start time. The log is a .tidal file: each entry is the code the server ran, under a -- time what happened comment, so you can open it in your editor and evaluate any block to replay that moment. Anything that isn't Tidal code, such as rejected code or Strudel programs, is commented out. Set TIDAL_LOG_FILE to keep adding every session to one file instead; logs are never overwritten. tidal_status says where the current one is.
Environment variables
Variable | Default | |
|
|
|
| the | Boot script passed to GHCi |
|
| GHCi binary |
|
| Output file in file mode |
| a new file per session in | One session log file to add every session to |
| SuperCollider's | Where to find Dirt-Samples and SuperDirt, if SuperCollider keeps them somewhere unusual |
| — | Extra sample folders to check names against, separated by |
|
|
|
|
| Where the shared-session socket and the |
| the boot file's | Tidal's control port, for |
|
| Host for the control port |
| — | Serve the control page and the Strudel page on this port |
|
| Address for the pages; |
|
|
|
|
|
|
For the WebSocket transport and its settings, see WEBSOCKET-USAGE.md.
Troubleshooting
Ask Claude to run tidal_status first. It shows the settings the server is actually using, and why Tidal didn't start.
Couldn't find ghci: the error lists where the server looked. Set GHCI_PATH to the full path of ghci.
Nothing plays:
Check SuperDirt is running and shows
listening to Tidal on port 57120.In GHCi mode, Tidal starts with the first pattern, not with the server.
tidal_statussays whether it started.
Tidal didn't load: GHCi ran the boot file, but Tidal's functions aren't defined afterwards. Check the boot file imports Sound.Tidal.Context, and that ghci is the one Tidal is installed for.
Tidal's control port ... is in use: another Tidal is running, with the same cCtrlPort: your editor's, or another copy of this server. Two would both play to SuperDirt, so the server won't start a second. Stop the other one, use a boot file with a different cCtrlPort, or share one session with your editor (see above).
Sound keeps going after the server stops: the server stops GHCi when it shuts down. If a GHCi process outlives it, run pkill ghci, or in SuperCollider run s.freeAll.
No samples: install Dirt-Samples (see Requirements), then restart SuperDirt.
ERROR: No more buffer numbers when SuperDirt starts: SuperCollider's buffer limit is too low for Dirt-Samples. Use the startup code under Install instead of SuperDirt.start.
Limitations
The server only knows what it has sent. If you also evaluate code by hand in the same Tidal session,
tidal_get_statewon't reflect it.Type errors come back to Claude, but runtime errors don't. Tidal prints those on its own while the pattern plays, so the server only logs them. File mode has no feedback at all.
The pattern is arbitrary Haskell, run with your user's permissions. Only connect clients you trust.
Development
git clone https://github.com/Benedict/tidal-cycles-mcp-server.git
cd tidal-cycles-mcp-server
npm install
npm run build
npm run dev # run from source with tsx
npm test # build, then run the test suite against dist/
npm run typecheck:tidal # type-check generated Tidal code against your Tidal install
npm run smoke:ghci # run the built server in GHCi mode against your Tidal (silent patterns only)
npm run bundle # build tidal-mcp-server.mcpb for Claude DesktopThe tests drive the built server over stdio in file mode, so they don't need GHCi or SuperCollider.
typecheck:tidal starts GHCi with BootTidal.hs and runs :t on every command the server sends and every palette entry. :t checks types without evaluating anything, so nothing plays. smoke:ghci only plays rests on d9, so it's safe to run with SuperDirt up. Set GHCI_PATH if ghci isn't on your PATH. CI runs all of these.
Design notes for possible future features are in docs/design. See CONTRIBUTING.md for where things go in the code.
Releasing
Bump version in package.json, update CHANGELOG.md, merge, then tag:
git tag v1.2.0 && git push origin v1.2.0.github/workflows/release.yml checks the tag matches package.json, runs the tests, publishes to npm with provenance, then creates a GitHub release with the Claude Desktop bundle attached. It uses npm trusted publishing if the package has this workflow set as a trusted publisher on npmjs.com, and otherwise an NPM_TOKEN repository secret.
License
MIT
Available Tools
20 toolsstrudel_get_stateA
Show the Strudel program, its blocks, how many Strudel pages are open, and the page's address.
Inputs: no named parameters.
strudel_hushA
Stop everything in Strudel and clear its blocks.
Inputs: no named parameters.
strudel_remove_blockB
Remove a named block from the Strudel program. Removing the last one hushes Strudel.
Inputs: name (required).
strudel_set_blockA
Add or replace a named block in the Strudel program, which plays on every open Strudel page (the server's web page at /strudel; needs TIDAL_UI_PORT). Each block is one Strudel pattern in JavaScript syntax, e.g. s("bd*2 [~ sd]").bank("RolandTR909") or note("c e g").s("piano").fast(2). Blocks play together. If Strudel rejects the code, you get its error and nothing changes.
Inputs: code (required), name (required).
strudel_set_tempoB
Set Strudel's tempo in beats per minute, assuming four beats per cycle (setcpm(bpm/4)).
Inputs: bpm (required).
tidal_autopilotA
Keep layered channels evolving between turns. While running, each layer changes on its own random timer: it switches to another of its variants, and transform layers sometimes lay out for a while. start: begin or resume, optionally with new settings. pause: stop changing, keep playing. stop: stop changing and hush everything. status: report settings and how many layers are moving.
Inputs: action (required), maxSeconds, minSeconds, layOutChance.
tidal_evalA
Evaluate a TidalCycles pattern on a specific channel (d1-d9). Replaces anything on that channel, including its layers. To build a channel you can edit piece by piece, use tidal_set_layer instead.
Inputs: channel (required), pattern (required).
tidal_get_historyA
Get the history of patterns evaluated in this session.
Inputs: limit.
tidal_get_stateA
Get the current state of all channels - what patterns are playing and when they started.
Inputs: quiet.
tidal_hushA
Stop all currently playing patterns immediately. Use this to clear everything.
Inputs: no named parameters.
tidal_list_samplesA
List the sample banks and synths SuperDirt has installed. Use these names with s or sound; any other name is silent. Check here before using a sample you aren't sure exists.
Inputs: filter, refresh.
tidal_paletteA
Get a reference list of Tidal transforms, sources and controls that combine well, grouped by layer kind.
Inputs: no named parameters.
tidal_remove_layerA
Remove a named layer from a channel and re-evaluate it. Removing the last layer silences the channel.
Inputs: name (required), channel (required).
tidal_set_controlA
Change a named value in Tidal without re-evaluating any pattern, through Tidal's control port. Patterns read it with cF (numbers) or cS (strings), e.g. tidal_eval d1 's "bd*4" # lpf (cF 1000 "cutoff")', then set cutoff here. With seconds, a number glides from its current value, for sweeps and fades.
Inputs: name (required), value (required), seconds.
tidal_set_layerA
Add or replace one named layer of a channel, then re-evaluate that channel. A channel's pattern is built as: $ $ ... # # . Transforms apply in the order they were added, outermost first. Each channel has one source; setting a new one replaces the old. Give variants to let tidal_autopilot switch between them. Call tidal_palette for idioms that work.
Inputs: code (required), kind (required), name (required), channel (required), +1 more.
tidal_set_tempoB
Set the tempo in beats per minute, assuming four beats per cycle (setcps (bpm/60/4)).
Inputs: bpm (required).
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 until tidal_unsolo is called.
Inputs: channel (required).
tidal_statusA
Check the server's setup: mode, the ghci and boot file it uses (as resolved), whether Tidal is running and its version, the control port, the last error, and where it logs. In GHCi mode this starts Tidal if it isn't running, so it reports whether Tidal actually starts. Use it when something doesn't work.
Inputs: no named parameters.
tidal_unsoloA
Restore all channels after soloing (unsolos every soloed channel).
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 20 tools
The tidal_/strudel_ prefixes cleanly separate the two subsystems, and descriptions explicitly differentiate the easy confusions (tidal_hush for all vs tidal_silence for one channel; tidal_eval replaces a whole channel vs tidal_set_layer builds piece by piece). The three read-back tools (tidal_get_state, tidal_status, tidal_get_history) target genuinely different things but their similar 'get/status' framing creates mild ambiguity. Overall mostly distinct with a couple of soft overlaps.
All names use snake_case with a consistent domain prefix (tidal_ or strudel_), and most follow verb_noun (set_layer, remove_layer, list_samples, get_state, set_tempo). A handful drop the noun (tidal_solo, tidal_hush, tidal_eval, tidal_palette), which is a minor deviation but keeps the prefix system predictable.
Twenty tools exceeds the typical 3-15 sweet spot, but the surface spans two distinct systems (Tidal and Strudel) plus layered-channel management, autopilot, palette, and samples, so most tools earn their place. It is slightly heavy but not gratuitous.
Tidal coverage is close to full (eval, layer add/remove, hush/silence, solo/unsolo, tempo, control port, palette, samples, history, status). Strudel is thinner, lacking solo, palette, samples, and control equivalents, but its core block/tempo/hush lifecycle is present. Minor gaps an agent can work around.
Maintenance
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
- AlicenseNot gradedqualityDmaintenanceEnables natural language control over Ableton Live for generating musical patterns, melodies, and full song arrangements. It also provides tools for sample searching and mixing assistance through an OSC-based connection with Claude Desktop.1MIT
- 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
- FlicenseNot gradedqualityCmaintenanceControl Ableton Live using natural language via Claude Code, with music theory engine for progressions, project persistence, and song cloning.-
- AlicenseAqualityDmaintenanceEnables conversational live coding with Claude AI and TidalCycles for algorithmic music composition, allowing natural language control of patterns, channels, and state.842 npmMIT