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:

1. Follow the Installation steps below

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

3. 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.

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

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:

1. The command generates a `.xpi` file and prints its path

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

3. 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

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:

1. `zotero-cli --json docx validate-placeholders `

2. If the user wants editable references / refresh support:

3. If the user wants static output or dynamic is unavailable:

Keep these files only as handoff artifacts:

• Placeholder draft (``)
• Final converted draft (``)
• No intermediate DOCX should be exposed unless `--debug-dir` is explicitly requested.

Platform support for this optional workflow:

• macOS: tested end-to-end with automatic open, conversion, save, and Word-compatible DOCX output.
• Windows/Linux: the base CLI works, and `docx doctor` can report missing dependencies. Full automatic LibreOffice open/save for dynamic DOCX citations still needs real Windows/Linux desktop validation; users may need to open or save the LibreOffice document manually until platform automation is verified.

`validate-placeholders`, `zoterify-preflight`, and `zoterify-probe` are

diagnostics for setup or failure cases. Add `--debug-dir` only when you want

JSON artifacts for troubleshooting.

`docx prepare-zotero-import` exists only as an experimental debugging command;

it is not a supported writing workflow after Zotero 9 + LibreOffice testing.

`docx insert-citations` and `docx render-citations` are the two supported outputs

for AI-authored citation insertion.

`item citation` and `item bibliography` render static previews; they are not

refreshable Word/LibreOffice Zotero fields. BIB export is a separate export

feature and is not part of the DOCX writing workflow.

Write & Manage

zotero-cli item update KEY --field title="New Title"
zotero-cli item tag KEY --add "important"
zotero-cli item attach KEY ./paper.pdf
zotero-cli item find-pdf KEY
zotero-cli note add KEY --text "My note"
zotero-cli sync

Advanced

zotero-cli item search-annotations "risk"
zotero-cli item annotations KEY
zotero-cli item metrics KEY                   # NIH citation metrics
zotero-cli collection stats COLLECTION_KEY
zotero-cli js "return await Zotero.Items.getAll(1).then(i => i.length)"

Full command reference: **docs/COMMANDS.md**

Optional Features

These require extra services. Everything else works without them.

Semantic Search

Any OpenAI-compatible `/v1/embeddings` endpoint (Ollama, LM Studio, OpenAI, etc.).

zotero-cli item build-index                            # one-time
zotero-cli item semantic-search "cardiovascular risk"
zotero-cli item similar ITEM_KEY

AI Analysis

export OPENAI_API_KEY=sk-...
zotero-cli item analyze ITEM_KEY --question "What are the main findings?"

Legacy MCP Users

MCP support is frozen at `v0.9.5`. To keep using the previous MCP server, install:

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

You can also use the `legacy/mcp` branch for source installs. Starting with `v1.0.0`, the maintained package installs only CLI/SDK surfaces and no longer provides the `zotero-mcp` command.

Related Projects

There are several great tools in the Zotero ecosystem. Each has different strengths depending on your use case:

License

Apache 2.0