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

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.

Follow the instructions to connect to Claude Desktop.

Add the remote MCP server to Claude Desktop. You can find your MCP URL in the setup wizard after deployment.

Optional Settings

Turn on "Always allow" for the Zotero Assistant MCP server to avoid having to approve every request.

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

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
assets		assets
packages		packages
release-assets		release-assets
setup		setup
src		src
tests/integration		tests/integration
.DS_Store		.DS_Store
.gitignore		.gitignore
README.md		README.md
mcp-deploy.json		mcp-deploy.json
package-lock 2.json		package-lock 2.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts
worker-configuration.d.ts		worker-configuration.d.ts
worker.mjs		worker.mjs
wrangler.jsonc		wrangler.jsonc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Zotero Assistant MCP — Remote (Cloudflare Workers)

Quick Start

Screenshots

Optional Settings

Manual Setup (Advanced)

1. Configure local development credentials

2. Run locally

3. Deploy to Cloudflare

4. Connect from Claude

Local Server (Alternative)

Claude Desktop config

Claude Code CLI

Get your credentials

Using as a library

Security

Cloudflare Account FAQ

Available Tools (18)

Project Structure

Testing with MCP Inspector

License

About

Uh oh!

Releases 4

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Zotero Assistant MCP — Remote (Cloudflare Workers)

Quick Start

Screenshots

Optional Settings

Manual Setup (Advanced)

1. Configure local development credentials

2. Run locally

3. Deploy to Cloudflare

4. Connect from Claude

Local Server (Alternative)

Claude Desktop config

Claude Code CLI

Get your credentials

Using as a library

Security

Cloudflare Account FAQ

Available Tools (18)

Project Structure

Testing with MCP Inspector

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages