vamp-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Vamp
Vamp is a local-first, headless music engine for coding agents: a versioned JSON song format with a deterministic offline renderer, a CLI, an MCP server, and a TypeScript SDK. It lets an agent compose original, editable background music on its own machine — no account, no cloud API, and no network access at render time.
Highlights
Fully local. Rendering is a local process over a JSON file. Nothing is downloaded at render time; on Linux the offline guarantee is enforced inside a network-free namespace in CI.
Editable source, not a prompt lottery. A song is data — notes, instruments, patterns, effects, automation — so edits are revision-safe and deterministic instead of re-rolls.
Real sampled instruments by default. The
autobackend renders General MIDI presets through FluidSynth and a local GM SoundFont, with a dependency-free oscillator synth as fallback.Complete render artifacts. Every render produces a master WAV, per-track stems, a Type 1 MIDI file, and a report (duration, peak, clipping, loudness, backend, hashes, warnings).
Agent-native surfaces. CLI with JSON envelopes and stable exit codes, a stdio MCP server with 14 tools, and a typed SDK — all revision-safe and confined to a project root.
Related MCP server: VOCALOID MCP
Status
v1 is published on npm at version 0.1.0 and CI-verified on Linux, macOS, and
Windows. WAV is the only render format — MP3 export and playback are not
implemented.
Install
npm i -g @gxaditya/vamp
vamp --version
vamp doctor # reports FluidSynth + SoundFont provisioningOr without a global install:
npx -y @gxaditya/vamp-cli --version
npx -y @gxaditya/vamp-mcp-server --project-root "$PWD/vamp-projects"The rest of this README covers the development workspace — for the published
packages' tool contracts see docs/api.md and
docs/mcp.md.
Requirements
Node.js ≥ 22.13 and pnpm 10.15.1 (via
corepack enable).Python ≥ 3.11 — only for the generated-types import check; stdlib only.
FluidSynth 2.x + a GM SoundFont (recommended) for sampled rendering. Without them, everything works through the built-in synth.
# Debian/Ubuntu sudo apt install fluidsynth fluid-soundfont-gm # macOS — plus a GM .sf2 under ~/.local/share/vamp/soundfonts/ (or VAMP_SOUNDFONT_PATH) brew install fluid-synthProvisioning, search order, and the pinned FluidR3 checksum are in
docs/instruments.md.
Build and verify
pnpm install
pnpm build
pnpm check:generated # generated types in sync with the schema
pnpm lint && pnpm typecheck
pnpm test # fast + native + security suitesQuick start (CLI)
pnpm exec vamp doctor # check FluidSynth / SoundFont provisioning
pnpm exec vamp init my-cue --preset lofi --duration 45 --bpm 90
pnpm exec vamp validate vamp-projects/my-cue/song.json
pnpm exec vamp render vamp-projects/my-cue/song.json \
--out vamp-projects/my-cue/renders/masterA render writes master.wav, one stem-*.wav per audible track, song.mid,
and report.json, refusing overwrites without --overwrite. Useful options:
--sample-rate 44100|48000 (default 48000), --backend auto|builtin|fluidsynth,
--no-stems, --no-midi, --no-report, --no-normalize, --json for a
single machine-readable envelope. Exit codes: 0 success (validation warnings
do not fail), 1 failure (validation, file, project, render, cancellation),
2 usage error.
Commands: init, validate, info, render, schema, presets, doctor.
Full contracts and envelope shapes: docs/api.md.
MCP server
The vamp-mcp stdio server exposes the whole agent loop over 14 tools:
discovery (health_check, get_schema_guide, list_instruments,
list_presets), authoring and revision-safe edits (validate_song,
create_song, get_song, list_projects, update_song, add_track,
add_notes, set_pattern, set_instrument), and render_song for bounded,
confined rendering into a project's renders/ tree.
{
"mcpServers": {
"vamp": {
"command": "node",
"args": [
"/absolute/path/to/vamp/packages/mcp-server/dist/main.js",
"--project-root",
"/absolute/path/to/vamp-projects"
]
}
}
}Configuration also comes from VAMP_PROJECT_ROOT, VAMP_FLUIDSYNTH_PATH, and
VAMP_SOUNDFONT_PATH; arguments take precedence over environment variables.
Every persisted edit requires expectedRevision — a stale revision returns a
repairable project.revision.conflict and changes nothing. Client setup for
Claude Code, Cursor, and Codex, plus full tool contracts:
docs/mcp.md.
SDK
@gxaditya/vamp-sdk is a typed facade over the shared libraries — the same
result, error, and revision contracts with no HTTP and no service:
import { VampClient } from '@gxaditya/vamp-sdk';
const client = new VampClient({ root: '/absolute/path/to/vamp-projects' });
// validate, create, edit with expectedRevision, render, and inspect reportsExample songs
examples/songs/ ships five authored BGM cues that render fully offline on
the built-in instruments, each with a brief, duration math, render commands,
and revision-safe edit prompts:
Song | Use | Length | BPM | Key |
| Lo-fi coding bed | 45 s | 90 | A minor |
| Tutorial / explainer | 30 s | 112 | G major |
| Ambient focus | 60 s | 60 | A minor |
| Corporate clean | 30 s | 108 | C major |
| Dramatic stinger | 6 s | 110 | D minor |
See examples/README.md for the catalog and audition
checklist.
Packages
Package | Purpose |
| Umbrella: CLI + MCP server + SDK |
| Canonical JSON Schema, generated TS/Python types, validation, normalization |
| Song→timeline compiler, MIDI export, built-in and FluidSynth backends, WAV/stem/report renderer |
| Filesystem projects: revision-safe edits, atomic writes, locks, root confinement |
| The |
| The |
| Typed local client facade |
Architecture and data flow: docs/architecture.md.
Development
ESM-only TypeScript (strict, NodeNext), Vitest, ESLint + Prettier. Common commands from the repo root:
Command | Purpose |
| Build all packages to |
| Full suite (builds first) |
| Fast regression suite |
| FluidSynth + pinned-SoundFont suite |
| Hardening and adversarial suites |
| ESLint / Prettier gates |
| Generated-type drift checks |
| Regenerate TS + Python types from the schema |
| Verify the pinned FluidR3 checksum offline |
CI (.github/workflows/ci.yml) runs three job
groups on every push: core checks on Linux, a platform matrix
(ubuntu/macos/windows) with build, lint, typecheck, and test gates plus
CLI/MCP/render smokes, and a native matrix that provisions FluidSynth and the
pinned SoundFont on all three OSes and runs the native suite offline —
including a network-free unshare --net render on Linux.
Guarantees and scope
Determinism. The built-in synth is byte-deterministic for identical song, options, engine build, and platform. FluidSynth output is pinned same-machine only — cross-platform byte identity is not claimed.
Offline. No network or model calls after provisioning; no audio device required.
Security model. Lexical + realpath project-root confinement (including symlink escapes), argument-array subprocesses with sanitized environments and bounded output, atomic writes, advisory locks. Enforced in process logic, not an OS sandbox.
Versioning. Package SemVer and song
schemaVersionare independent. Loading never migrates; a future schema version requires an explicit, user-invoked migration.Not in v1. MP3 export, realtime playback, HTTP MCP transport, Python SDK, GUI, generative models, tempo maps, vocals. The schema rejects unknown fields rather than half-supporting them.
Troubleshooting
audio.backend.missing_dependency— FluidSynth not onPATH. Install it or pass--fluidsynth-path(Windows health checks rely onPATHEXTresolution).VAMP_FLUIDSYNTH_PATHavoids repeating the flag.audio.asset.checksum_mismatch— the SoundFont on disk is not the pinned FluidR3 bytes. Re-provision perdocs/instruments.md; never edit the checksum to make a check pass.project.path.confined— the path uses traversal, an absolute/drive/UNC form, or an escaping symlink. Use plain forward-slash relative paths underassets/orrenders/.macOS paths show
/private/...—/tmpand/varare symlinks; the store realpath-resolves the root. This is confinement working, not corruption.project.lock.busy— another writer holds the project lock; the wait is bounded, and crashed-process locks are recovered as stale automatically.
License
AGPL-3.0-only. Third-party notices:
THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Autonomous music production for AI agents with MIDI generation, QC and provenance.
Generate, edit and stream royalty-free music, or search a licensed catalogue.
Score video as an agent: cue sheet from the cut, 100+ AI instruments play your MIDI, mix to picture
Score video, make music as an agent: 100+ AI instruments play your MIDI, audio, stems, Logic/Ableton
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP-capable agents to author, compile, run, and commit generative music E-- Recipes from a library catalog, completing the full authoring loop.42 PyPIApache 2.0
- AlicenseBqualityCmaintenanceEnables coding agents to compose, tune, render, mix, and audit native VOCALOID3/4 projects from scratch, acting as a production bridge between intent and finished song.2214MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to create and edit Strudel music code, render offline WAV audio, and obtain structured hearing reports with waveform, spectrogram, BPM, and onset analysis.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to compose, edit and run multi-agent pipelines represented as songs, where channels are agents, notes are agent calls, and mixer buses carry each agent's output to the next. Lets agents create and modify arrangements, validate and render projects headlessly, play them back live in a studio window, and export the result as WAV or MP3, with every change undoable and cached takes replayed for free.43 npmMIT