tidal-cycles

This MCP server enables Claude to control TidalCycles via natural conversation. It exposes a set of tools that let Claude evaluate, manage, and query Tidal patterns in real time, with support for multiple channels (d1–d9), pattern history, and live solo/silence control. Core capabilities include tidal_eval to run a Tidal pattern on a specified channel, tidal_hush to stop all activity, tidal_silence to stop a single channel gracefully, tidal_get_state to inspect what’s playing, tidal_solo to spotlight a single channel, tidal_unsolo to restore all channels after a solo, and tidal_get_history to retrieve recent patterns. The server can operate in file-based mode (writing patterns to a tidal output file for TidalCycles to read) or in a GHCi-assisted mode for more dynamic interaction. To use it, configure Claude Desktop to point at the tidal MCP entry (tidal) and ensure SuperCollider with SuperDirt is running, then start the Node-based MCP server and begin a conversation with Claude to generate and modify patterns in real time.

Prerequisites:

• Node.js 18+ installed
• TidalCycles installed with GHCi (via haskell-stack or cabal) and SuperCollider + SuperDirt for audio output
• Claude Desktop (or Claude AI integration) for conversational control

Setup steps:

1. Clone the repository and install dependencies

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

2. Build the server (if a build step exists)

npm run build

3. Ensure TidalCycles and SuperDirt are running:

• Start SuperDirt in SuperCollider and verify it’s listening on port 57120 (e.g., SuperDirt.start; // Should print that it’s listening)

4. Create or update the Claude Desktop MCP config to point to the Node server. Example file-based configuration (adjust absolute paths):

{
  "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"
      }
    }
  }
}

5. Start the MCP server (as configured). Then restart Claude Desktop and begin a new conversation to generate patterns.

If you need direct GHCi mode later, you can enable environment variables such as TIDAL_USE_GHCI, TIDAL_BOOT_PATH, and GHCI_PATH as shown in the README to run in experimental mode.

Tips and notes:

• Ensure the TIDAL_FILE path is writable by the MCP server so TidalCycles can receive pattern updates.
• In file-based mode, you may use tools like watchexec to auto-reload the output file into TidalCycles.
• If you enable TIDAL_USE_GHCI, make sure GHCI is installed and the BootTidal.hs script path is correct.
• For remote clients or Claude Desktop setups, the server is designed to expose WebSocket-based communications or stdio transport to Claude, so ensure network connectivity if you plan to use WebSocket-based control.
• Common issues: mismatched Node version, incorrect absolute paths in config, or SuperDirt not started. Verify the SuperCollider output prints listening messages and that the MCP server’s environment variables are reachable by Claude.
• The server supports multiple channels (d1–d9); use tidal_eval with channel and pattern to drive specific parts of your composition.