DrumSplit for agents

Upload a local audio file, separate its drums, and save the ZIP and WAV stems with one tool call. This package provides a local MCP server, a command-line client, and a Python client for the existing DrumSplit API.

Install and connect

Use Python 3.10 or newer:

python -m pip install drumsplit-mcp==0.1.0

Sign in at DrumSplit Developers, create an API key, and set DRUMSPLIT_API_KEY in your agent host's secret settings or launch environment. The connector never creates an account or purchases credits. API credits are separate from website credits. Each submitted split consumes one API credit, including drum-bus-only output.

Configure your MCP host to launch python -m drumsplit_mcp. The Python executable must belong to the environment where you installed this package. For hosts that accept JSON configuration:

{
  "mcpServers": {
    "drumsplit": {
      "command": "python",
      "args": ["-m", "drumsplit_mcp"]
    }
  }
}

Provide DRUMSPLIT_API_KEY to that process through the host's credential or environment configuration. Keep credentials out of prompts and shared config. Restart the connection after changing its environment.

Ask your agent to separate the drums from a local song and save them in a new output folder. The tool call is:

{
  "name": "separate_audio",
  "arguments": {
    "file": "/audio/song.wav",
    "output_dir": "/audio/song-stems"
  }
}

The server runs alongside the agent. Paths refer to files accessible to that process. This release does not accept public audio URLs or provide a hosted MCP endpoint for browser-only agents.

Use the command line

With DRUMSPLIT_API_KEY in your environment:

drumsplit separate song.wav --output-dir ./song-stems
drumsplit resume ./song-stems
drumsplit status JOB_ID
drumsplit download JOB_ID --output-dir ./downloaded-stems
drumsplit balance

Commands print JSON. Exit code 0 means the command succeeded, including a job that is still processing. Exit code 1 means an error, a failed job, or a job that was not found. CLI usage errors exit with code 2.

separate supports --output-mode full|drumbus, --input-type full_mix|drum_stem, --algorithm auto|natural|puncher, --quality standard|studio, and --wait-seconds. Defaults are full, full_mix, auto, standard, and 45 seconds. Paid-only options and duration limits are enforced by the API. Input files must be nonempty supported audio files no larger than 100 MiB.

Resume an interrupted request

Keep the output folder. The connector writes .drumsplit-request.json before submitting audio. The file contains request metadata and a retry key, without your API credential. Repeating separate with the same file, options, account, and output folder reuses that request. resume also works after the source file is removed once the job ID has been saved.

If the upload response is lost, resume reads the original audio and reuses the saved idempotency key. An unconfirmed request older than 23 hours stops instead of risking another charge after the API's documented 24-hour retry window. Never delete the request record to recover an uncertain submission. Contact support with its request ID if the connector cannot reconcile it.

A timeout returns status: processing, the job ID, and the output folder. Call resume_split or drumsplit resume later. Known jobs are never resubmitted. Failed or expired jobs do not automatically start replacement splits. A not_found observation can be checked again with resume; it is not cached as a permanent failure. Results are retained on the server for 24 hours; locally downloaded results remain in the output folder.

Use one new output folder per song/request. The connector refuses to overwrite unrelated files or mix different requests in the same folder. Keep the original API key available for resumption. A different key cannot adopt its saved record. The output folder itself must not be a symbolic link.

Tools

• separate_audio: submit, wait, and save the ZIP and WAV files.
• resume_split: continue a saved request using its output folder.
• get_job_status: inspect a job with the current API key.
• download_stems: save an existing job without submitting audio.
• get_balance: read the API credit balance and usage.

Downloads always use the authenticated DrumSplit API. The connector does not follow download redirects or arbitrary URLs returned by a server. ZIP extraction accepts flat WAV filenames, rejects traversal and symbolic links, and bounds the download and extracted size. Completed results include the archive path and individual WAV paths.

Use Python

import asyncio
from drumsplit_mcp import DrumSplitClient

async def main():
    async with DrumSplitClient.from_environment() as client:
        result = await client.separate_audio("song.wav", "song-stems")
        print(result)

asyncio.run(main())

Verify or build from source

Run these commands from this package directory:

python -m pip install -e '.[test]' build
python -m pytest -q
python -m build

The tests run an offline HTTP service and real MCP/CLI clients. They verify the connector's upload, recovery, download, and filesystem behavior. They do not prove GPU separation quality or production billing.

DRUMSPLIT_API_URL defaults to https://drumsplit.io/api/v1. The isolated staging hostname and HTTP loopback addresses are supported for testing. Direct Modal URLs are rejected. Do not run mutation tests against a Pages PR preview: those previews use production services.