zotero-curator 0.1.1

Research-focused MCP server and setup helper for Zotero

Curator for Zotero

Curator for Zotero is a research-focused MCP server for Zotero. It lets AI coding and research assistants search your library, inspect metadata, read indexed attachment text in manageable chunks, navigate outlines/sections, and safely organize items with dry-run-first write tools.

This project is independently maintained and is based on the MIT-licensed kujenga/zotero-mcp. See ACKNOWLEDGEMENTS.md and LICENSE.

Why this repo exists

The original Python MCP server was useful but awkward to configure across Codex, Claude Desktop, Cursor, Claude Code, and other clients because each app needed a hand-maintained virtualenv path. Curator fixes that by making the server a normal published Python tool that clients can launch with uvx:

uvx --from zotero-curator zotero-curator serve

That command lets each MCP client start its own stdio server process without knowing about a local checkout path, a repo-local .venv, or per-app shell setup.

Recommended install: uvx

Install uv once, then configure Curator through the published package:

uvx --from zotero-curator zotero-curator setup --local
uvx --from zotero-curator zotero-curator doctor

uvx keeps Python environments out of Claude/Codex/Cursor config files. It resolves and caches the published zotero-curator package, then runs the requested console command.

For GUI-launched clients on macOS, prefer the absolute uvx path from:

command -v uvx

Common Homebrew paths are /opt/homebrew/bin/uvx on Apple Silicon and /usr/local/bin/uvx on Intel macOS.

Optional persistent install:

uv tool install zotero-curator
zotero-curator setup --local
zotero-curator doctor

Let an agent set it up

Copy this prompt into Codex, Claude Code, Cursor, or another local coding agent:

Install Curator for Zotero for me by following this repo's AGENTS.md. Use the published uvx workflow and configure these MCP clients: CLIENTS_TO_CONFIGURE.

Replace CLIENTS_TO_CONFIGURE with the clients you use, for example Claude Desktop and Codex.

From a local checkout:

uv sync --extra dev
uv run zotero-curator doctor
uv run pytest
uv run ruff check .

Zotero local API setup

1. Open Zotero.
2. Go to Settings → Advanced → Allow other applications on this computer to communicate with Zotero.
3. Run:

uvx --from zotero-curator zotero-curator setup --local
uvx --from zotero-curator zotero-curator doctor

Local mode uses library id 0 and does not require an API key.

Web API setup

uvx --from zotero-curator zotero-curator setup --web --library-id YOUR_LIBRARY_ID --api-key YOUR_API_KEY

For group libraries, add --library-type group.

MCP client config

Recommended uvx config for Claude Desktop, Cursor, and other JSON-style MCP clients:

{
  "mcpServers": {
    "zotero": {
      "command": "/opt/homebrew/bin/uvx",
      "args": [
        "--from",
        "zotero-curator",
        "zotero-curator",
        "serve"
      ]
    }
  }
}

Replace /opt/homebrew/bin/uvx with the output of command -v uvx on your machine.

Recommended uvx config for Codex:

[mcp_servers.zotero]
type = "stdio"
command = "/opt/homebrew/bin/uvx"
args = ["--from", "zotero-curator", "zotero-curator", "serve"]
startup_timeout_sec = 30

If you prefer a pinned release, pin the package in the --from argument:

args = ["--from", "zotero-curator==0.1.0", "zotero-curator", "serve"]

Installed-tool fallback:

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-curator",
      "args": ["serve"]
    }
  }
}

Generate config snippets:

uvx --from zotero-curator zotero-curator mcp-config --uvx --format json
uvx --from zotero-curator zotero-curator mcp-config --uvx --format toml

Current workflow note: setup writes Curator's central Zotero settings and prints client config snippets. mcp-config only prints JSON/TOML. Neither command edits Claude, Codex, Cursor, or other client config files yet. A future install-client or client-config apply command should detect known config paths, back up existing files, merge the zotero MCP server entry, support --dry-run, and preserve user-managed settings.

Release instructions are in docs/release.md. Claude Desktop MCPB bundle notes are in docs/mcpb.md.

Add arXiv papers

Curator can create a Zotero preprint item directly from an arXiv id, abstract URL, or PDF URL:

uvx --from zotero-curator zotero-curator add-arxiv https://arxiv.org/abs/2410.03529

The command is dry-run-first. To apply it, configure Web API mode with a write-enabled API key, enable writes globally, and pass --apply:

uvx --from zotero-curator zotero-curator setup --web --library-id YOUR_LIBRARY_ID --api-key YOUR_WRITE_ENABLED_API_KEY --write-enabled
uvx --from zotero-curator zotero-curator add-arxiv 2410.03529 --tag AI --collection COLLECTION_KEY --apply

This imports arXiv metadata first and stores the PDF as a Zotero file attachment by default. Use --link-pdf to attach only the arXiv PDF URL, --no-pdf to create only the metadata item, or --pdf-mode {stored,linked,none} for explicit control.

