Local Bridge

Hosted assistants can't see the files on your computer. The local bridge closes that gap. It is a small open-source program (@panelwave/mcp, MIT license) that your desktop assistant starts in the background. It passes every PanelWave tool through unchanged and adds three tools that work on folders you allow:

The files go straight from your computer to PanelWave's storage. They never pass through the AI model, so large videos are no problem.

The bridge is published on npm as @panelwave/mcp (MIT license); the source is in panelwave/packages. npx downloads it on first use, so there is nothing to install by hand.

Set it up

{
  "mcpServers": {
    "panelwave": {
      "command": "npx",
      "args": ["-y", "@panelwave/mcp"],
      "env": {
        "PANELWAVE_TOKEN": "pw_pat_…",
        "PANELWAVE_ALLOWED_DIRS": "/Users/me/comics"
      }
    }
  }
}

claude mcp add panelwave \
  --env PANELWAVE_TOKEN=pw_pat_… \
  --env PANELWAVE_ALLOWED_DIRS="$HOME/comics" \
  -- npx -y @panelwave/mcp

{
  "mcpServers": {
    "panelwave": {
      "command": "npx",
      "args": ["-y", "@panelwave/mcp"],
      "env": { "PANELWAVE_TOKEN": "pw_pat_…", "PANELWAVE_ALLOWED_DIRS": "/Users/me/comics" }
    }
  }
}

If you use the bridge, you don't need the remote PanelWave connector in the same client as well. The bridge already includes all its tools.

Settings

From a script and a folder to a work

Say your folder comics/rooftop holds script.md and a panels folder with panel-01.png to panel-12.png. Ask the assistant step by step:

1. "Read rooftop/script.md and turn it into a PanelWave work, one panel per shot, with mobile and A4 pages." It reads the script, drafts an outline, shows you a dry run, and creates the work.
2. "Upload rooftop/panels into that work, into a folder called Panels." Files already in your library are reused, so repeating this after an interruption only uploads what is missing.
3. "Attach panel-01 to the first panel, panel-02 to the second, and so on." Each panel fits itself to its image on every page format.
4. "Check the work." The validation lists anything still missing. Open the work in the editor to review it.

How uploads behave

• No duplicates. Each file is fingerprinted first. Files already in the library, or twice in one batch, are not uploaded again.
• Resumable. If an upload fails, run it again. Finished files are recognised and skipped.
• Large files in parts. Files of 10 MB or more upload in parts, and each part is retried on failure.
• Folders. Name a folder such as Chapter 1/Panels; missing folders are created.
• Warnings. The result lists each file with its status and warnings, for example an image over 5 MB that needs optimizing before publishing. Validation can fix that for you.

Troubleshooting

For developers

• Errors come back as tool results with isError: true and { code, message }. The bridge's own codes are UNAUTHENTICATED (token rejected), UPSTREAM_UNAVAILABLE (PanelWave or storage unreachable), INVALID_INPUT (for example a path outside the allowed folders), NOT_FOUND and PRECONDITION_FAILED (for example a binary file for pw_local_read_text). Codes of the hosted tools, such as QUOTA_EXCEEDED or PERMISSION_DENIED, pass through unchanged, also inside upload rows.
• Options: pw_local_read_text cuts files at 1 MiB and flags them truncated (maxBytes up to 5 MiB). pw_local_upload_files takes folderName, tags, concurrency (3 by default, up to 6) and skipDuplicates: false to get a CONFLICT row instead of reusing an existing asset.
• Security: PANELWAVE_MCP_URL must use https (plain http only for localhost). Paths are checked as text before the file system is touched, and network paths such as \\server\share are refused. The token is sent only to the PanelWave server, never to the storage upload URLs, and uploads go only to https storage.
• panelwave-mcp --version prints the version and --help a short usage. Diagnostics go to stderr, which your client shows in its MCP log.

Related pages