ptsl-mcp-server

An MCP server that lets AI assistants (Claude Code, Claude Desktop, any MCP client) drive Avid Pro Tools through the PTSL scripting API.

It differs from other Pro Tools MCP servers in one point: it knows every PTSL command. The command list, parameters and enum values are read from the protobuf definition that ships with py-ptsl, so any command Pro Tools understands can be described and executed, including the ones py-ptsl has no Python wrapper for.

Experimental. Write commands modify the open session. Use the read-only mode if you only want to inspect.

Features

• Generic access to all PTSL commands: list_commands, describe_command, run_command cover the whole CommandId enum (159 commands with PTSL 2026). Parameters are plain JSON; enums by name or number; nested messages as objects.

• Convenience tools for the common session loop: create, open, save, save as, close; create tracks; import audio; Session Info as Text as a string (no file dialog); set the session start timecode.

• Hard timeouts on every call. py-ptsl does not pass a gRPC deadline, so a modal dialog in Pro Tools (missing plug-in, playback engine, sample-rate mismatch) would block forever. This server injects a deadline and reports a stuck Pro Tools as TIMEOUT instead of hanging the assistant.

• Serialized calls and automatic reconnect after a gRPC failure.

• Path mapping for the setup where Pro Tools runs on another machine and the shared volume is mounted under different paths on each side. Every path field is translated in both directions; paths outside the configured root are rejected.

• Read-only mode (PTSL_MCP_READ_ONLY=1) refuses every command that can change a session, in the convenience tools and in run_command.

• stdio-safe: the py-ptsl CreateSessionBuilder prints its request to stdout, which corrupts a stdio MCP transport. The server builds the request itself. It also fixes py-ptsl's audio import, which sends the wrong import type.

Related MCP server: ableton-mcp

Requirements

• A Pro Tools version that ships the PTSL scripting server (introduced with Pro Tools 2022.9). Tested with Pro Tools 2026.4 (PTSL version 2026).

• Python 3.10+

• py-ptsl, mcp, grpcio, protobuf (installed automatically)

Installation

pip install git+https://github.com/ruehljens-creator/ptsl-mcp-server

or from a clone:

git clone https://github.com/ruehljens-creator/ptsl-mcp-server
cd ptsl-mcp-server
pip install -e .

Check that the package is installed and see the registered tools:

ptsl-mcp-server --list-tools

If the ptsl-mcp-server script is not on your PATH (common with framework Python installs on macOS), use python3 -m ptsl_mcp.server everywhere the examples say ptsl-mcp-server.

Configuration

Everything is set through environment variables.

If both roots are unset, paths are passed through unchanged (Pro Tools on the same machine). If both are set, every path is translated; setting only one is an error.

Claude Code

Add to .mcp.json in your project (see examples/):

{
  "mcpServers": {
    "ptsl": {
      "command": "ptsl-mcp-server",
      "env": { "PTSL_ADDRESS": "localhost:31416" }
    }
  }
}

Or from the command line:

claude mcp add ptsl -- ptsl-mcp-server

Claude Desktop

Add the same block to claude_desktop_config.json.

Tools

Diagnostics

Session workflow

Generic

Example, run from an assistant:

describe_command("CreateNewTracks")
run_command("CreateNewTracks", {"number_of_tracks": 2, "track_name": "Dialog",
            "track_format": "TF_Mono", "track_type": "TT_Audio",
            "track_timebase": "TTB_Samples"})
run_command("GetSessionSampleRate")

Safety notes

• Pro Tools shows modal dialogs on session open (missing plug-ins, playback engine, sample-rate mismatch) that are invisible over PTSL. The server reports these as timeouts; someone has to dismiss the dialog in Pro Tools.

• create_session closes the currently open session without asking. Save it first.

• The read-only classification in run_command is by command name (Get*, HostReadyCheck, ExportSessionInfoAsText, connection commands). Everything else is treated as a write.

Development

ptsl-mcp-server --list-tools      # registered MCP tools
ptsl-mcp-server --list-commands   # all PTSL command names

License

MIT, see LICENSE.