alterlab-pyzotero

Work with your Zotero reference library from code — search and read items, collections and tags, export BibTeX / CSL-JSON / RIS, find duplicates and missing DOIs, and create, update or delete items, c

SKILL.md

GitHub

Pyzotero

Pyzotero is a Python wrapper for the Zotero API v3 (current release 1.15.x as of 2026-09). Use it to programmatically manage Zotero libraries: read items and collections, create and update references, upload attachments, manage tags, and export citations. It also ships an optional CLI and MCP server for a local Zotero library.

No key is needed for the user's own library. Pick the access path before writing code:

Path Needs Reads Writes
Local API (default when Zotero is open) Zotero 7+ desktop running, Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" everything: items, collections, tags, full text, saved searches Zotero 10+ after the user clicks Allow in Zotero (authorize_local) — a local key, not a zotero.org key
Exported file (Zotero closed, another machine, a colleague's export) a .bib (Better BibTeX auto-export, or File > Export Library), CSL JSON or RIS file scripts/zotero_export.py: search, tags, stats, duplicates, missing fields, subset export an importable RIS / CSL JSON / BibTeX file the user adds with File > Import… (new-item --doi fills metadata from Crossref, keyless)
Web API (optional) ZOTERO_API_KEY + ZOTERO_LIBRARY_ID from zotero.org/settings/keys the synced web library, incl. group libraries direct create / update / delete, file uploads

Ask for (or check) which one applies only when it matters; when the user has given an export file, use it; when they have neither file nor key, write the local-API code and say which Zotero setting it needs. Never ask the user to paste a key into the chat.

When to Use This Skill

  • Reading, searching, or bulk-editing items, collections, and tags in a Zotero library from code
  • Creating items from templates, attaching PDFs, or exporting BibTeX / CSL-JSON / formatted bibliographies
  • Automating research workflows that sync with Zotero (web library or the local desktop app)
  • Scripting the local Zotero library from the terminal (pyzotero CLI) or exposing it to an AI client (MCP server)

Does NOT Trigger

Scenario Use Instead
Discovering new papers in scholarly databases alterlab-research-lookup
Converting DOIs to BibTeX or searching Google Scholar/PubMed without a Zotero library alterlab-citation-mgmt
Checking that every bibliography entry exists / spotting hallucinated references alterlab-citation-verifier
Building an evidence table from a folder of PDFs alterlab-pdf-extract

Hand-off rule. When the request matches a row above, open your answer by naming that skill by its exact id (for example alterlab-research-lookup) and saying in one line why it fits better, then stop applying this skill's procedure. Name it even when you also need to ask for missing input. If only part of the request is out of scope, name the skill for that part and do only the in-scope part. A brief general pointer is fine; the named skill does the work.

Connecting

Local API (no key). In Zotero 7+, enable Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" and keep Zotero open; pyzotero then talks to http://localhost:23119/api/ with Zotero(library_id='0', library_type='user', local=True). Every read method below works unchanged.

Web API (optional key) — for a library on another machine, group libraries, or writes without Zotero 10 — get from https://www.zotero.org/settings/keys:

Ask the user to store them in environment variables or a .env file:

ZOTERO_LIBRARY_ID=your_user_id
ZOTERO_API_KEY=your_api_key
ZOTERO_LIBRARY_TYPE=user  # or "group"

See references/authentication.md for full setup details.

Installation

uv add pyzotero
# or with CLI support (local library search, writes, collection management):
uv add "pyzotero[cli]"
# or the MCP server (read-only unless started with --enable-writes):
uv add "pyzotero[mcp]"

Quick Start

import os
from pyzotero import Zotero

if os.environ.get("ZOTERO_API_KEY"):          # optional zotero.org Web API
    zot = Zotero(os.environ["ZOTERO_LIBRARY_ID"], os.environ.get("ZOTERO_LIBRARY_TYPE", "user"),
                 os.environ["ZOTERO_API_KEY"])
else:                                          # keyless: the running Zotero 7+ desktop app
    zot = Zotero(library_id='0', library_type='user', local=True)

# Retrieve top-level items (returns 100 by default)
items = zot.top(limit=10)
for item in items:
    print(item['data']['title'], item['data']['itemType'])

# Search by keyword
results = zot.items(q='machine learning', limit=20)

# Retrieve all items (use everything() for complete results)
all_items = zot.everything(zot.items())

Run it with uv run --python ">=3.11" --with pyzotero python script.py. A connection error on the local path means Zotero is closed or the setting is off — say which, or offer the exported-file path.

Exported Library Files (offline, no key, no running Zotero)

When the user has (or can make) an export — Better BibTeX's auto-exported .bib, File > Export Library… as BibTeX/BibLaTeX, CSL JSON or RIS — scripts/zotero_export.py (stdlib only) answers the usual questions directly from the file. Tags are BibTeX keywords (CSL JSON exports carry none); item types are normalised to CSL names (article-journal, paper-conference, book, chapter, report, manuscript, …).

S=scripts/zotero_export.py
python $S stats   my_library.bib                       # counts by type/year, top tags, missing DOIs, duplicate groups
python $S search  my_library.bib --tag "machine learning"          # repeat --tag for AND; -q "words" for text
python $S dupes   my_library.bib                       # same DOI (case-insensitive), or same title + year
python $S missing my_library.bib --field doi           # also abstract, year, authors, container, pages
python $S export  my_library.json --type article-journal --year-from 2020 --to bibtex -o recent.bib
python $S new-item --doi 10.1038/nature14539 --tag to-read --to ris -o to_import.ris   # Crossref metadata

Report results by citation key and DOI (title when an item has none), one line per item, so the user can check the selection and find each item in Zotero; export -o prints that list for what it wrote. export keeps Better BibTeX keys and turns CSL item URIs into author+year+word keys. "Writes" on this path never touch the library: they produce a file the user imports with File > Import… — or, for a few DOIs, tell them to paste the DOIs into Zotero's Add Item by Identifier (magic-wand) button, which is keyless too. Fixing metadata, merging duplicates and moving items between collections in place need the local API (Zotero 10+ writes) or the Web API.

Core Concepts

  • A Zotero instance is bound to a single library (user or group). All methods operate on that library.
  • Item data lives in item['data']. Access fields like item['data']['title'], item['data']['creators'].
  • Pyzotero returns 100 items by default (API default is 25). Use zot.everything(zot.items()) to get all items.
  • Write methods return True on success or raise a PyZoteroError subclass (from pyzotero.errors; all class names end in Error, e.g. ResourceNotFoundError).

Reference Files

File Contents
references/authentication.md Credentials, library types, local mode
references/read-api.md Retrieving items, collections, tags, groups
references/search-params.md Filtering, sorting, search parameters
references/write-api.md Creating, updating, deleting items
references/collections.md Collection CRUD operations
references/tags.md Tag retrieval and management
references/files-attachments.md File retrieval and attachment uploads
references/exports.md BibTeX, CSL-JSON, bibliography export
references/pagination.md follow(), everything(), generators
references/full-text.md Full-text content indexing and retrieval
references/saved-searches.md Saved search management
references/cli.md Command-line interface usage
references/error-handling.md Errors and exception handling
scripts/zotero_export.py Offline search / stats / duplicates / export over .bib, CSL JSON, RIS

Common Patterns

Fetch and modify an item

item = zot.item('ITEMKEY')
item['data']['title'] = 'New Title'
zot.update_item(item)

Create an item from a template

template = zot.item_template('journalArticle')
template['title'] = 'My Paper'
template['creators'][0] = {'creatorType': 'author', 'firstName': 'Jane', 'lastName': 'Doe'}
zot.create_items([template])

Export as BibTeX

zot.add_parameters(format='bibtex')
bibtex = zot.top(limit=50)
# bibtex is a bibtexparser BibDatabase object
print(bibtex.entries)

Local mode (no web API key)

Talks to the running Zotero desktop app (Zotero 7+, with "Allow other applications on this computer to communicate with Zotero" enabled in Settings > Advanced). Reads need no key:

zot = Zotero(library_id='0', library_type='user', local=True)
items = zot.items()

Writes to the local library are possible only with Zotero 10 or later and the user's consent: zot.authorize_local("My script") makes Zotero show an Allow / Always Allow / Deny dialog. "Allow" yields a single-use key; "Always Allow" yields a key you can store and pass back as Zotero(..., local=True, local_api_key=...). Local API keys are unrelated to zotero.org API keys. Details: references/authentication.md.

Part of the AlterLab Academic Skills suite.