zot — A Zotero CLI for Any AI Agent

zotero-cli is a Zotero CLI for any AI agent.

Reads — direct local SQLite, zero-config, offline, millisecond response
Writes — safe via Zotero Web API, Zotero stays in sync
PDF + ranked search — extract full text with caching; index-free ranked retrieval over the whole library or scoped to a collection
Agent-native — stable JSON envelope, typed exit codes, zot schema, --dry-run, --idempotency-key, NDJSON streaming
MCP server — exposes 39 tools to Claude Desktop / LM Studio / Cursor via zot mcp serve

Architecture

Install

uv tool install zotero-cli-ai      # recommended
pipx install zotero-cli-ai         # or
pip install zotero-cli-ai          # or

Note: the PyPI package is zotero-cli-ai (zotero-cli is an unrelated older project); the installed command is zot.

60-second quickstart

# Reads work out of the box — no API key, Zotero data dir auto-detected
zot search "transformer attention"
zot read ABC123
zot export ABC123                  # BibTeX

# Writes need a Web API key (https://www.zotero.org/settings/keys)
zot config init
zot add --doi "10.1038/s41586-023-06139-9"

In Claude Code, just ask in natural language — the bundled skill maps requests to zot commands automatically:

cp -r skill/zotero-cli ~/.claude/skills/

When stdout is not a TTY, zot automatically emits a stable JSON envelope so agents never need --json:

{ "ok": true, "data": { ... }, "meta": { "request_id": "...", "cli_version": "0.4.3" } }

Documentation

Full docs live at https://agents365-ai.github.io/zotero-cli-ai/.

Topic	Link
Installation & setup	Getting started
Search, list, read	Search guide
Notes, tags, citations	Notes & tags, Citations
Add / update / delete items	Item management
Collections	Collections
Ranked search & ask (collections)	Search guide
PDF extraction	PDF
Preprint → published	update-status
MCP setup & tools	MCP
Full CLI reference	CLI reference
Agent contract (envelope, exit codes, schema)	`docs/agent-interface.md`
Comparison with similar tools	Comparison
Roadmap	`ROADMAP.md`

Why zotero-cli? The only actively maintained Python CLI that reads Zotero's local SQLite database directly, with a clean read/write split: SQLite for fast offline reads, Web API for safe writes that Zotero stays aware of. See the comparison page for a feature-by-feature breakdown against similar tools.

Support

If zot helps you, consider supporting the author:

WeChat Pay

Alipay

Buy Me a Coffee

Give a Reward

Author

Agents365-ai

Bilibili: https://space.bilibili.com/441831884
GitHub: https://github.com/Agents365-ai

License

zotero-cli is dual-licensed:

Open source: GNU AGPL-3.0-or-later (see LICENSE).
Commercial: a separate commercial license is available for use inclosed-source or commercial products without the AGPL's copyleft obligations(see LICENSE-COMMERCIAL).

Contributions are accepted under the project's Developer Certificate of Origin.

zot — A Zotero CLI for Any AI Agent