Zotero References for Claude Code

A Claude Code plugin that scopes selected Zotero libraries to a project repo and deploys an auto-triggering skill so coding agents can reference curated literature without an MCP server.

What this is for

You're working on a project that has an associated Zotero library — a research project, a thesis, a review article, a curated reading list of tool docs and talks. You want Claude to automatically consult those references when discussing the project's domain, instead of defaulting to web search or training-data recall.

This is reference recall — surfacing papers you've already curated to Zotero — not paper discovery across external corpora.

Install

Prerequisites

• Claude Code 2.1.118 or later (slash commands for plugin skills require the recent skills-as-commands merger).

• Python 3.10+.

• uv — the vendored scripts use PEP 723 inline metadata, so uv provisions an isolated environment with pyzotero on first invocation. You don't need to pip install anything yourself. The setup-zotero-references skill detects uv and offers to install it via the official one-line installer if missing:

  curl -LsSf https://astral.sh/uv/install.sh | sh

  Other install methods are documented in the uv installation guide.

• One of:

  • Zotero desktop running with "Allow other applications" enabled in Preferences → Advanced (gives the plugin a key-less local API at localhost:23119), OR
  • A ZOTERO_API_KEY from Zotero settings → Feeds/API added to .env in your target project (web API; required for abstract enrichment regardless).

Option 1: Per-session via --plugin-dir (recommended for testing)

Clone the repo once, then point claude at it when working in any other project:

# One-time clone
git clone https://github.com/benjibromberg/zotero-context.git ~/code/zotero-context

# In any project where you want the plugin
cd /path/to/your/project
claude --plugin-dir ~/code/zotero-context

