# pyzotero

> Interact with Zotero reference management libraries using the pyzotero Python client to retrieve, create, update, and delete items, collections, tags, and attachments via the Zotero Web API v3.

**Use case**: Programmatically manage Zotero libraries with Python

**Canonical URL**: https://agentcookbooks.com/skills/pyzotero/

**Topics**: claude-code, skills, science, scientific-writing

**Trigger phrases**: "access my Zotero library", "export citations from Zotero", "search my Zotero collection", "add items to Zotero", "upload PDF to Zotero"

**Source**: [K-Dense AI](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/pyzotero)

**License**: MIT

---

## What it does

`pyzotero` is a Claude Code skill from K-Dense AI's [scientific-agent-skills repo](https://github.com/K-Dense-AI/scientific-agent-skills). It turns Claude into a Zotero API client that can read and write your Zotero reference library programmatically — retrieving items, searching by tag or collection, exporting formatted citations, uploading PDF attachments, and building automation workflows that integrate with Zotero's cloud sync.

A session produces working Python code that talks to the Zotero Web API v3 using the `pyzotero` client, along with the actual data retrieved or modified in your library.

## When to use it

Reach for it when:

- You want to export a filtered subset of your Zotero library (e.g., all items tagged "to-read" or in a specific collection) as a BibTeX file
- You're building a research automation workflow that needs to write new items or attachments back to Zotero
- You need to batch-update tags, collections, or metadata across many library items

When *not* to reach for it:

- Simple citation formatting for a manuscript — use `citation-management`
- You don't have a Zotero library or API key configured

## Install

Copy the `SKILL.md` from K-Dense AI's [pyzotero folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/pyzotero) into `.claude/skills/pyzotero/` in your project. You'll need a Zotero API key from [zotero.org/settings/keys](https://www.zotero.org/settings/keys) and your library ID.

Trigger phrases: "access my Zotero library", "export citations from Zotero", "search my Zotero collection".

## What a session looks like

A typical session has three phases:

1. **Authentication setup.** Claude checks for your Zotero API key and library ID, either from environment variables or prompts you to provide them. It confirms API access with a test call.
2. **Operation scoping.** You describe what you want — search, export, update, or upload. Claude maps the request to the appropriate pyzotero methods and pagination strategy for large libraries.
3. **Code execution and output.** Claude runs the pyzotero calls, handles rate limits, and returns the results: exported BibTeX, a list of matched items, or confirmation of writes.

## Receipts

**Where it works well:**
- Exporting a collection to BibTeX for a LaTeX project — pyzotero handles pagination cleanly for large libraries
- Batch tagging items based on metadata criteria (year range, author, journal)

**Where it backfires:**
- PDF full-text extraction is not part of pyzotero — it only manages metadata and attachment links, not file content
- Rate limits on the Zotero API can slow batch operations on libraries with thousands of items

**Pattern that works:** always check collection IDs and item keys before running write operations; read-then-write with a dry-run confirmation step prevents unintended library modifications.

## Source and attribution

Originally authored by [K-Dense Inc.](https://github.com/K-Dense-AI). The canonical SKILL.md lives in the [`pyzotero` folder](https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/scientific-skills/pyzotero) of their public scientific-agent-skills repository.

License: MIT. Install, adapt, and redistribute with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.