zot — Let Zotero Fly in Your Terminal

zotero-cli-cc is a Zotero CLI built for Claude Code and AI agents.

Reads — direct local SQLite, zero-config, offline, millisecond response
Writes — safe via Zotero Web API, Zotero stays in sync
PDF + RAG — extract full text with caching; built-in BM25 (+ optional embedding) search over per-topic workspaces
Agent-native — stable JSON envelope, typed exit codes, zot schema, --dry-run, --idempotency-key, NDJSON streaming
MCP server — exposes 45 tools to Claude Desktop / LM Studio / Cursor via zot mcp serve

Architecture

Install

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

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-cc ~/.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-cc/.

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
Workspaces + RAG	Workspaces
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-cc? 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.

Community

Join us for help, Q&A, and updates:

Discord: https://discord.gg/79JF5Atuk
WeChat: scan the QR code below

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-cc 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 — Let Zotero Fly in Your Terminal