The slash commands /zotero-context:setup-zotero-references and /zotero-context:enrich-zotero-abstracts will be available for that session, and the deployed using-zotero-references skill (once you've run setup) will auto-trigger on project-relevant topics in any future session in that project.

Option 2: Persistent via local marketplace (recommended for daily use)

Register the cloned repo as a Claude Code plugin marketplace, then install the plugin from it:

# One-time clone (skip if you did this for Option 1)
git clone https://github.com/benjibromberg/zotero-context.git ~/code/zotero-context

# Register as a marketplace and install (run inside a `claude` session)
/plugin marketplace add ~/code/zotero-context
/plugin install zotero-context@zotero-context

The plugin is now persistently enabled across all Claude Code sessions on this machine. To remove: /plugin uninstall zotero-context@zotero-context.

Option 3: Install from GitHub (no clone required)

Inside a claude session:

/plugin marketplace add benjibromberg/zotero-context
/plugin install zotero-context@zotero-context

Updates with /plugin marketplace update zotero-context.

Verifying the install

In any Claude Code session run:

/doctor

Expected output: a Plugins section listing zotero-context v0.2.0 as Enabled. If it shows up with a "Plugin Errors" entry, run /reload-plugins and re-check.

Updating

• Option 1 (--plugin-dir): cd ~/code/zotero-context && git pull. Takes effect on next claude --plugin-dir ... invocation.
• Options 2 and 3 (marketplace): in any Claude Code session, run /plugin marketplace update zotero-context, then /reload-plugins. (Marketplaces are identified by the name field in marketplace.json, regardless of whether you registered them from a local path or from benjibromberg/zotero-context on GitHub.)

Existing target projects keep using their vendored copy of .zotero-context/bin/ until you re-run /zotero-context:setup-zotero-references (which re-vendors the latest scripts).

Setup

In a target project repo:

# 1. (optional) Add API key for web-API fallback / writes
echo "ZOTERO_API_KEY=..." >> .env

# 2. Run setup in a Claude Code session
/zotero-context:setup-zotero-references

The setup skill will:

1. Detect uv and offer to install it if missing (one-line curl … | sh).
2. Detect your Zotero connection (local API preferred, web API fallback).
3. List your libraries.
4. Prompt which to scope to this project.
5. Sample each chosen library and propose trigger keywords + descriptions.
6. Write .zotero-context/config.json, vendor scripts to .zotero-context/bin/, render .claude/skills/using-zotero-references/SKILL.md, and append a section to CLAUDE.md.

After setup, future Claude sessions in this repo auto-trigger reference lookups via:

.zotero-context/bin/search_items.py --query "<topic>"

The first invocation triggers uv to install pyzotero into a script-scoped cache (~5MB, one-time). Subsequent invocations are instant.

Skills

Skill	Where	When
/zotero-context:setup-zotero-references	Plugin	One-time per project
using-zotero-references	Deployed into target repo	Auto-trigger on project-relevant topics
/zotero-context:enrich-zotero-abstracts	Plugin	Periodic write-back to fix thin abstracts

Reference search CLI

.zotero-context/bin/search_items.py --help

Key flags: --query, --filter-tag, --filter-item-type, --year, --year-range, --has-abstract, --no-abstract, --lib, --include-notes, --include-annotations, --output {summary,full,bib}, --format {json,md,table}.

Companion: .zotero-context/bin/get_item.py --key <key>.

Related projects

Zotero-for-LLM tooling has converged on roughly three different jobs, each with a different shape of tool. Worth knowing which one fits your problem — you might reasonably use more than one.

Job	Shape	Example
Library reference: teach an agent how to call pyzotero generically, account-wide	One skill in a large catalog of "how-to-use-library-X" skills	K-Dense-AI/scientific-agent-skills/pyzotero
Discovery: find and triage new papers across external corpora	Standalone multi-agent app you switch into	VirtualPatientEngine/AIAgents4Pharma (talk2scholars)
Recall: surface papers you've already curated, in the project you're working in	Project-scoped plugin (a skill + scripts inside your repo)	zotero-context (this project)

zotero-context is the recall tool. It scopes a subset of your Zotero libraries to a single project repo and deploys a skill that auto-triggers when you discuss that project's domain. It does not search Semantic Scholar / arXiv / PubMed (use Talk2Scholars for that), and it does not aim to teach Claude generic pyzotero CRUD across your whole account (use the K-Dense-AI catalog skill for that).

Library reference: skill catalogs

K-Dense-AI/scientific-agent-skills is a large catalog of agent skills — 140+ at last count — covering scientific Python libraries like biopython, scanpy, rdkit, pymc, and many more. The pyzotero skill inside it is a generic reference manual: it teaches Claude how to authenticate, fetch items, write items, manage collections, upload attachments, and export citations against the whole Zotero Web API v3.

Use it instead of zotero-context when you want Claude to know how to script against pyzotero in general (one-off automations, library-wide audits, write-heavy workflows) rather than auto-trigger curated-reference lookups from a project's domain keywords. Different shape: a per-library how-to skill, not a per-project workflow.

Discovery: standalone research apps

talk2scholars is a Streamlit + Python multi-agent app inside the AIAgents4Pharma "talk2X" suite (alongside talk2biomodels, talk2cells, talk2knowledgegraphs, ...). A supervisor agent routes queries to specialized sub-agents — S2 search, PDF, Zotero, Paper Download — backed primarily by Semantic Scholar, with arXiv / PubMed / BioRxiv / MedRxiv layered in. Integration with the user's own Zotero library is currently "in process"; discovery across external corpora is the primary capability today.

Use it instead of zotero-context when you want a conversational app for finding new papers, not for surfacing your already-curated ones. Different host (Streamlit), different paradigm (a separate destination app, not embedded in your IDE).

Recall: other Zotero-for-Claude plugins

Other projects in the same paradigm as zotero-context — Zotero-aware extensions that run inside a Claude session:

Project	Distinguishes
urschrei/zotero_search_skill	User-global skill; we are project-scoped with templated triggers.
WenyuChiou/zotero-skills	User-global; we add per-project library descriptions and keyword templating.
54yyyu/zotero-mcp	MCP server (different protocol); we use plain scripts + skills.
X1AOX1A/ZoFiles	Mirrors libraries into Zotero plugin storage; we scope per-repo.

Architecture

See docs/architecture.md for the full design.

Development

Tests

pip install -e ".[dev]"
python -m pytest -v

Linting

ruff check scripts/ tests/ tools/
ruff format --check scripts/ tests/ tools/
python tools/lint_skill_frontmatter.py

Pre-commit hooks

pre-commit install                # one-time
pre-commit run --all-files        # run all hooks against all files

CI runs the full test matrix (Python 3.10–3.12) and lint suite on every push and pull request.

License

MIT.