Use Maru from your agent

The agent skill, the CLI, the local MCP server and the hosted MCP connector: what each one is for, which you need, the install commands and how they work together.

Maru works with the agent you already use. Four pieces connect it, and you install only the ones your work needs. The CLI and both MCP servers run the same operations under one permission model, so a project or a build looks the same from Claude Code, Codex, Cursor, Claude, ChatGPT or a script.

The four pieces

PieceWhat it isUse it for
Agent skill (maru-agent)Instructions for a coding agentTeaching the agent the Maru workflow and to ask the CLI for commands, schemas and guides
CLI (maru)The maruaudio npm packageCreating, building and checking projects on your computer; signed in, your hosted projects, builds and generation
Local MCP server (maru-local)maru mcp on stdioThe CLI's operations as MCP tools, on the project in your checkout
Hosted MCP connector (maru)https://maruaudio.com/mcpYour Maru account from any MCP client: projects and their source, guides, community modules, builds, new projects and sound generation

The skill contains no tools. It tells a coding agent to check the machine with maru doctor, read the guides for the task with maru guide, and look up exact input schemas with maru tools describe before it acts. The CLI and the two MCP servers do the work.

Which do I need

Your situationInstall
Building a plugin, kit or bank on your computer with Claude Code, Codex, Cursor or another coding agentThe skill and the CLI. Add the local server if you want the agent to call operations as MCP tools rather than shell commands.
Working on your Maru account from Claude, ChatGPT or Claude DesktopThe hosted connector. Paste the URL in the app's connector settings.
A coding agent that works on your account and your checkoutThe skill, plus both MCP servers.
Scripts and CIThe CLI with --json, or the hosted API with a personal token.

Install

The skill needs no sign-in:

bash
npx maruaudio skill install

Register the MCP servers with your coding agents:

bash
npx maruaudio mcp install            # the hosted connector (maru)
npx maruaudio mcp install --local    # the local server (maru-local)
npx maruaudio mcp install --both     # both

Both commands work on the agents used in the current project. Add --global to install for your user instead. npx maruaudio runs any command without a global install; to keep maru on your path, run npm i -g maruaudio.

mcp install writes each agent's own configuration and keeps the other servers there:

Agent (--client)This project--global
Claude Code (claude-code).mcp.jsonruns claude mcp add --scope user
Cursor (cursor).cursor/mcp.json~/.cursor/mcp.json
VS Code (vscode).vscode/mcp.jsonruns code --add-mcp
Codex (codex)~/.codex/config.toml~/.codex/config.toml
Gemini CLI (gemini).gemini/settings.json~/.gemini/settings.json
Claude Desktop (claude-desktop)claude_desktop_config.json for the local server; prints the Settings → Connectors steps for the connectorthe same

Without --client, it configures the agents it finds: those with files in this project (or in your home folder with --global), Codex and Claude Desktop where they are installed, and Claude Code when it finds none. Name agents with --client, which you can repeat. --dry-run shows what would change without writing. A configuration file that is not plain JSON is refused rather than overwritten; add the entry by hand from Connect your agent.

bash
npx maruaudio mcp install --client cursor --both
npx maruaudio mcp status    # which agents have Maru configured, and where
npx maruaudio mcp remove    # takes the same options as install

Restart the agent, or reload its MCP servers, afterwards. The hosted connector asks you to sign in to Maru in your browser the first time the agent uses it; in Claude Code, run /mcp, select maru and choose Authenticate.

Claude, ChatGPT and other apps that take a connector URL in their settings are set up by hand: Connect your agent has the steps for each.

How the pieces work together

  • One set of operations. Every Maru operation is a CLI command, an MCP tool and a typed call in the maruaudio library, with one input schema. The local server serves the same operations as the CLI, on the project in your checkout; maru tools list prints them.
  • One hosted catalog. The hosted connector, the hosted API (POST https://maruaudio.com/api/v1/ops/<name>) and a signed-in maru run the same hosted operations, such as maru project list, maru build list and maru audio generate. /mcp/tools.json publishes the list, and Tools explains each one.
  • One permission model. Each hosted operation reads, creates, or spends generation credits, and each of those needs its own permission. A connector asks for mcp:read and mcp:write when you approve it and for mcp:generate the first time it generates. maru login grants reading and creating by default; generation asks for inference:run separately (maru login --scope names the full set).
  • The skill ties them together. It sends the agent to the CLI for discovery, so the agent sees the features of the version you installed. It also tells the agent to ask you before signing in, running paid or hosted generation, publishing, or confirming a destructive command.

A typical local session uses all four: the skill guides the agent, the hosted connector finds your project and the guide, and the CLI or the local server edits, builds and checks the checkout.

Next