cli-anything-zotero

by piaoyangguohai1

Not rated

GitHub

About

CLI & MCP server for Zotero 7/8 — 52 tools to let AI manage your research library locally. Search, import, export, PDF, notes, and more.

Details

Author: piaoyangguohai1
Categories: Productivity, Other, Knowledge Base

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

First install requires manual steps in Zotero:
- The command generates a.xpifile and prints its path
- In Zotero:Tools → Plugins → gear icon → Install Plugin From File...
- Select the.xpifile, thenrestart Zotero

After the first install, future upgrades viaapp install-pluginare 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

No client-specific setup is required. Tell your AI assistant thatzotero-cliis available; it can runzotero-cli --helpto discover commands.

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

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

# 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

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 andextra software requirementsare underDOCX citations: static vs dynamic):

- Static citations:docx render-citationsreplaces 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-citationsconverts placeholders into real Zotero/LibreOffice fields and creates or updates a refreshable bibliography field. NeedsLibreOffice + Zotero LO add-in + Bridgeon 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 rundocx doctorbefore promising dynamic conversion.
- 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 fromdoctorand ask the user for next steps.

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

Keep these files only as handoff artifacts:

- Placeholder draft (<input.docx>)
- Final converted draft (<final.docx>)
- No intermediate DOCX should be exposed unless--debug-diris 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, anddocx doctorcan 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, andzoterify-probeare diagnostics for setup or failure cases. Add--debug-dironly when you want JSON artifacts for troubleshooting.docx prepare-zotero-importexists only as an experimental debugging command; it is not a supported writing workflow after Zotero 9 + LibreOffice testing.docx insert-citationsanddocx render-citationsare the two supported outputs for AI-authored citation insertion.item citationanditem bibliographyrender 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.

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

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

These require extra services. Everything else works without them.

Any OpenAI-compatible/v1/embeddingsendpoint (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

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

MCP support is frozen atv0.9.5. To keep using the previous MCP server, install:

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

You can also use thelegacy/mcpbranch for source installs. Starting withv1.0.0, the maintained package installs only CLI/SDK surfaces and no longer provides thezotero-mcpcommand.

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

Search, cite, and read PDFs from your EndNote reference library directly in Claude Desktop

Connect your Zotero research library with AI assistants. Supports local/web API access, PDF annotation extraction, and advanced search.

MCP server for Apple Notes with semantic search and CRUD operations. Claude searches, reads, creates, updates, and manages your Apple Notes through natural language.

An MCP server for interacting with Bookstack, built with the mcp-framework for Node.js.

Personal Knowledge Base MCP — 22 tools for AI agents to access your curated reading intelligence.

Integrates Model Context Protocol (MCP) with Obsidian, allowing AI assistants to interact with your notes and vault.

A Model Context Protocol (MCP) Server for https://joplinapp.org/ that enables note access through the https://modelcontextprotocol.io. Perfect for integration with AI assistants like Claude.

Semantic search and RAG over Apple Notes with on-device embeddings, full CRUD, folder management, and fuzzy title matching. 10 tools. Fully local on macOS.

A service for reading, writing, and managing markdown documentation with frontmatter metadata.

A lightweight MCP server that wraps academic-refchecker, letting Claude verify academic citations against Semantic Scholar, OpenAlex, and CrossRef in real time

CLI & MCP server for Zotero 7/8 — 52 tools to let AI manage your research library locally. Search, import, export, PDF, notes, and more.

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

MCP legacy notice:v0.9.5is the final release with thezotero-mcpcommand andcli-anything-zotero[mcp]extra. New releases are CLI/SDK-first. Existing MCP users should pinpip install "cli-anything-zotero[mcp]==0.9.5"or use thelegacy/mcpbranch.

This tool is designed to beused 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"
- Follow theInstallationsteps below
- Tell your AI assistant (Claude Code, Cursor, etc.) what you need
- That's it

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

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

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

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

Dynamic mode is optional and is not installed bypipalone.You also need:

Check the machine before relying on dynamic mode:

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

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

cli-anything-zoterois now maintained as a CLI/SDK-first tool. The primary interface is thezotero-clishell 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"

Thelegacy/mcpbranch and thev0.9.5release remain available, but MCP receives no new feature maintenance after that line.

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

This installs thezotero-clicommand. The oldcli-anything-zoterocommand remains as a compatibility alias.