Settings

Curator stores central settings in the platform config directory. Print the exact path with:

uvx --from zotero-curator zotero-curator setup-info

On macOS this is typically:

~/Library/Application Support/zotero-curator/config.toml

On many Linux systems this is typically:

~/.config/zotero-curator/config.toml

Example:

[zotero]
local = true
library_type = "user"
library_id = "0"
write_enabled = false
response_format = "markdown"

Environment variables override file settings:

Variable	Purpose
ZOTERO_LOCAL	true for local API, false for Web API
ZOTERO_LIBRARY_ID	Zotero user/group library id
ZOTERO_LIBRARY_TYPE	user or group
ZOTERO_API_KEY	Zotero Web API key
ZOTERO_WRITE_ENABLED	Enable non-dry-run write tools
ZOTERO_CURATOR_CONFIG	Override settings file path
ZOTERO_CURATOR_CONFIG_DIR	Override settings directory

Tools

Read/navigation:

• zotero_healthcheck
• zotero_diagnostics
• zotero_search_items
• zotero_find_item_by_doi
• zotero_item_metadata
• zotero_item_fulltext
• zotero_item_fulltext_info
• zotero_pdf_pages (pdf extra)
• zotero_pdf_outline (pdf extra)
• zotero_item_text_chunk
• zotero_item_search_text
• zotero_item_outline
• zotero_item_read_section
• zotero_item_children
• zotero_list_collections
• zotero_collection_items
• zotero_list_tags
• zotero_semantic_rebuild (semantic extra)
• zotero_semantic_search (semantic extra)

Write/organization tools are dry-run-first and additionally require write_enabled = true for real changes:

• zotero_write_status
• zotero_add_arxiv
• zotero_create_collection
• zotero_rename_collection
• zotero_delete_collection
• zotero_update_item_tags
• zotero_update_item_collections
• zotero_update_item_metadata
• zotero_create_child_note
• zotero_apply_organization_plan

Safety model

Write tools default to dry_run=true. Real write calls require all of the following:

1. Web API mode: local = false.
2. A Zotero API key with write access.
3. write_enabled = true in settings, or ZOTERO_WRITE_ENABLED=true.
4. The individual tool call sets dry_run=false.

The Zotero local API is treated as read-only by Curator because Zotero's Local API v3 documentation says: "Write requests are currently unsupported. Only GET is accepted." Local mode can be used for reads and dry-runs, but Curator blocks non-dry-run write tools before they call Zotero. This keeps the implementation aligned with the current API protocol and makes it easy to re-enable local writes later when Zotero adds support.

Optional extras

The base install stays small. Heavy PDF and semantic dependencies are opt-in. For persistent installs:

uv tool install 'zotero-curator[pdf]'
uv tool install 'zotero-curator[semantic]'
uv tool install 'zotero-curator[all]'

For uvx-launched MCP clients, request the extra in the --from package:

uvx --from 'zotero-curator[pdf]' zotero-curator serve
uvx --from 'zotero-curator[semantic]' zotero-curator serve
uvx --from 'zotero-curator[all]' zotero-curator serve

From a checkout:

uv pip install --python .venv/bin/python -e '.[pdf]'
uv pip install --python .venv/bin/python -e '.[semantic]'

The pdf extra enables page-aware PDF reads and bookmark extraction from stored Zotero attachments. The semantic extra stores a local Chroma index under the platform data directory shown by zotero-curator doctor; rebuild with zotero_semantic_rebuild after major library changes, then search with zotero_semantic_search. See docs/optional-extras.md for storage and rebuild details.

Runtime diagnostics

Curator writes structured JSONL runtime logs under the platform log directory shown by:

uvx --from zotero-curator zotero-curator doctor

Set response_format = "json" in the central settings file, or set ZOTERO_CURATOR_RESPONSE_FORMAT=json, to make action-style write responses return structured JSON instead of Markdown. The zotero_diagnostics MCP tool reports resolved settings, log paths, and Zotero API reachability.

Batch organization plans include completed/error counts and a per-step report. Automatic rollback is intentionally not attempted; use the report to build and dry-run a corrective plan before applying fixes.

Development status

Implemented:

• Python package with console scripts: zotero-curator and compatibility alias zotero-mcp.
• Central settings, diagnostics, and structured runtime logs.
• Client config generation for JSON and TOML MCP clients.
• Read/search/full-text tools.
• Dry-run-first write tools.
• arXiv preprint import from IDs, abstract URLs, and PDF URLs.
• Test and lint configuration.
• CI skeleton.

Next polish:

• Client config apply command that safely injects the recommended uvx server entry into Claude/Codex/Cursor configs.
• PyPI trusted publishing and signed GitHub releases.
• Claude Desktop .mcpb packaging.
• Optional semantic index and PDF extraction extras.
• Richer structured JSON responses while keeping Markdown defaults.