# MCP: tools

> Every tool the Maru MCP server offers, what it does and the permission it needs, plus the machine-readable catalog.

Canonical: https://maruaudio.com/docs/mcp-tools
Documentation index: https://maruaudio.com/llms.txt

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`](https://maruaudio.com/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 |

## 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.

## 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](https://maruaudio.com/docs/agent-setup.md).