Zotero Assistant MCP — Remote (Cloudflare Workers)

A remote MCP server for reading, writing, and managing items in your Zotero library, deployed on Cloudflare Workers. Each user deploys their own server to their own Cloudflare account — no shared infrastructure, no cost beyond Cloudflare's generous free tier.

Quick Start

You'll need Node.js 18+, a Zotero account, and a Cloudflare account (free tier — no credit card required).

git clone https://github.com/upascal/zotero-assistant-mcp-remote.git
cd zotero-assistant-mcp-remote
npm install
npm run setup

This opens a browser-based setup wizard that walks you through:

Zotero credentials — Enter your Library ID and API key (with a "Test Connection" button to verify)
Cloudflare login — The wizard detects if you're already logged in. If not, it opens the Cloudflare login page for you.
Deploy — One click deploys the Worker, sets your secrets, and generates a secure bearer token.

After deployment, the wizard shows your secure MCP URL and gives you three ways to connect:

| Method | Best for | |--------|----------| | Claude Desktop UI | Paste a single URL into Settings → Connectors → Add custom connector | | JSON Config | Manually edit claude_desktop_config.json | | Claude Code CLI | Run a claude mcp add-json command in your terminal |

Screenshots

<img src="assets/1-configure-credentials.png" alt="Configure Credentials" width="600"/> <text>Enter your Zotero credentials. You can find your Library ID and API key in your Zotero account settings. Click "Deploy" to and follow the instructions add the remote MCP server to Claude Desktop.</text>

<img src="assets/2-connection-to-claude-instructions.png" alt="Connection to Claude Instructions" width="600"/> <text>Follow the instructions to connect to Claude Desktop.</text> <img src="assets/3-claude-desktop-configuration.png" alt="Claude Desktop Configuration" width="600"/> <text> Add the remote MCP server to Claude Desktop. You can find your MCP URL in the setup wizard after deployment. </text>

Optional Settings

<img src="assets/4-configure-mcp-server-settings.png" alt="Configure MCP Server Settings" width="600"/> <img src="assets/5-turn-on-always-allow.png" alt="Turn on Always Allow" width="600"/> <text>Turn on "Always allow" for the Zotero Assistant MCP server to avoid having to approve every request.</text>

Manual Setup (Advanced)

If you prefer to configure everything yourself without the setup wizard, or want to develop locally. Start by cloning and installing as shown in the Quick Start.

1. Configure local development credentials

Create a .dev.vars file with your Zotero credentials:

ZOTERO_API_KEY=your-api-key-here
ZOTERO_LIBRARY_ID=your-library-id-here
BEARER_TOKEN=any-secret-token-for-local-dev

2. Run locally

npm run dev

The server starts at http://localhost:8787/mcp.

3. Deploy to Cloudflare

# Login to Cloudflare (if not already)
npx wrangler login

# Deploy the worker
npm run deploy

# Set production secrets
npx wrangler secret put ZOTERO_API_KEY
npx wrangler secret put ZOTERO_LIBRARY_ID
npx wrangler secret put BEARER_TOKEN

4. Connect from Claude

Option A: Claude Desktop UI (recommended)

Use the token-in-URL format so you can paste a single URL with no advanced settings:

https://zotero-assistant-mcp.<your-subdomain>.workers.dev/mcp/t/<your-bearer-token>

Open Claude Desktop → Settings → Connectors
Click "Add custom connector"
Set name to Zotero Assistant
Paste the URL above
Click "Add"

Option B: JSON Config

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "zotero": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://zotero-assistant-mcp.<your-subdomain>.workers.dev/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer <your-bearer-token>"
      }
    }
  }
}

Option C: Claude Code CLI

claude mcp add-json zotero '{"type":"http","url":"https://zotero-assistant-mcp.<your-subdomain>.workers.dev/mcp","headers":{"Authorization":"Bearer <your-bearer-token>"}}'

Local Server (Alternative)

If you don't want to deploy to Cloudflare, you can run the MCP server locally as a stdio subprocess. No cloud account needed — just your Zotero credentials.

Claude Desktop config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "zotero": {
      "command": "npx",
      "args": ["zotero-assistant-mcp"],
      "env": {
        "ZOTERO_API_KEY": "your-api-key-here",
        "ZOTERO_LIBRARY_ID": "your-library-id-here"
      }
    }
  }
}

