zot — A Zotero CLI for Any AI Agent

中文 | Documentation

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

Related MCP server: zotero-mcp

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

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:

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 in closed-source or commercial products without the AGPL's copyleft obligations (see LICENSE-COMMERCIAL).

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