MCP: tools
Every tool the Maru MCP server offers, what it does and the permission it needs, plus the machine-readable catalog.
The Maru MCP server offers these tools to a connected agent. Each name starts
with maru_ so you and the agent can tell them apart from other servers'
tools. Read tools need mcp:read; tools that create something need
mcp:write; tools that spend your generation credits need mcp:generate,
which your agent asks for separately the first time it generates.
The same list is published as JSON at /mcp/tools.json,
with each tool's full description, input schema and annotations, for scripts
and for checking what an agent will see before you connect.
Guides
| Tool | Permission | Does |
|---|---|---|
maru_list_guides | mcp:read | Lists the Maru guides and when each applies |
maru_read_guide | mcp:read | Reads one or more guides |
Your projects
| Tool | Permission | Does |
|---|---|---|
maru_list_studio_projects | mcp:read | Lists your Studio projects with status, slug and Studio link |
maru_list_module_files | mcp:read | Lists one project's files, named by its slug |
maru_search_module_source | mcp:read | Searches a project's source for text or a pattern |
maru_read_module_source | mcp:read | Reads a window of one source file |
Community and engine
| Tool | Permission | Does |
|---|---|---|
maru_search_community_modules | mcp:read | Searches modules other creators published |
maru_list_community_module_files | mcp:read | Lists a published module's source files |
maru_read_community_module_source | mcp:read | Reads a published module's open source |
maru_list_dsp_nodes | mcp:read | Lists the engine's DSP nodes, their channels and parameters |
maru_list_effects | mcp:read | Lists the named effects you can chain in MultiFX, by family, so you can recompose before writing DSP |
Library
Name a published module or sampler bank the way you would in the terminal or
the plug-ins: @handle/slug, @handle/slug@3 to pin a publication, or a
pasted maruaudio.com link such as https://maruaudio.com/@handle/slug.
| Tool | Permission | Does |
|---|---|---|
maru_library_resolve | mcp:read | Resolves a module or sampler bank reference: which Maru plug-in loads it, its live version, price, licence and download |
maru_library_favorite | mcp:write | Saves a module or sampler bank to your library, or removes the save |
maru_remix | mcp:write | Remixes a module or sampler bank into your account as a new project, with its lineage; refuses a licence that forbids it and a paid item you have not bought |
Plug-in builds
| Tool | Permission | Does |
|---|---|---|
maru_list_plugin_builds | mcp:read | Lists your plug-in builds: state, latest release, each format |
maru_show_plugin_build | mcp:read | One plug-in's recent builds, errors and releases |
Create
| Tool | Permission | Does |
|---|---|---|
maru_list_studio_templates | mcp:read | Lists the templates a new project can start from |
maru_create_studio_project | mcp:write | Creates a Studio project from a template |
maru_create_sound_bank | mcp:write | Creates an empty MIDI sound bank |
Generate
| Tool | Permission | Does |
|---|---|---|
maru_generate_audio | mcp:generate | Generates one-shots, loops or effects from a prompt (1 to 4 variations) |
maru_generate_kit | mcp:generate | Generates a 16-pad drum kit from a prompt |
maru_check_audio_generation | mcp:read | Collects a generation that was still rendering when the call returned |
maru_cancel_audio_generation | mcp:generate | Requests cancellation of your existing gateway-backed audio or kit take without starting a new render |
Every generated sound is saved to your Generated Sounds library and comes back as a link you can open. Generation spends credits the same way it does on the site.
To cancel, call maru_cancel_audio_generation with
{"job":"<returned job id>"}. It uses your existing generation permission
and spends no new credits. Queue-backed takes currently return an explicit
unsupported error. Read permission alone cannot cancel a generation.
Audio jobs and workflows
Inspect capabilities before submitting work. Raw jobs retain private artifacts;
generate_sample saves an account sample after its required MIDI and analysis
steps. Availability depends on the configured model and healthy workers.
| Tool | Permission | Does |
|---|---|---|
maru_list_audio_capabilities | mcp:read | Inspects current task and model availability |
maru_prepare_audio_source | mcp:generate | Admits an already uploaded owned audio asset as an immutable source |
maru_submit_audio_job | mcp:generate | Submits a versioned audio task with a retained request key |
maru_get_audio_job | mcp:read | Reads an owned job and its artifact descriptors |
maru_list_audio_jobs | mcp:read | Pages through owned audio jobs |
maru_get_audio_job_by_request_key | mcp:read | Recovers a submission after a lost response |
maru_get_audio_job_events | mcp:read | Replays persisted events after a saved sequence |
maru_get_audio_artifact | mcp:read | Reads artifact metadata and its authenticated download path |
maru_cancel_audio_job | mcp:generate | Cancels an owned job without starting another render |
maru_retry_audio_job | mcp:generate | Retries an owned job after checking admission and credits again |
maru_generate_sample | mcp:generate | Generates one seeded sample with required MIDI and analysis |
maru_analyze_sample | mcp:generate | Extracts beat MIDI or stems from an owned library sample |
maru_get_audio_workflow | mcp:read | Reads workflow readiness and child job identities |
maru_list_audio_workflows | mcp:read | Pages through owned named workflows |
maru_cancel_audio_workflow | mcp:generate | Cancels an owned workflow without a new charge |
maru_retry_audio_workflow_step | mcp:generate | Retries a failed step with a new retained retry key |
Owned job and workflow reads also accept an existing generation grant. Source preparation and cancellation require generation permission but spend no new credits. Retry and submission may spend credits. For schemas and source identity requirements, see Add generative audio to your app.
Not on the remote server
Some Maru operations stay with the CLI and the local maru mcp server, which
work on the project in your checkout:
- Editing source, building, checking, evaluating, exporting and deploying a module. Source edits in your account happen in Studio.
- Instrument generation and transcription (
maru audio generate instrument,maru audio transcribe): not served by the hosted service yet. - Hardware projects and the local module catalog.
maru tools list prints every operation the CLI and the local server offer,
and maru tools describe --json prints their input schemas. Run
npx maruaudio mcp install --local to add the local server to your coding
agents, and npx maruaudio skill install for the agent skill, which teaches
the agent to discover these operations itself. A signed-in maru runs the
same hosted operations as this server; see
Use Maru from your agent.