Claude Code CLI

claude mcp add zotero -- npx zotero-assistant-mcp \
  --env ZOTERO_API_KEY=your-api-key \
  --env ZOTERO_LIBRARY_ID=your-library-id

Get your credentials

Go to zotero.org/settings/keys
Create a new API key with read/write access
Your Library ID is shown on the same page (it's the number in your profile URL)

Using as a library

The zotero-assistant-mcp package can be imported by other projects to build custom integrations:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerTools } from "zotero-assistant-mcp";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
registerTools(server, { apiKey: "...", libraryId: "..." });

// Connect to any transport you want

The Zotero API functions are also exported individually:

import { searchItems, createItem, getItem } from "zotero-assistant-mcp";

const results = await searchItems(apiKey, libraryId, { query: "machine learning" });

Security

Every MCP endpoint is protected by a bearer token. The server supports two authentication methods:

Token in URL path — /mcp/t/{token} (convenient for Claude Desktop's connector UI)
Bearer header — Authorization: Bearer {token} (standard HTTP auth for API/CLI usage)

Unauthenticated requests to /mcp return 401 Unauthorized.

Your Zotero API key and bearer token are stored as Cloudflare Worker secrets — they are encrypted at rest and never exposed in logs or source code.

Keep your MCP URL and bearer token private. Anyone with the token can read and write to your Zotero library.

Cloudflare Account FAQ

Do I need a paid Cloudflare plan? No. The Workers Free plan includes 100,000 requests per day — more than enough for personal MCP usage. No credit card is required to sign up.

How does the setup wizard detect my Cloudflare account? The wizard runs wrangler whoami behind the scenes, which checks for a locally stored OAuth token from a previous wrangler login. It's the same mechanism the Wrangler CLI uses — no passwords are stored by the setup wizard.

What if I don't have a Cloudflare account? The wizard will show a "Not logged in" status in Step 3. Click "Login to Cloudflare" — this runs wrangler login, which opens the Cloudflare website in your browser. From there you can either sign in or create a free account. Once authenticated, the wizard detects your login automatically and you can proceed to deploy.

Can I sign up with GitHub/Google? Yes. Cloudflare supports email, Google, and Apple sign-in. When wrangler login opens your browser, you can use any of these methods to create or access your account.

Available Tools (18)

| Category | Tool | Description | |----------|------|-------------| | Utility | get_help | Workflow instructions | | Utility | get_item_types | List valid item types | | Utility | prepare_url | Get fetch instructions for a URL | | Search | search_items | Search by text, tags, type, or collection | | Search | get_collection_items | List items in a collection | | Search | get_recent_items | Recently added/modified items | | Search | list_collections | All collections (folders) | | Search | create_collection | Create a new collection | | Search | list_tags | All tags in library | | Read | get_item | Full metadata + children for an item | | Read | get_item_fulltext | Extracted text content | | Read | get_attachment_content | Read snapshot HTML or attachment files | | Read | get_library_stats | Library overview with counts and top tags | | Write | save_item | Create new item with metadata | | Write | attach_pdf | Attach PDF to existing item | | Write | attach_snapshot | Attach webpage snapshot | | Write | create_note | Create note on existing item | | Write | update_item | Modify metadata/tags |

Project Structure

packages/
├── mcp/          # zotero-assistant-mcp — pure MCP library + stdio CLI
│   ├── src/
│   │   ├── index.ts    # registerTools() + re-exports
│   │   └── zotero.ts   # Zotero API wrapper
│   ├── bin/cli.ts      # npx zotero-assistant-mcp
│   └── tests/
└── deploy/       # Cloudflare Workers deployer
    ├── src/
    │   └── index.ts    # Worker entry (McpAgent + auth)
    ├── setup/          # Browser-based setup wizard (npm run setup)
    └── wrangler.jsonc

Testing with MCP Inspector

npm run dev  # in one terminal

# in another terminal:
npx @modelcontextprotocol/inspector@latest

Open http://localhost:5173 and connect to http://localhost:8787/mcp.

License

MIT

Zotero Assistant MCP Remote