Zotero Assistant Remote

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:

1. Zotero credentials — Enter your Library ID and API key (with a "Test Connection" button to verify)
2. Cloudflare login — The wizard detects if you're already logged in. If not, it opens the Cloudflare login page for you.
3. 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>

1. Open Claude Desktop → Settings → Connectors
2. Click "Add custom connector"
3. Set name to Zotero Assistant
4. Paste the URL above
5. 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

1. Go to zotero.org/settings/keys
2. Create a new API key with read/write access
3. 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:

1. Token in URL path — /mcp/t/{token} (convenient for Claude Desktop's connector UI)
2. 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