| name | zotero |
| description | Query your local Zotero library. Supports keyword, fulltext, author, collection, tag, DOI, and recent-additions search. Trigger: /zotero, "my papers", "Zotero", "find paper", "references", "citations". After installation, verify DEFAULT_DB path in scripts/zotero-search.py points to your zotero.sqlite. |
Zotero Local Search
Query a local Zotero library (zotero.sqlite), read-only, zero external dependencies.
Setup: The default database path is ~/Zotero/zotero.sqlite (standard on macOS/Linux).
Windows users: change DEFAULT_DB in scripts/zotero-search.py to your Zotero data directory,
typically C:\Users\<username>\Zotero\zotero.sqlite.
You can also override per-call with --db PATH.
Tool
python3 .claude/skills/zotero/scripts/zotero-search.py <mode> <query> [options]
Search Modes
| Mode | Command | Description |
|---|
| Keyword search | search "query" | Search title, abstract, journal, authors, notes |
| Fulltext search | fulltext "word1 word2" | Search PDF body text (inverted index, exact word match, AND semantics), ranked by metadata relevance |
| Author search | author "name" | By author name (partial match) |
| Browse collection | collection list / collection "name" | List or browse collections |
| Recent additions | recent [--days N] | Items added in last N days (default: 30) |
| Tag search | tag list / tag "name" | List or search by tag |
| DOI lookup | doi "10.xxxx/..." | Exact DOI match |
| Get by key | get KEY1 KEY2 ... | Batch fetch by itemKey, preserves input order |
Global Options
| Flag | Default | Description |
|---|
--limit N | 20 | Max results |
--type TYPE | all | Filter by type: journalArticle / book / conferencePaper / preprint |
--compact | false | Compact output (title, authors, year, journal, URI only) — good for scanning |
--db PATH | ~/Zotero/zotero.sqlite | Override database path |
Instructions
1. Intent Mapping
Map user requests to search modes:
- "find/search + keywords" ->
search
- "papers by [author]" ->
author
- "what's in [collection]" ->
collection
- "recently added" ->
recent
- "tagged with X" ->
tag
- "do I have this DOI" ->
doi
- "paper mentions X" / "body text contains X" ->
fulltext
- Unsure -> default to
search
2. Search Execution
Run the command, get JSON results.
Strategy:
search mode auto-ranks by relevance (phrase match > whole word > substring), output includes relevance score- Two-stage retrieval: use
--compact first to scan results, then get KEY1 KEY2 ... to fetch full details for selected items
- For compound terms (e.g. "Neural ODE"), if
search is noisy, supplement with fulltext (exact word match, less noise)
3. Fallback
search returns nothing -> auto-try fulltext (keywords may appear in PDF body, not title/abstract).
4. Result Presentation
- 1-3 results: Show full info (title, authors, year, journal, abstract excerpt, DOI, zoteroURI)
- 4-10 results: Title + authors + year list, offer to expand
- 10+ results: Show count + title list, suggest narrowing query
- Always include
zoteroURI (clickable link to open in Zotero)
5. Writing Assistance
When the user is writing a paper/document:
- Proactively provide citation format:
(Author, Year)
- Include DOI for cross-referencing
- If abstract available, briefly summarize the paper's key contribution
6. Combined Queries
No complex SQL needed. For "papers by [author] about [topic]":
- Run
search "topic keywords"
- Filter results by matching the author field in returned JSON
Notes
fulltext is exact word match (no phrases, no fuzzy, no stemming), multi-word = AND- Tag coverage varies by library; not the primary search method
- Some items may lack abstracts — this is normal
