Skip to content
Back to search

cli-anything-zotero

CLI server for Zotero 7/8/9 — let AI manage your library. 70+ CLI commands for search, import, PDF, BibTeX, notes, and more. Works with Claude, Cursor, ChatGPT.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/piaoyangguohai1--cli-anything-zotero/badge.svg)](/listings/piaoyangguohai1--cli-anything-zotero)

HTML

<a href="/listings/piaoyangguohai1--cli-anything-zotero"><img src="/api/listings/piaoyangguohai1--cli-anything-zotero/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**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

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

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 404 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # cli-anything-zotero
  2. [![PyPI](https://img.shields.io/pypi/v/cli-anything-zotero?color=blue)](https://pypi.org/project/cli-anything-zotero/)
  3. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
  4. [![License](https://img.shields.io/github/license/PiaoyangGuohai1/cli-anything-zotero)](LICENSE)
  5. [![GitHub release](https://img.shields.io/github/v/release/PiaoyangGuohai1/cli-anything-zotero)](https://github.com/PiaoyangGuohai1/cli-anything-zotero/releases)
  6. [![GitHub stars](https://img.shields.io/github/stars/PiaoyangGuohai1/cli-anything-zotero)](https://github.com/PiaoyangGuohai1/cli-anything-zotero/stargazers)
  7. **Let AI manage your Zotero library.**
  8. [中文文档](docs/README_zh.md) | English | [Roadmap](docs/ROADMAP.md) | [TODO](docs/TODO.md) | [Commands](docs/COMMANDS.md)
  9. > **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.
  10. ---
  11. ## For Non-Programmers
  12. 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:
  13. > "Find papers about diabetes and kidney disease in my Zotero library"
  14. >
  15. > "Import this DOI into my CKM collection: 10.1038/s41586-024-07871-6"
  16. >
  17. > "Export all papers in my thesis collection as BibTeX"
  18. >
  19. > "Find PDFs for items in my review collection that are missing them"
  20. **All you need to do:**
  21. 1. Follow the [Installation](#installation) steps below
  22. 2. Tell your AI assistant (Claude Code, Cursor, etc.) what you need
  23. 3. That's it
  24. ---
  25. ## What It Does
  26. Built on [CLI-Anything](https://github.com/HKUDS/CLI-Anything) by [HKUDS](https://github.com/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.
  27. **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.
  28. **Key capabilities:**
  29. - **Search & browse** — keyword search, full-text PDF search, collection tree, tags
  30. - **Import** — from DOI, PMID, RIS/BibTeX files, or JSON
  31. - **Export** — BibTeX, CSL-JSON, RIS, CSV, formatted citations
  32. - **PDF management** — attach files, auto-find PDFs online, search annotations
  33. - **Write operations** — update metadata, manage tags, add notes, trigger sync
  34. - **DOCX citations** — turn `{{zotero:ITEMKEY}}` placeholders into static text or refreshable Zotero fields (see below)
  35. - **Advanced** — execute arbitrary Zotero JS, semantic search with local embeddings, AI analysis
  36. All write operations run locally through the JS Bridge — no API key or internet connection required.
  37. ### DOCX citations: static vs dynamic
  38. AI-authored drafts should use placeholders such as `{{zotero:ITEMKEY}}` or
  39. `{{zotero:KEY1,KEY2}}`, then convert them with the `docx` commands.
  40. | Mode | Command | Output | Extra software |
  41. |------|---------|--------|----------------|
  42. | **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). |
  43. | **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). |
  44. | **Auto** | `docx cite --mode auto` | Picks dynamic if the stack is ready, else static | Same as dynamic when available |
  45. **Dynamic mode is optional and is not installed by `pip` alone.** You also need:
  46. | Requirement | Why |
  47. |-------------|-----|
  48. | Zotero Desktop (running) | Source library + word-processor integration |
  49. | CLI Bridge plugin (`zotero-cli app install-plugin`) | Local privileged bridge used by conversion |
  50. | [LibreOffice](https://www.libreoffice.org/) | Opens/saves the DOCX during field insertion |
  51. | [Zotero LibreOffice plugin](https://www.zotero.org/support/word_processor_plugin_installation) | Creates refreshable citation/bibliography fields |
  52. Check the machine before relying on dynamic mode:
  53. ```bash
  54. zotero-cli --json docx doctor
  55. ```
  56. If `doctor` reports missing LibreOffice / the LO add-in / Bridge, use **static**
  57. mode (or install the missing pieces). On macOS the full dynamic path is tested
  58. end-to-end; on Windows/Linux, `doctor` works but auto open/save may still need
  59. manual LibreOffice interaction until verified.
  60. One-shot when you are unsure:
  61. ```bash
  62. zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force
  63. ```
  64. ---
  65. ## CLI-First Usage
  66. `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.
  67. For legacy MCP users, install the frozen MCP release explicitly:
  68. ```bash
  69. pip install "cli-anything-zotero[mcp]==0.9.5"
  70. ```
  71. The `legacy/mcp` branch and the `v0.9.5` release remain available, but MCP receives no new feature maintenance after that line.
  72. ---
  73. ## Installation
  74. **Prerequisites:** Python 3.10+, Zotero 7+ (running).
  75. ### Step 1: Install the package
  76. ```bash
  77. pip install cli-anything-zotero
  78. ```
  79. This installs the `zotero-cli` command. The old `cli-anything-zotero` command remains as a compatibility alias.
  80. ### Step 2: Install the JS Bridge Plugin (one-time, both modes)
  81. ```bash
  82. zotero-cli app install-plugin
  83. ```
  84. The first install goes through Zotero's Plugins window (Zotero switches off plugins that appear in its profile on their own):
  85. 1. The command generates a `.xpi` file and prints its path
  86. 2. In Zotero: **Tools → Plugins → gear icon → Install Plugin From File...**
  87. 3. Select the `.xpi` file, then **restart Zotero**
  88. > After the first install, `app install-plugin` upgrades the bridge without the Plugins window. With Zotero running and the bridge active, it upgrades through the bridge. With Zotero closed, it replaces the plugin in the profile and Zotero loads it on its next start.
  89. > **Upgrading to Zotero 10:** bridge versions up to 1.2.1 only declare support for Zotero 7–9, so Zotero 10 disables them. Upgrade cli-anything-zotero (1.4.2 or later), quit Zotero, run `zotero-cli app install-plugin`, then start Zotero.
  90. For existing users upgrading to the dynamic DOCX citation workflow, update both
  91. the Python package and the Zotero bridge plugin:
  92. ```bash
  93. python -m pip install -U cli-anything-zotero
  94. zotero-cli app install-plugin
  95. # restart Zotero
  96. zotero-cli app plugin-status
  97. zotero-cli docx doctor
  98. ```
  99. ### Step 3: Set up your AI client
  100. No client-specific setup is required. Tell your AI assistant that `zotero-cli` is available; it can run `zotero-cli --help` to discover commands.
  101. Verify it works:
  102. ```bash
  103. zotero-cli app ping
  104. zotero-cli js "return Zotero.version"
  105. ```
  106. ### Troubleshooting
  107. | Problem | Solution |
  108. |---------|----------|
  109. | `Cannot resolve Zotero profile directory` | Launch Zotero at least once first |
  110. | Plugin not appearing | Restart Zotero after installing the `.xpi` |
  111. | `endpoint_active: false` | Plugin failed to load — reinstall via Zotero UI |
  112. | `No endpoint found` after a Zotero major upgrade | Zotero disabled the bridge as incompatible; `zotero-cli app doctor` reports `app_disabled`. Upgrade cli-anything-zotero, quit Zotero, run `zotero-cli app install-plugin`, then start Zotero |
  113. | `app doctor` reports `user_disabled` | The bridge is switched off in Zotero: turn it on in **Tools → Plugins** |
  114. | Windows: `pip` not recognized | Close and reopen PowerShell after installing Python |
  115. ---
  116. ## Usage (CLI Mode)
  117. **Search & Browse**
  118. ```bash
  119. zotero-cli item find "machine learning"
  120. zotero-cli item search-fulltext "CRISPR"
  121. zotero-cli collection tree
  122. ```
  123. **Import**
  124. ```bash
  125. # Preferred agent ingest
  126. zotero-cli --json add doi "10.1038/s41586-024-07871-6" --tag "review" --fetch-pdf
  127. zotero-cli --json add arxiv 2602.02093 --collection COLLECTION_KEY
  128. zotero-cli --json add file ./paper.pdf
  129. zotero-cli --json add bibtex ./refs.bib --collection COLLECTION_KEY
  130. # Lower-level import still available
  131. zotero-cli import doi "10.1038/s41586-024-07871-6" --no-translator
  132. zotero-cli --json item fetch-pdf ITEM_KEY --sources zotero,unpaywall,arxiv
  133. zotero-cli --json collection fetch-pdfs COLLECTION_KEY --limit 20 --jsonl-progress
  134. # DOCX one-shot citations
  135. zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force
  136. # Audit recent write ops
  137. zotero-cli --json audit tail --limit 20
  138. ```
  139. **Library hygiene**
  140. ```bash
  141. # Find duplicate clusters. Matches on DOI, and on normalized title confirmed by
  142. # a shared creator surname and an agreeing year. Each copy reports its
  143. # attachment counts and its Better BibTeX citation key.
  144. zotero-cli --json item duplicates --limit 20
  145. zotero-cli --json item duplicates --year-tolerance 0 # exact year agreement only
  146. zotero-cli --json item merge KEEP OTHER1 # dry-run; --confirm applies
  147. ```
  148. Clusters whose copies carry more than one *pinned* citation key are flagged with
  149. `citation_key_conflict: true`. Merging those silently orphans whichever key your
  150. manuscript already cites, so resolve the key before merging.
  151. **Deleting things**
  152. ```bash
  153. zotero-cli item delete ITEM_KEY --confirm # -> trash. Reversible.
  154. zotero-cli item restore ITEM_KEY # <- back out of the trash
  155. zotero-cli collection delete COLLECTION_KEY --confirm # with its subcollections
  156. zotero-cli collection restore COLLECTION_KEY # brings the subcollections back too
  157. ```
  158. `delete` moves things to the Zotero trash, exactly as the Delete key does in the
  159. Zotero UI. Trashed items keep their keys and stay recoverable until you empty the
  160. trash, which the CLI never does for you. `collection delete --delete-items` also
  161. trashes the items of the collection and of every subcollection; `collection restore`
  162. leaves those items in the trash, as the Zotero UI does, so restore them with
  163. `item restore`.
  164. Permanent erasure is a separate path and bypasses the trash entirely:
  165. ```bash
  166. zotero-cli item delete ITEM_KEY --permanent --yes-erase
  167. ```
  168. `--permanent` prompts before erasing **even when `--confirm` is given**; only the
  169. explicit `--yes-erase` suppresses that prompt. `--confirm` is the flag people
  170. paste into scripts out of habit, so it is deliberately not the flag that can
  171. destroy anything.
  172. **Read & Export**
  173. ```bash
  174. zotero-cli item get ITEM_KEY
  175. zotero-cli item find "keyword" --scope fields
  176. zotero-cli item export ITEM_KEY --format bibtex
  177. zotero-cli export bib --items KEY1,KEY2 --output refs.bib
  178. zotero-cli item citation ITEM_KEY
  179. zotero-cli item context ITEM_KEY # LLM-ready context
  180. zotero-cli docx inspect-citations draft.docx # detect Zotero/EndNote/static citation fields
  181. zotero-cli docx validate-placeholders draft.docx
  182. zotero-cli docx render-citations draft.docx --output draft-static.docx --force
  183. zotero-cli docx doctor
  184. zotero-cli docx insert-citations draft.docx --output draft-zotero.docx --force
  185. ```
  186. For AI-authored DOCX workflows, use Zotero-bound placeholders such as
  187. `{{zotero:ITEMKEY}}` or `{{zotero:KEY1,KEY2}}`, then choose the final output
  188. mode (details and **extra software requirements** are under
  189. [DOCX citations: static vs dynamic](#docx-citations-static-vs-dynamic)):
  190. - 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.
  191. - 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.
  192. AI agents should ask the user which mode they want when the request is
  193. ambiguous. If the user only wants a simple final DOCX and has not installed
  194. LibreOffice, prefer static citations. Always run `docx doctor` before promising
  195. dynamic conversion.
  196. Recommended AI protocol:
  197. 1. `zotero-cli --json docx validate-placeholders <input.docx>`
  198. 2. If the user wants editable references / refresh support:
  199. - `zotero-cli --json docx doctor`
  200. - `zotero-cli --json docx insert-citations <input.docx> --output <final.docx> --force`
  201. - If conversion fails, report the failing layer from `doctor` and ask the user for next steps.
  202. 3. If the user wants static output or dynamic is unavailable:
  203. - `zotero-cli --json docx render-citations <input.docx> --output <final.docx> --force`
  204. Keep these files only as handoff artifacts:
  205. - Placeholder draft (`<input.docx>`)
  206. - Final converted draft (`<final.docx>`)
  207. - No intermediate DOCX should be exposed unless `--debug-dir` is explicitly requested.
  208. Platform support for this optional workflow:
  209. - macOS: tested end-to-end with automatic open, conversion, save, and Word-compatible DOCX output.
  210. - 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.
  211. `validate-placeholders`, `zoterify-preflight`, and `zoterify-probe` are
  212. diagnostics for setup or failure cases. Add `--debug-dir` only when you want
  213. JSON artifacts for troubleshooting.
  214. `docx prepare-zotero-import` exists only as an experimental debugging command;
  215. it is not a supported writing workflow after Zotero 9 + LibreOffice testing.
  216. `docx insert-citations` and `docx render-citations` are the two supported outputs
  217. for AI-authored citation insertion.
  218. `item citation` and `item bibliography` render static previews; they are not
  219. refreshable Word/LibreOffice Zotero fields. BIB export is a separate export
  220. feature and is not part of the DOCX writing workflow.
  221. **Write & Manage**
  222. ```bash
  223. zotero-cli item update KEY --field title="New Title"
  224. zotero-cli item tag KEY --add "important"
  225. zotero-cli item tag KEY1 KEY2 KEY3 --add "reviewed" # one bridge call for all keys
  226. zotero-cli item attach KEY ./paper.pdf
  227. zotero-cli item find-pdf KEY
  228. zotero-cli note add KEY --text "My note"
  229. zotero-cli sync
  230. ```
  231. **Bulk operations**
  232. ```bash
  233. # Tag everything a search returns, in one call
  234. zotero-cli --json item find "graph" | jq -r '.[].key' | zotero-cli item tag --keys-from - --add reviewed
  235. # Many write operations from one JSONL file, in one process
  236. zotero-cli --json batch ops.jsonl --dry-run # validate only, change nothing
  237. zotero-cli --json batch ops.jsonl --jsonl-progress # run, one result line per operation
  238. ```
  239. `ops.jsonl` holds one operation per line:
  240. ```jsonl
  241. {"op": "tag", "key": "ABCD1234", "add": ["reviewed"], "remove": ["unread"]}
  242. {"op": "update", "key": "ABCD1234", "fields": {"extra": "checked 2026-11"}}
  243. {"op": "note", "key": "ABCD1234", "file": "notes/ABCD1234.md"}
  244. {"op": "add-doi", "doi": "10.1371/journal.pcbi.1003285", "collection": "COLLKEY1", "tags": ["to-read"], "fetch_pdf": true}
  245. {"op": "add-pmid", "pmid": "32015507", "tags": ["to-read"]}
  246. ```
  247. Every line is validated before anything runs, so a typo on one line does not leave
  248. the lines before it applied. Operations then run in order and a failed one does
  249. not stop the rest (pass `--stop-on-error` to stop). Consecutive `tag` lines go to
  250. Zotero in a single bridge call; with `--op tag`, lines can leave out `"op"`. Note
  251. files ending in `.md` are read as Markdown, and relative paths resolve against
  252. the JSONL file. The exit code is 1 when any operation failed; a DOI imported
  253. without an open-access PDF still counts as done and is reported under `partial`.
  254. **Advanced**
  255. ```bash
  256. zotero-cli item search-annotations "risk"
  257. zotero-cli item annotations KEY
  258. zotero-cli item metrics KEY # NIH citation metrics
  259. zotero-cli collection stats COLLECTION_KEY
  260. zotero-cli js "return await Zotero.Items.getAll(1).then(i => i.length)"
  261. ```
  262. Full command reference: **[docs/COMMANDS.md](docs/COMMANDS.md)**
  263. ---
  264. ## Optional Features
  265. These require extra services. Everything else works without them.
  266. ### Semantic Search
  267. Any OpenAI-compatible `/v1/embeddings` endpoint ([Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), OpenAI, etc.).
  268. ```bash
  269. zotero-cli item build-index # one-time
  270. zotero-cli item semantic-search "cardiovascular risk"
  271. zotero-cli item similar ITEM_KEY
  272. ```
  273. | Variable | Default | Description |
  274. |----------|---------|-------------|
  275. | `ZOTERO_EMBED_API` | `http://127.0.0.1:8080/v1/embeddings` | Embedding API endpoint |
  276. | `ZOTERO_EMBED_MODEL` | `nomic-embed-text` | Model name |
  277. | `ZOTERO_EMBED_KEY` | *(empty)* | API key (if needed) |
  278. ### AI Analysis
  279. ```bash
  280. export OPENAI_API_KEY=sk-...
  281. zotero-cli item analyze ITEM_KEY --question "What are the main findings?"
  282. ```
  283. ---
  284. ## Legacy MCP Users
  285. MCP support is frozen at `v0.9.5`. To keep using the previous MCP server, install:
  286. ```bash
  287. pip install "cli-anything-zotero[mcp]==0.9.5"
  288. ```
  289. 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.
  290. ## Related Projects
  291. There are several great tools in the Zotero ecosystem. Each has different strengths depending on your use case:
  292. | | **cli-anything-zotero** | [zotero-mcp](https://github.com/54yyyu/zotero-mcp) | [zotero-cli-cc](https://github.com/Agents365-ai/zotero-cli-cc) | [pyzotero-cli](https://github.com/chriscarrollsmith/pyzotero-cli) |
  293. |---|---|---|---|---|
  294. | **Approach** | Local JS Bridge | Web API + MCP | Web API + CLI | Web API + CLI |
  295. | **Best for** | Local-first, full control | MCP-native workflows | Agent-driven research | Scripting & automation |
  296. | **Write ops** | Local (no API key) | Via Web API | Via Web API | Via Web API |
  297. | **MCP support** | Legacy via v0.9.5 | Yes | 45 tools | No |
  298. | **Terminal CLI** | Yes | No | Yes | Yes |
  299. | **Zotero JS access** | Yes | No | No | No |
  300. | **License** | Apache 2.0 | MIT | CC BY-NC 4.0 | MIT |
  301. ---
  302. ## License
  303. [Apache 2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.