cli-anything-zotero

Let AI manage your Zotero library.

中文文档 | English | Roadmap | TODO | Commands

MCP legacy notice: v0.9.5 is the final release with the zotero-mcp command and cli-anything-zotero[mcp] extra. New releases are CLI/SDK-first. Existing MCP users should pin pip install "cli-anything-zotero[mcp]==0.9.5" or use the legacy/mcp branch.

For Non-Programmers

This tool is designed to be used by AI, not memorized by you. After a simple install (~3 minutes), just talk to your AI assistant in plain language:

"Find papers about diabetes and kidney disease in my Zotero library"

"Import this DOI into my CKM collection: 10.1038/s41586-024-07871-6"

"Export all papers in my thesis collection as BibTeX"

"Find PDFs for items in my review collection that are missing them"

All you need to do:

• Follow the Installation steps below

• Tell your AI assistant (Claude Code, Cursor, etc.) what you need

• That's it

What It Does

Built on CLI-Anything by HKUDS, this tool gives AI agents full access to your local Zotero library through a JS Bridge — a lightweight Zotero plugin that exposes a privileged JavaScript endpoint.

Prerequisite: the Zotero desktop app must be running. This is intentional — we automate the local client (Connector, Local API, CLI Bridge), not a cloud-only API substitute.

Key capabilities:

• Search & browse — keyword search, full-text PDF search, collection tree, tags

• Import — from DOI, PMID, RIS/BibTeX files, or JSON

• Export — BibTeX, CSL-JSON, RIS, CSV, formatted citations

• PDF management — attach files, auto-find PDFs online, search annotations

• Write operations — update metadata, manage tags, add notes, trigger sync

• DOCX citations — turn {{zotero:ITEMKEY}} placeholders into static text or refreshable Zotero fields (see below)

• Advanced — execute arbitrary Zotero JS, semantic search with local embeddings, AI analysis

All write operations run locally through the JS Bridge — no API key or internet connection required.

DOCX citations: static vs dynamic

AI-authored drafts should use placeholders such as {{zotero:ITEMKEY}} or {{zotero:KEY1,KEY2}}, then convert them with the docx commands.

Mode Command Output Extra software

Static (default for simple finals) docx render-citations or docx cite --mode static Plain-text citations + static bibliography No. Only pip install + JS Bridge + running Zotero (Local API).

Dynamic (refreshable fields) docx insert-citations or docx cite --mode dynamic Real Zotero fields in Word/LibreOffice + refreshable bibliography Yes — extra stack required (see table below).

Auto docx cite --mode auto Picks dynamic if the stack is ready, else static Same as dynamic when available

Dynamic mode is optional and is not installed by pip alone. You also need:

Requirement Why

Zotero Desktop (running) Source library + word-processor integration

CLI Bridge plugin (zotero-cli app install-plugin) Local privileged bridge used by conversion

LibreOffice Opens/saves the DOCX during field insertion

Zotero LibreOffice plugin Creates refreshable citation/bibliography fields

Check the machine before relying on dynamic mode:

zotero-cli --json docx doctor

If doctor reports missing LibreOffice / the LO add-in / Bridge, use static mode (or install the missing pieces). On macOS the full dynamic path is tested end-to-end; on Windows/Linux, doctor works but auto open/save may still need manual LibreOffice interaction until verified.

One-shot when you are unsure:

zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

CLI-First Usage

cli-anything-zotero is now maintained as a CLI/SDK-first tool. The primary interface is the zotero-cli shell command, which works well for Codex, Claude Code, Cursor, shell scripts, and other agents that can run terminal commands.

For legacy MCP users, install the frozen MCP release explicitly:

pip install "cli-anything-zotero[mcp]==0.9.5"

The legacy/mcp branch and the v0.9.5 release remain available, but MCP receives no new feature maintenance after that line.

Installation

Prerequisites: Python 3.10+, Zotero 7/8/9 (running).

Step 1: Install the package

pip install cli-anything-zotero

This installs the zotero-cli command. The old cli-anything-zotero command remains as a compatibility alias.

Step 2: Install the JS Bridge Plugin (one-time, both modes)

