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

Choose Your Mode

This tool supports two modes. Pick the one that fits your AI client:

Not sure? If your AI client supports MCP, choose MCP — it's more reliable. Otherwise, CLI works everywhere.

Installation

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

Step 1: Install the package

CLI Mode (for any AI assistant):

pip install cli-anything-zotero

MCP Mode (for Claude Desktop, Cursor, Claude Code, etc.):

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

Both modes are included in the same package. The [mcp] extra just adds MCP protocol dependencies.

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

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.

Step 3: Set up your AI client

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

claude mcp add zotero --scope user -- cli-anything-zotero mcp serve

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

Troubleshooting

Usage (CLI Mode)

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

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

Upgrading to 0.4.0

Breaking change for MCP users: All MCP tool names have been renamed from mixed conventions to a consistent group_action pattern matching the CLI. If you have agent prompts or configs referencing old tool names, update them:

CLI users: No breaking changes. The --help output now shows all commands at once.

Related Projects

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

License

Apache 2.0