Zotero CLI Cc
Zotero CLI for Claude Code β SQLite reads + Web API writes
Ask AI about Zotero CLI Cc
Powered by Claude Β· Grounded in docs
I know everything about Zotero CLI Cc. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
zot β Let Zotero Fly in Your Terminal
Introduction
zotero-cli-cc is a Zotero CLI designed for Claude Code.
Core Features:
- Reads: Direct local SQLite database access β zero config, offline, millisecond response
- Writes: Safe writes through Zotero Web API β Zotero fully aware of changes
- PDF: Extract full text from local PDF storage with automatic caching
- Workspace: Organize papers by topic with local workspaces + built-in RAG search
- Agent-native: Stable JSON envelope, typed exit codes,
zot schema,--dry-run,--idempotency-key, NDJSON streaming β seedocs/agent-interface.md
Search and read papers without launching Zotero desktop.
Using with Claude Code
In any Claude Code session, use natural language:
Search my Zotero for single cell papers
β Claude runs: zot search "single cell"
Show me details of this paper
β Claude runs: zot read ABC123
Export BibTeX for this paper
β Claude runs: zot export ABC123
When zot detects that stdout is not a TTY (agents, pipelines, subprocess calls) it automatically emits JSON. Humans still see tables. Agents never have to pass --json.
Every command response is a stable envelope:
{ "ok": true, "data": { ... }, "meta": { "request_id": "...", "cli_version": "0.4.0" } }
Errors carry machine-routable code and retryable fields; exit codes are distinct per failure class (1 runtime, 2 auth, 3 validation, 4 not-found, 5 network, 6 conflict). Mutating commands support --dry-run and --idempotency-key so retries are safe. See docs/agent-interface.md for the full contract, or run zot schema to introspect the CLI tree programmatically.
Install the zotero-cli skill so Claude Code automatically recognizes literature-related requests:
# Install skill (copy skill/zotero-cli-cc/ to ~/.claude/skills/)
cp -r skill/zotero-cli-cc ~/.claude/skills/
Install
# Recommended
uv tool install zotero-cli-cc
# Or
pipx install zotero-cli-cc
# Or
pip install zotero-cli-cc
Upgrade to the latest version:
uv tool upgrade zotero-cli-cc # uv
pipx upgrade zotero-cli-cc # pipx
pip install -U zotero-cli-cc # pip
Setup
# Configure Web API credentials (write operations only)
zot config init
Data Directory
Data directory refers to the folder containing the
zotero.sqlitedatabase file (not the Zotero installation directory or the PDF sync directory). You can find it in Zotero Settings β Advanced β "Data Directory Location".
Read operations work out of the box. zot automatically detects the Zotero data directory:
| Platform | Detection Order |
|---|---|
| Windows | Registry HKCU\Software\Zotero\Zotero\dataDir β %APPDATA%\Zotero β %LOCALAPPDATA%\Zotero |
| macOS / Linux | ~/Zotero |
If your Zotero data is not in the default location, specify it:
# Option 1: Config file (recommended)
zot config init --data-dir "D:\MyZotero"
# Option 2: Environment variable
export ZOT_DATA_DIR="/path/to/zotero/data"
# Option 3: Edit config file manually
# Edit ~/.config/zot/config.toml
Example config file:
[zotero]
data_dir = "D:\\MyZotero"
library_id = "12345"
api_key = "xxx"
[output]
default_format = "table"
limit = 50
[export]
default_style = "bibtex"
API Credentials
Write operations require an API Key from https://www.zotero.org/settings/keys.
MCP Server Mode
zotero-cli-cc supports MCP (Model Context Protocol) and can be used in MCP-compatible clients like LM Studio, Claude Desktop, and Cursor.
Install MCP Support:
pip install zotero-cli-cc[mcp]
Start MCP Server:
zot mcp serve
Client Configuration (LM Studio / Claude Desktop / Cursor):
{
"mcpServers": {
"zotero": {
"command": "zot",
"args": ["mcp", "serve"]
}
}
}
MCP mode provides 45 tools covering search, reading, PDF extraction, note management, tag management, citation export, workspace management with RAG, library statistics, and preprint status checking.
Commands
Search & Browse
How search works:
zot searchmatches keywords across four layers: β titles & abstracts β‘ author names β’ tags β£ PDF fulltext index. For deeper content search with BM25 ranking and optional semantic matching, usezot workspace queryβ it indexes metadata + full PDF text and supports hybrid BM25 + embedding retrieval.
# Search across title, author, tags, fulltext
zot search "transformer attention"
# Filter by collection
zot search "BERT" --collection "NLP"
# List items
zot list --collection "Machine Learning" --limit 10
# View item details (metadata + abstract + notes)
zot read ABC123
# Find related items
zot relate ABC123
Notes & Tags
# View/add notes
zot note ABC123
zot note ABC123 --add "This paper proposes a new attention mechanism"
# View/add/remove tags
zot tag ABC123
zot tag ABC123 --add "important"
zot tag ABC123 --remove "to-read"
Citation Export
zot export ABC123 # BibTeX
zot export ABC123 --format csl-json # CSL-JSON
zot export ABC123 --format ris # RIS
zot export ABC123 --format json # JSON
# Format citation and copy to clipboard
zot cite ABC123 # APA (default)
zot cite ABC123 --style nature # Nature
zot cite ABC123 --style vancouver # Vancouver
Item Management
zot add --doi "10.1038/s41586-023-06139-9" # Add by DOI
zot add --url "https://arxiv.org/abs/2301.00001" # Add by URL
zot add --from-file dois.txt # Batch import from file
zot delete ABC123 --yes # Delete (move to trash)
Collections
zot collection list # List all collections (tree view)
zot collection items COLML01 # View items in a collection
zot collection create "New Project" # Create a new collection
Workspaces
Why workspaces? Zotero collections are great for permanent library organization, but research often requires temporary, cross-cutting groupings β "all papers for my ICML submission", "papers to discuss at lab meeting", or "references for Chapter 3". Workspaces fill this gap: they're lightweight, local-only views that don't modify your Zotero library. Each workspace is a simple TOML file at
~/.config/zot/workspaces/<name>.tomlcontaining item key references β no API key needed, no syncing side effects. Combined with built-in RAG indexing, workspaces become a powerful bridge between your Zotero library and AI coding assistants like Claude Code.
# Create and populate a workspace
zot workspace new llm-safety --description "LLM alignment papers"
zot workspace add llm-safety ABC123 DEF456 GHI789
zot workspace import llm-safety --collection "Alignment" # Bulk import from collection
zot workspace import llm-safety --tag "safety" # or by tag
zot workspace import llm-safety --search "RLHF" # or by search
# Browse workspace
zot workspace list # List all workspaces
zot workspace show llm-safety # View items with metadata
zot workspace search "reward" --workspace llm-safety # Search within workspace
# Export for AI consumption
zot workspace export llm-safety # Markdown (for Claude Code)
zot workspace export llm-safety --format json # JSON
zot workspace export llm-safety --format bibtex # BibTeX
# Built-in RAG: index and query
zot workspace index llm-safety # Build BM25 index (metadata + PDF text)
zot workspace index llm-safety --extractor mineru # Use MinerU for higher-quality PDF text
zot workspace query "reward hacking methods" --workspace llm-safety
# Manage
zot workspace remove llm-safety ABC123 # Remove item
zot workspace delete llm-safety --yes # Delete workspace
Optional semantic search β configure an embedding endpoint for hybrid BM25 + vector retrieval. Multiple providers are supported via [embedding] provider (jina (default) / aliyun / openai):
# Jina AI (default, 10M free tokens)
export ZOT_EMBEDDING_URL="https://api.jina.ai/v1/embeddings"
export ZOT_EMBEDDING_KEY="your-jina-key"
# Or Aliyun DashScope (OpenAI-compatible)
export ZOT_EMBEDDING_PROVIDER=aliyun
export ZOT_EMBEDDING_KEY="your-dashscope-key"
zot workspace index llm-safety --force # Rebuild with embeddings
zot workspace query "reward hacking" --workspace llm-safety --mode hybrid
Profiles & Cache
zot config profile list # List all config profiles
zot config profile set lab # Set default profile
zot config cache stats # Show PDF cache statistics
zot config cache clear # Clear PDF cache
Preprint Status Check
# Check if arXiv/bioRxiv/medRxiv preprints have been published (dry-run)
zot update-status
# Actually update Zotero metadata for published papers
zot update-status --apply
# Check a single item
zot update-status ABC123
# Check items in a collection
zot update-status --collection "scRNA-seq" --limit 20
Uses the Semantic Scholar API. Optional API key for faster rate limits:
export S2_API_KEY=your_key_here # in ~/.zshrc or ~/.bashrc
AI Features
zot summarize ABC123 # Structured summary (optimized for Claude Code)
zot pdf ABC123 # Extract PDF full text
zot pdf ABC123 --pages 1-5 # Extract specific pages
zot pdf ABC123 --outline # List headings as a numbered outline
zot pdf ABC123 --section 3 # Extract just section 3 from --outline
zot pdf ABC123 --extractor mineru # Use MinerU (auto-falls-back to pymupdf)
PDF extractors. Two backends are available: the default pymupdf (fast, no network), and mineru (higher-fidelity layout/equation/table parsing via the MinerU API; falls back to pymupdf on failure). Configure once via [pdf] extractor / [pdf] mineru_token in ~/.config/zot/config.toml, or via ZOT_PDF_EXTRACTOR / MINERU_TOKEN env vars.
Global Flags
zot --json search "attention" # JSON output
zot --limit 5 list # Limit results
zot --detail minimal search "attention" # Minimal output (key/title/authors/year only)
zot --detail full read ABC123 # Full output (including extra fields)
zot --no-interaction delete ABC123 # Skip confirmation prompts (AI/script mode)
zot --profile lab search "CRISPR" # Use a specific config profile
zot --version # Show version
Shell Completions
# Zsh (recommended)
zot completions zsh >> ~/.zshrc
# Bash
zot completions bash >> ~/.bashrc
# Fish
zot completions fish > ~/.config/fish/completions/zot.fish
Restart your terminal or source the config file to enable tab completions.
Comparison with Similar Tools
| Feature | zotero-cli-cc | pyzotero-cli | zotero-cli | zotero-cli-tool | zotero-mcp | cookjohn/zotero-mcp | ZoteroBridge |
|---|---|---|---|---|---|---|---|
| Direct SQLite Read | β | β | β (cache only) | β | β | β (plugin) | β |
| Offline Read | β | β | β | β | β | β | β |
| No Zotero Running | β | β | β | β | β | β | β |
| Zero-Config Read | β | β | β | β | β | β | β |
| Safe Write (Web API) | β | β | β | β | β | β | β (direct SQLite) |
| PDF Full-Text | β | β | β | β | β | β | β |
| AI Coding Assistant | β Claude Code | Partial | β | β | Claude/ChatGPT | Claude/Cursor | Claude/Cursor |
| Terminal CLI | β | β | β | β | β | β | β |
| MCP Protocol | β | β | β | β | β | β | β |
| JSON Output | β | β | β | β | N/A | N/A | N/A |
| Note Management | β | β | β | β | β | β | β |
| Collections | β | β | β | β | β | β | β |
| Citation Export | β BibTeX/CSL-JSON/RIS | β | β | β Excel | β | β | β |
| Semantic Search | β Built-in (workspace RAG) | β | β | β | β | β | β |
| Detail Levels | β | β | β | β | β | β | β |
| Multi-Profile | β | β | β | β | β | β | β |
| PDF Cache | β | β | β | β | β | β | β |
| Library Maintenance | β | β | β | β | β | β | β |
| Language | Python | Python | Python | Python | Python | TypeScript | TypeScript |
| Active | β 2026 | β 2025 | β 2024 | β 2026 | β 2026 | β 2026 | β 2026 |
Why zotero-cli-cc?
The only actively maintained Python CLI that reads Zotero's local SQLite database directly.
- Fast: Millisecond response, no network latency
- Offline: No internet, no Zotero desktop needed
- Zero-Config: Install and go, no API key for reads
- AI-Native: Built for Claude Code,
--jsonoutput for AI consumption - Safe: Read/write separation β writes go through Web API to protect DB integrity
- Terminal-Native: The only CLI combining local SQLite reads with safe Web API writes; MCP tools require AI client, not usable in terminal
Architecture
Environment Variables
| Variable | Purpose |
|---|---|
ZOT_DATA_DIR | Override Zotero data directory path |
ZOT_LIBRARY_ID | Override Library ID (write operations) |
ZOT_API_KEY | Override API Key (write operations) |
ZOT_PROFILE | Override default config profile |
S2_API_KEY | Semantic Scholar API key (for update-status) |
ZOT_PDF_EXTRACTOR | PDF extractor: pymupdf (default) or mineru |
MINERU_TOKEN | API token for the MinerU PDF extractor |
ZOT_EMBEDDING_PROVIDER | Embedding provider: jina (default), aliyun, or openai |
ZOT_EMBEDDING_URL | Embedding API endpoint (default: Jina AI) |
ZOT_EMBEDDING_KEY | Embedding API key (enables semantic workspace search) |
ZOT_EMBEDDING_MODEL | Embedding model name (default: jina-embeddings-v3) |
TODO
- Improve HTML-to-Markdown: support lists, links, tables, and other common Zotero note formats (v0.1.2: uses markdownify)
-
summarize-allpagination: add offset/cursor pagination for large libraries (v0.1.2:--offsetflag) -
--dry-runfor destructive ops: add preview mode todelete,collection delete, andtag(v0.1.2)
Features
-
zot cite: copy formatted citation to clipboard (APA, Nature, Vancouver) - Bulk operations from file input (
zot add --from-file dois.txt) -
zot export: add RIS format support (BibTeX, CSL-JSON, RIS, JSON)
Tier 1 β High Value, Moderate Effort
-
zot update KEY --title/--date/--field: update item metadata (pyzoteroupdate_item()) -
zot search --type journalArticle: filter search results by item type -
zot search --sort dateAdded --direction desc: sort control for search/list -
zot recent --days 7: recently added/modified items -
zot pdf KEY --annotations: extract PDF annotations (highlights, comments, page numbers) β pymupdf
Tier 2 β High Value, Higher Effort
-
zot duplicates --by doi|title|both: duplicate detection (fuzzy title + DOI matching) -
zot trash list/restore: trash management (view + restore) -
zot attach KEY --file paper.pdf: attachment upload -
--library group:<id>: group library support (all commands + MCP tools) -
zot add --pdf paper.pdf: add from local PDF (auto-extract DOI + upload attachment)
Tier 3 β Medium Value
- Saved searches CRUD
- More export formats: BibLaTeX, MODS, TEI, CSV
- Formatted bibliography via citeproc-py with CSL styles
-
zot collection remove: remove item from collection (counterpart tocollection move) - BetterBibTeX citation key lookup support
Tier 4 β Nice to Have
- Semantic search via workspace RAG (BM25 + optional embeddings, v0.2.0)
- DOI-to-key index
- Version tracking / incremental sync
- Web interface (
zot serve) - View tags by collection
Polish
- GitHub Issues / Discussions setup for user feedback
- Improve
--helptext with usage examples - Shell completion install instructions in README (zsh/bash/fish)
Distribution
-
pipxinstall instructions - GitHub Releases with changelogs (v0.1.1, v0.1.2)
- README badges: PyPI version, CI status, Python versions, License
MCP Server
- Expand MCP tools: workspace, cite, stats, update-status (45 tools total)
- MCP server documentation / integration guide
Author
Agents365-ai
- GitHub: https://github.com/Agents365-ai
- Bilibili: https://space.bilibili.com/441831884
Support
WeChat Pay |
Alipay |
Buy Me a Coffee |
License
CC BY-NC 4.0 β Free for non-commercial use.
