Skip to content
PixDrive
All articles

PixDrive Studio MCP Setup

Enable the PixDrive Studio MCP server and connect it to Claude Code, Claude Desktop, Cursor or VS Code.

Updated

PixDrive Studio ships with an MCP server. It lets AI assistants such as Claude or Cursor control your light show: start effects, change parameters live, run Lua scripts, build and play sequences.

The server runs only locally on your computer (127.0.0.1), is switched off by default and can be protected with a password.

What is MCP?

The Model Context Protocol is an open standard that lets AI applications use the tools of other programs. You describe in plain language what should happen – the assistant turns that into calls to PixDrive Studio:

“Start a slow rainbow on all fixtures.”

Requirements

  • PixDrive Studio with a license. The MCP server is not available in the demo version.
  • PixDrive Studio is running while the assistant needs access.
  • An MCP client on the same computer, for example Claude Code, Claude Desktop, Cursor or VS Code.
  • For Claude Desktop only: Node.js (LTS version).

1. Enable the server

  1. In the PixDrive Studio toolbar, open Settings (gear icon).
  2. Scroll to the MCP Server section.
  3. Turn on Server active.
  4. Restart PixDrive Studio. The server only starts when the app starts – the note in the settings reminds you.

After the restart the section shows the server address. Use the copy icon next to it to copy it to the clipboard:

http://127.0.0.1:9847/mcp

Without a password, any program on your computer can use the server. With a password, clients must send it with every request.

  1. Enter a password under Password and click Save. It takes effect immediately, no restart needed.
  2. Password then shows “set”. Remove switches the protection off again.

Clients send the password as an HTTP header:

Authorization: Bearer YOUR-PASSWORD

PixDrive Studio never stores the password in plain text, only as a salted SHA-256 hash. If you forget it, simply set a new one and update your client.

The examples below include the header. If you haven’t set a password, leave it out.

3. Connect your assistant

Claude Code

Run in your terminal:

claude mcp add --transport http pixdrive http://127.0.0.1:9847/mcp \
  --header "Authorization: Bearer YOUR-PASSWORD"

Add --scope user to make PixDrive available in all your projects. claude mcp list shows whether the connection works (“Connected”), as does the /mcp command inside Claude Code.

Claude Desktop

Claude Desktop can’t talk to local HTTP servers directly. The connection therefore goes through the small helper mcp-remote, which Node.js downloads automatically on first start.

  1. In Claude Desktop, open Settings → Developer and click Edit Config. The file is located at:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. Add PixDrive (existing entries under mcpServers stay as they are):
{
  "mcpServers": {
    "pixdrive": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:9847/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR-PASSWORD"
      }
    }
  }
}
  1. Quit Claude Desktop completely and start it again.
  2. pixdrive and its tools now appear under Connectors in the message input.

The password deliberately lives in env, with no space after Authorization: – on Windows, spaces inside args would otherwise be passed incorrectly. Without a password, remove the two --header lines and the env block.

Cursor

Create the file ~/.cursor/mcp.json (for all projects) or .cursor/mcp.json in your project folder:

{
  "mcpServers": {
    "pixdrive": {
      "url": "http://127.0.0.1:9847/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-PASSWORD"
      }
    }
  }
}

You can check the connection in Cursor’s settings under MCP or in the Output panel under MCP Logs.

VS Code

Create .vscode/mcp.json in your project, or run MCP: Open User Configuration from the command palette:

{
  "servers": {
    "pixdrive": {
      "type": "http",
      "url": "http://127.0.0.1:9847/mcp",
      "headers": {
        "Authorization": "Bearer YOUR-PASSWORD"
      }
    }
  }
}

Other clients

PixDrive Studio speaks MCP over Streamable HTTP. Any client that supports it connects to http://127.0.0.1:9847/mcp and – if a password is set – sends the header Authorization: Bearer ….

Test the connection without a client

Use curl to check that the server responds:

curl -i -X POST http://127.0.0.1:9847/mcp \
  -H "Authorization: Bearer YOUR-PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

If the response contains pixdrive-studio, everything works. The most common other responses are covered under Troubleshooting.

What the assistant can control

Area What it can do
Effects list available effects, start and stop them, read and change parameters live
Scripts validate Lua scripts and run them as effects, fetch the script guide
Sequence playback play, pause, stop, seek, toggle looping, read the playback state
Sequence editing create sequences; add, change and remove tracks, clips, transitions, keyframes and markers
Devices list devices and fixtures, add or remove Art-Net devices and fixtures, apply the configuration

In total PixDrive Studio provides 36 tools. The server describes each of them itself – your client shows them once connected.

For custom effects, the Script Engine is the best starting point: the assistant fetches the script guide and writes Lua scripts for you.

Example requests

  • “Which effects are there? Start fire on all fixtures.”
  • “Make the running effect half as fast.”
  • “Write a Lua script that flashes white on every beat and start it.”
  • “Create a 60-second sequence with two tracks: rainbow at the beginning, then plasma with a crossfade.”
  • “Which devices are configured?”

Security

  • The server can only be reached from your own computer (127.0.0.1). Other devices on the network can’t use it.
  • Requests with a foreign host name are rejected. This prevents a web page in your browser from reaching the server through a detour.
  • The password protects against other programs on your computer, not against malware already running under your user account.
  • An assistant can start effects, change sequences and adjust device settings. Review what it does before letting it work during a live event.
  • If you don’t use the server, turn Server active off again.

Troubleshooting

The client can’t connect (“connection refused”) – the server isn’t running. Check that Server active is on and that you restarted PixDrive Studio afterwards.

401 Unauthorized – a password is set, but the client sends none or a wrong one. Check the Authorization: Bearer … header in your configuration or set a new password.

403 with “not available in the demo version” – PixDrive Studio is running without a valid license. The MCP server is only available in the full version.

403 with “invalid Host header” – the client uses an address other than 127.0.0.1 or localhost, for example your computer’s network IP. Use http://127.0.0.1:9847/mcp.

Claude Desktop doesn’t show pixdrive – Node.js is missing or the configuration file has an error, such as a missing comma. Check the file, quit Claude Desktop completely and start it again. Details are in the logs under ~/Library/Logs/Claude (macOS) or %APPDATA%\Claude\logs (Windows).

The tools don’t appear although the connection works – restart the client so it reloads the tool list.

The PixDrive Studio log also shows whether the server started: open Help → View Logs in the menu and look for MCP server started on http://127.0.0.1:9847/mcp. The message failed to bind port means another program is already using port 9847.