cli-anything-zotero

Let AI manage your Zotero library.

中文文档 | English

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.

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
• Advanced — execute arbitrary Zotero JS, semantic search with local embeddings, AI analysis
• MCP server — 49 tools for Claude Desktop, Cursor, LM Studio, and other MCP clients

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

Installation

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

1. Install the CLI

pip install cli-anything-zotero

Or install from source:

git clone https://github.com/PiaoyangGuohai1/cli-anything-zotero.git
cd cli-anything-zotero && pip install -e .

2. Install the JS Bridge Plugin (one-time)

cli-anything-zotero 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.

3. Verify

cli-anything-zotero app plugin-status --json
# Should show: "plugin_installed": true, "endpoint_active": true

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

Troubleshooting

Usage

Search & Browse

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

Import

cli-anything-zotero import doi "10.1038/s41586-024-07871-6" --tag "review"
cli-anything-zotero import pmid "37821702" --collection FMTCPUWN
cli-anything-zotero import file ./refs.ris

Read & Export

cli-anything-zotero item get ITEM_KEY
cli-anything-zotero item export ITEM_KEY --format bibtex
cli-anything-zotero item citation ITEM_KEY
cli-anything-zotero item context ITEM_KEY              # LLM-ready context

Write & Manage

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

Advanced

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

Full command reference: docs/COMMANDS.md

MCP Server

49 tools for AI clients that support the Model Context Protocol. Full reference: docs/MCP.md

pip install 'cli-anything-zotero[mcp]'
zotero-cli mcp serve

Client configuration (Claude Desktop / Cursor / LM Studio):

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

Optional Features

These require extra services. Everything else works without them.

Semantic Search

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

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

AI Analysis

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

Related Projects

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

License

Apache 2.0