zotero-mcp-server

An MCP (Model Context Protocol) server for the Zotero Web API v3 — search, read, and write items, collections, tags, and notes in a Zotero library.

Built for use with Claude (or any MCP client), aimed at literature-review workflows: pulling existing references into a "registro maestro," filing newly-found sources back into Zotero, tagging items by theoretical line, and attaching notes.

Tools

This is a focused set covering the core research workflow, not full API coverage. Not included (would need to be added if you need them): saved searches, file uploads, full item updates beyond tags, deletion, group-membership management.

Deep reading: zotero_get_fulltext

This is what lets Claude read an actual PDF's argument, not just its title and abstract. Resolution is automatic:

1. Pass either a parent item's key or an attachment's key directly.

2. Zotero's own server-indexed full text is tried first (fast — works when Zotero desktop has already synced and indexed the PDF).

3. If not indexed, the server downloads the attachment and extracts text locally with a PDF parser.

4. Long documents are paginated via char_offset/char_limit — call again with a higher offset to keep reading.

Limitation: scanned/image-only PDFs without OCR text return little or garbled text. The tool detects this (flags a warning when extracted text is too short for the page count) rather than silently returning garbage, but it cannot OCR a document itself.

Related MCP server: zotero-mcp

1. Get a Zotero API key

1. Go to https://www.zotero.org/settings/keys and create a new private key.

2. Grant it read/write access to the library you want to use (your personal library, and/or specific groups).

3. Note your numeric user ID, shown on the same page — this is not your username.

   • For a group library, the group ID is the number in the group's URL, or from GET https://api.zotero.org/users/<userID>/groups.

2. Configure environment variables

Never commit these values or hardcode them in source — set them as environment variables or secrets in whatever you use to run the server.

3. Build

npm install
npm run build

4. Run

Locally, over stdio (for local MCP clients, e.g. Claude Desktop's local server config):

ZOTERO_API_KEY=... ZOTERO_LIBRARY_TYPE=user ZOTERO_LIBRARY_ID=... node dist/index.js

As a remote server, over Streamable HTTP (needed to add it as a custom connector in claude.ai):

TRANSPORT=http PORT=3000 \
ZOTERO_API_KEY=... ZOTERO_LIBRARY_TYPE=user ZOTERO_LIBRARY_ID=... \
node dist/index.js

This exposes POST /mcp (the MCP endpoint) and GET /health (a plain liveness check). Deploy it somewhere reachable over HTTPS (Render, Fly.io, Railway, a small VM behind a reverse proxy with TLS, etc.) — claude.ai's custom connector setup needs a public https:// URL, not localhost.

A Dockerfile is included, so any of the platforms below can build and run it with no extra configuration beyond setting environment variables.

Deploying to a public HTTPS endpoint

Pick one. Render is the easiest if you don't mind pushing to GitHub; Fly.io is the easiest if you'd rather stay in a terminal.

Option A — Render (dashboard, needs a GitHub repo)

1. Push this project (this whole folder) to a new GitHub repository.

2. In the Render dashboard, click New → Web Service and connect that repository.

3. Render will detect the Dockerfile automatically — leave Environment as Docker. Leave build/start commands blank (the Dockerfile handles both).

4. Under Environment Variables, add:

   • ZOTERO_API_KEY

   • ZOTERO_LIBRARY_TYPE (user or group)

   • ZOTERO_LIBRARY_ID

   • (TRANSPORT=http is already set inside the Dockerfile — no need to add it.)

5. Click Create Web Service. Render builds the image and deploys it; this takes a few minutes the first time.

6. Once live, Render shows a URL like https://zotero-mcp-server.onrender.com. Your MCP endpoint is https://zotero-mcp-server.onrender.com/mcp.

7. Sanity check: curl https://zotero-mcp-server.onrender.com/health should return {"status":"ok"}.

Free-tier note: Render's free web services sleep after inactivity and take a few seconds to wake on the next request — fine for testing, worth upgrading if you'll use this daily.

Option B — Fly.io (CLI, no GitHub needed)

1. Install the CLI: curl -L https://fly.io/install.sh | sh (or see fly.io/docs/flyctl).

2. fly auth login

3. From inside the zotero-mcp-server folder: fly launch

   • It detects the Dockerfile and proposes an app name and region — accept or edit.

   • Say no to adding a Postgres/Redis database (not needed).

   • Say no to deploying immediately if it asks — set secrets first (next step).

4. Set your credentials as secrets (never as plain fly.toml values):

   fly secrets set ZOTERO_API_KEY=your_key ZOTERO_LIBRARY_TYPE=user ZOTERO_LIBRARY_ID=your_id

5. Open the generated fly.toml and confirm internal_port = 3000 under [http_service] (it should be auto-detected from the Dockerfile's EXPOSE 3000; fix it manually if not).

6. Deploy: fly deploy

7. Your MCP endpoint is https://<your-app-name>.fly.dev/mcp. Check https://<your-app-name>.fly.dev/health.

Option C — Railway (CLI or dashboard)

1. Install the CLI (npm install -g @railway/cli) or use the Railway dashboard connected to a GitHub repo — same idea as Render.

2. CLI path: railway login, then from the project folder railway init and railway up. Railway detects the Dockerfile automatically.

3. Set env vars: railway variables set ZOTERO_API_KEY=... ZOTERO_LIBRARY_TYPE=user ZOTERO_LIBRARY_ID=... (or via the dashboard's Variables tab).

4. Railway services aren't public by default — go to Settings → Networking → Generate Domain to get a public https://your-app.up.railway.app URL.

5. MCP endpoint: https://your-app.up.railway.app/mcp.

Option D — Self-hosted VM (full control, more steps)

1. Provision a small Ubuntu 22.04+ VM (DigitalOcean, Linode, a spare EC2 instance, etc.) and point a DNS A record at its IP, e.g. zotero-mcp.yourdomain.com.

2. SSH in and install Node 20 and Caddy (Caddy handles HTTPS automatically via Let's Encrypt — much less setup than nginx + certbot):

   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash -
   sudo apt-get install -y nodejs
   sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https
   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
   curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
   sudo apt-get update && sudo apt-get install -y caddy

3. Copy the project to the VM (scp the zip, then unzip) and build:

   cd zotero-mcp-server && npm install && npm run build

4. Create /etc/systemd/system/zotero-mcp.service:

   [Unit]
   Description=Zotero MCP server
   After=network.target
   
   [Service]
   Environment=TRANSPORT=http
   Environment=PORT=3000
   Environment=ZOTERO_API_KEY=your_key
   Environment=ZOTERO_LIBRARY_TYPE=user
   Environment=ZOTERO_LIBRARY_ID=your_id
   ExecStart=/usr/bin/node /home/youruser/zotero-mcp-server/dist/index.js
   Restart=always
   User=youruser
   
   [Install]
   WantedBy=multi-user.target

   Then: sudo systemctl daemon-reload && sudo systemctl enable --now zotero-mcp

5. Point Caddy at it — edit /etc/caddy/Caddyfile:

   zotero-mcp.yourdomain.com {
       reverse_proxy localhost:3000
   }

   Then: sudo systemctl reload caddy. Caddy fetches a TLS certificate automatically on first request.

6. Check https://zotero-mcp.yourdomain.com/health. MCP endpoint: https://zotero-mcp.yourdomain.com/mcp.

Actualizar un despliegue ya existente

Ya tienes esto corriendo en Render con un repositorio en GitHub — actualizar es mucho más simple que el despliegue inicial, no hay que tocar Render para nada:

1. Descomprime el nuevo .zip en tu computadora, igual que la primera vez.

2. Ve a tu repositorio en GitHub (zotero-mcp-server-v2 o el nombre que le hayas puesto).

3. Add file → Upload files, y arrastra TODO el contenido de la carpeta descomprimida — igual que la vez pasada. GitHub reemplaza automáticamente los archivos que ya existían (por ejemplo package.json, src/index.ts) y agrega los nuevos (src/tools/fulltext.ts).

4. Commit changes.

5. Eso es todo — Render detecta el cambio en GitHub y vuelve a desplegar solo, normalmente en 3-8 minutos. No hace falta volver a tocar las variables de entorno ni ninguna otra configuración de Render.

6. Verifica en el panel de Render que el nuevo deploy diga "Live" antes de probar las herramientas nuevas.

5. Connect it to Claude

Once deployed and reachable over HTTPS:

1. In claude.ai, go to Settings → Connectors → Add custom connector.

2. Enter the deployed URL, e.g. https://your-deployment.example.com/mcp.

3. Claude will discover the 9 tools above automatically.

For Claude Desktop with a local stdio server instead, add an entry to its MCP server config pointing at node /absolute/path/to/dist/index.js, with the environment variables from step 2 set in that config.

Testing

npx @modelcontextprotocol/inspector node dist/index.js

This opens a local UI to call each tool by hand before wiring it up to Claude.

Notes on the Zotero API this server relies on

• Auth: Zotero-API-Key header, per request.

• Versioning for writes: zotero_update_item_tags reads the item's current version before patching, and sends it via If-Unmodified-Since-Version — if the item changed elsewhere in the meantime, Zotero returns 412 and the tool reports it clearly instead of silently overwriting.

• Rate limits: Zotero may return 429 with a Retry-After header, or a Backoff header on any response. This server surfaces both as actionable error text; it does not currently auto-retry.

• Item creation fetches the field template for the requested itemType from GET /items/new first, so only valid fields for that type are sent.

Official API docs: https://www.zotero.org/support/dev/web_api/v3/