zotero-filelink-bridge

name	zotero-filelink-bridge
description	Use Zotero FileLink Bridge to attach existing local files to Zotero parent items as linked-file attachments. Trigger when asked to link a local file into Zotero, attach generated files without copying them into Zotero storage, test the bridge, or automate Zotero linked-file attachment creation from Windows, WSL, or an AI-agent workflow.

Zotero FileLink Bridge

Use this skill when a file already exists on local disk and should appear under a Zotero item as a linked-file attachment. The file can be generated by OCR, PDF conversion, a language model, a script, or manual editing. This skill is not limited to Markdown or any single extraction tool.

Do not use this skill for importing URLs, copying files into Zotero storage, or attaching directories. If a workflow produces a directory, link the entry file that should open from Zotero and keep any sibling assets in place.

Preconditions

• Zotero is running with the Zotero FileLink Bridge plugin installed.
• The bridge exposes GET /ping and POST /link-file on port 23121.
• You know the target Zotero parent item, preferably itemKey and libraryID.
• The local file exists and will remain at that path.

Connect

Windows-native agents can usually use:

Invoke-RestMethod "http://127.0.0.1:23121/ping"

POSIX-style shells on the same machine can use:

ZOTERO_BRIDGE_BASE=http://127.0.0.1:23121
curl "$ZOTERO_BRIDGE_BASE/ping"

WSL agents should use the Windows NAT gateway:

export ZOTERO_BRIDGE_HOST=$(ip route | awk '/default/ {print $3; exit}')
export ZOTERO_BRIDGE_BASE="http://$ZOTERO_BRIDGE_HOST:23121"
curl "$ZOTERO_BRIDGE_BASE/ping"

Do not assume WSL 127.0.0.1:23121 reaches Windows Zotero.

Link Workflow

1. Resolve the parent Zotero item.
2. Confirm the local file path.
3. Run a dry run.
4. Check parent title, resolved path, fileExists, canLink, and duplicate fields.
5. Only write after the dry run is correct.
6. Verify the new child attachment when possible.

Dry run:

curl -X POST "$ZOTERO_BRIDGE_BASE/link-file" \
  -H 'Content-Type: application/json' \
  -d '{
    "itemKey": "ITEMKEY",
    "libraryID": 1,
    "filePath": "/path/to/local/file.ext",
    "title": "Readable attachment title",
    "dryRun": true
  }'

Create the linked attachment:

curl -X POST "$ZOTERO_BRIDGE_BASE/link-file" \
  -H 'Content-Type: application/json' \
  -d '{
    "itemKey": "ITEMKEY",
    "libraryID": 1,
    "filePath": "/path/to/local/file.ext",
    "title": "Readable attachment title"
  }'

Path Rules

• Windows paths such as C:\Users\you\Documents\output.html are accepted.
• WSL paths such as /mnt/c/Users/you/Documents/output.html are converted for Windows Zotero.
• attachments:relative/path/file.ext is resolved against Zotero's linked attachment base directory.
• Pass a file path, not a directory path.
• If a file depends on sibling assets, keep those assets in the same relative layout. A linked attachment points to the original file location.

Tool Combinations

• Use Zotero MCP or another Zotero automation tool to find parent item metadata.
• Use any file-producing tool to create the local file: OCR, document extraction, Markdown conversion, HTML export, LLM-generated reports, or scripts.
• Use Zotero FileLink Bridge only for the final linked-file attachment step.

Safety

This is a write-capable local endpoint. Never expose it to untrusted networks. Always use dryRun: true before write operations, especially in batches.