zotero-cli app install-plugin

First install requires manual steps in Zotero:

• The command generates a .xpi file and prints its path

• In Zotero: Tools → Plugins → gear icon → Install Plugin From File...

• Select the .xpi file, then restart Zotero

After the first install, future upgrades via app install-plugin are automatic.

For existing users upgrading to the dynamic DOCX citation workflow, update both the Python package and the Zotero bridge plugin:

python -m pip install -U cli-anything-zotero
zotero-cli app install-plugin
# restart Zotero
zotero-cli app plugin-status
zotero-cli docx doctor

Step 3: Set up your AI client

No client-specific setup is required. Tell your AI assistant that zotero-cli is available; it can run zotero-cli --help to discover commands.

Verify it works:

zotero-cli app ping
zotero-cli js "return Zotero.version"

Troubleshooting

Problem Solution

Cannot resolve Zotero profile directory Launch Zotero at least once first

Plugin not appearing Restart Zotero after installing the .xpi

endpoint_active: false Plugin failed to load — reinstall via Zotero UI

Windows: pip not recognized Close and reopen PowerShell after installing Python

Usage (CLI Mode)

Search & Browse

zotero-cli item find "machine learning"
zotero-cli item search-fulltext "CRISPR"
zotero-cli collection tree

Import

# Preferred agent ingest
zotero-cli --json add doi "10.1038/s41586-024-07871-6" --tag "review" --fetch-pdf
zotero-cli --json add arxiv 2602.02093 --collection COLLECTION_KEY
zotero-cli --json add file ./paper.pdf
zotero-cli --json add bibtex ./refs.bib --collection COLLECTION_KEY

# Lower-level import still available
zotero-cli import doi "10.1038/s41586-024-07871-6" --no-translator
zotero-cli --json item fetch-pdf ITEM_KEY --sources zotero,unpaywall,arxiv
zotero-cli --json collection fetch-pdfs COLLECTION_KEY --limit 20 --jsonl-progress

# DOCX one-shot citations
zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

# Audit recent write ops
zotero-cli --json audit tail --limit 20

Read & Export

zotero-cli item get ITEM_KEY
zotero-cli item find "keyword" --scope fields
zotero-cli item export ITEM_KEY --format bibtex
zotero-cli export bib --items KEY1,KEY2 --output refs.bib
zotero-cli item citation ITEM_KEY
zotero-cli item context ITEM_KEY              # LLM-ready context
zotero-cli docx inspect-citations draft.docx  # detect Zotero/EndNote/static citation fields
zotero-cli docx validate-placeholders draft.docx
zotero-cli docx render-citations draft.docx --output draft-static.docx --force
zotero-cli docx doctor
zotero-cli docx insert-citations draft.docx --output draft-zotero.docx --force

For AI-authored DOCX workflows, use Zotero-bound placeholders such as {{zotero:ITEMKEY}} or {{zotero:KEY1,KEY2}}, then choose the final output mode (details and extra software requirements are under DOCX citations: static vs dynamic):

• Static citations: docx render-citations replaces placeholders with ordinary citation text and appends a static bibliography. Easiest path; no LibreOffice. Cannot be refreshed by the Zotero word processor plugin.

• Dynamic citations: docx insert-citations converts placeholders into real Zotero/LibreOffice fields and creates or updates a refreshable bibliography field. Needs LibreOffice + Zotero LO add-in + Bridge on top of Zotero Desktop.

AI agents should ask the user which mode they want when the request is ambiguous. If the user only wants a simple final DOCX and has not installed LibreOffice, prefer static citations. Always run docx doctor before promising dynamic conversion.

Recommended AI protocol:

• zotero-cli --json docx validate-placeholders <input.docx>

• If the user wants editable references / refresh support:

• zotero-cli --json docx doctor

• zotero-cli --json docx insert-citations <input.docx> --output <final.docx> --force

• If conversion fails, report the failing layer from doctor and ask the user for next steps.

• If the user wants static output or dynamic is unavailable:

• zotero-cli --json docx render-citations <input.docx> --output <final.docx> --force

Keep these files only as h