PixDrive Studio MCP Setup

PixDrive Studio ships with an MCP server. It lets AI assistants such as Claude or Cursor control your light show: start and adjust effects live, write Lua scripts, build sequences and set up devices.

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

2. Set a password (recommended)

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.

If you haven’t set a password, switch Password off in the examples below – the header then disappears from the code.

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"

claude mcp add --transport http pixdrive http://127.0.0.1:9847/mcp

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"
      }
    }
  }
}

{
  "mcpServers": {
    "pixdrive": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:9847/mcp"
      ]
    }
  }
}

3. Quit Claude Desktop completely and start it again.
4. 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.

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"
      }
    }
  }
}

{
  "mcpServers": {
    "pixdrive": {
      "url": "http://127.0.0.1:9847/mcp"
    }
  }
}

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"
      }
    }
  }
}

{
  "servers": {
    "pixdrive": {
      "type": "http",
      "url": "http://127.0.0.1:9847/mcp"
    }
  }
}

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"}}}'

curl -i -X POST http://127.0.0.1:9847/mcp \
  -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

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

A few things worth knowing:

• Checking the result: the assistant can read the colors being output and check for itself whether an effect looks as intended.
• Saving the project only works once the project has been saved in PixDrive Studio at least once and therefore has a file.
• Exports are not available over MCP. Once the assistant has built the sequence, you export it yourself in the app, see Advatek SHOWTime Export and TPM2 Export. The assistant can still set up the controller ports for the SHOWTime export.

For custom effects, the Script Engine is the best starting point: the assistant fetches the script guide, writes Lua scripts for you and keeps the good ones in your script library.

Example requests

• “Which effects are there? Start fire on all fixtures.”
• “Make the running effect half as fast and dim everything to 30%.”
• “Start audio capture and write a Lua script that flashes white on every beat.”
• “Create a 60-second sequence: rainbow at the beginning, then plasma with a crossfade. Save it as a show preset.”
• “Scan the network for Art-Net controllers and set up a 16 × 16 pixel matrix on the first one.”
• “Place the two strips side by side on the canvas, 50 cm apart.”

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 device settings and save your project. 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.