FmodStudioMCP

AI-powered game-audio authoring in FMOD Studio through the Model Context Protocol

Quick Start • Features • Tools Reference • Architecture • Changelog • Contributing • Troubleshooting

FmodStudioMCP connects any MCP-compatible AI assistant to FMOD Studio, the game-audio middleware, and gives it full control over the authoring tool. Talk to your AI and it creates events, imports audio, builds parameter cultures, routes mixer buses, assigns banks, and builds your project — while you watch the editor apply every change live.

It runs over FMOD Studio's built-in JavaScript scripting terminal (TCP, port 3663), so — like its sibling ReaperMCP — there is no plugin, no cloud, nothing to install inside the tool: FMOD Studio ships the bridge. The MCP server is the only new piece, and it talks to a stock FMOD Studio install.

If this is useful to you, a star helps other people find it.

Works With

• Claude Desktop, Claude Code, Cursor, or any MCP-compatible client

Quick Start

1. Get FmodStudioMCP

Install directly:

pip install xdarkzx-fmod-studio-mcp

or clone and pip install -e . for development (see CONTRIBUTING.md).

2. Enable FMOD Studio's Script Server (one time)

The scripting terminal is disabled by default, and opening the console with Ctrl+0 is not enough — that only shows output.

1. Launch FMOD Studio and open your project (.fspro).
2. Edit → Preferences… (Windows) or FMOD Studio → Preferences… (macOS).
3. On the Interface tab, tick Enable Script Server (requires restart).
4. Quit and relaunch FMOD Studio, then reopen the project. The port is 3663 by default.

Confirmed it's listening? Check the newest log under %LOCALAPPDATA%\FMOD Studio\Logs\ for [Scripting] ScriptServer started on 127.0.0.1 (3663).

3. Register the server with your MCP client

{
  "mcpServers": {
    "fmod-studio": {
      "command": "fmod-studio-mcp"
    }
  }
}

fmod-studio-mcp reads FMOD_STUDIO_HOST / FMOD_STUDIO_PORT (defaults 127.0.0.1:3663) if your setup differs.

4. Start authoring

"List every event in the project"
"Create an event called 'Player/Footsteps' with a SingleSound loop of footsteps.wav"
"Add a 'Fear' User parameter to it, range 0-1, initial 0"
"Assign it to the Master bank and build the project"

FMOD Studio must be running with a project open. The bridge cannot launch Studio for you, and the Script Server only binds once a project is open.

Features

Curated tool surface (not generated)

Unlike auto-generated "one tool per API member" servers, every tool here is hand-shaped around the real authoring workflow. 90+ tools in 13 modules —

Typed, safe by default

• Every command is a named, schema-validated operation — no arbitrary-script escape hatch (same policy as ReaperMCP).
• Values are validated before they reach Studio (names, dB ranges, type whitelists, audio file paths/extensions).
• Params travel as inert JSON literals into a self-trapping JS wrapper — a hostile string can't break out of its quotes or reach the command body.
• Results are capped (MAX_OBJECTS_READ, etc.) so a busy project can't flood your model's context window.

Profile-trimmable tool surface

Smaller/cheaper models truncate tool lists. Set FMOD_STUDIO_MCP_PROFILE in your client's server config to pick a workflow-specific subset:

Production-grade plumbing, same as ReaperMCP

• TCP bridge with read-until-idle framing + typed connection/timeout errors (never a silent hang).
• Cross-process file mutex so multiple MCP clients can share one Studio without their evals interleaving.
• Command history archive (30-day retention) for after-the-fact debugging.
• Startup UTF-8 stdio fix and a self-retiring parent watchdog — battle-tested client behaviour inherited from ReaperMCP.

Architecture

┌──────────────┐    stdio    ┌──────────────┐    TCP 3663    ┌──────────────┐
│  MCP Client  │◄──────────►│ FmodStudioMCP│◄──────────────►│ FMOD Studio  │
│(AI assistant)│  (JSON-RPC) │   FastMCP    │  (JS eval)     │ (JS terminal)│
└──────────────┘             └──────────────┘                └──────────────┘

The Python server wraps every tool's command body in a self-evaluating, error-trapping JavaScript IIFE, sends it to the Script Server, and parses the string reply back into a structured result. No cloud. Nothing leaves your machine — Studio and the AI talk over localhost.

Full details — framing, wrapping, safety limits, lifecycle — in docs/ARCHITECTURE.md.

Troubleshooting

Development

pip install -e ".[dev]"
pytest tests/ -x -q
ruff check .

Adding a tool

1. Add a module in fmod_mcp/tools/ (or extend an existing one).
2. Export register(mcp: FastMCP).
3. Define tools with @mcp.tool(), using the client.execute("js body", **params) helper.
4. Add the module name to _EXPECTED_MODULES in tool_registry.py.
5. Every new tool is automatically exercised by the test harness in tests/test_tools_registration.py.

See CONTRIBUTING.md for full guidelines.

License

Apache License 2.0 — see LICENSE for details.

Built by Daniel Hodgetts (@xDarkzx).

Need a custom tool, plugin, or integration built like this? Open an issue.