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.

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

Authentication Setup

Required credentials — get from https://www.zotero.org/settings/keys:

• User ID: shown as "Your userID for use in API calls"
• API Key: create at https://www.zotero.org/settings/keys/new
• Library ID: for group libraries, the integer after /groups/ in the group URL

Store credentials 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

from pyzotero import Zotero

zot = Zotero(library_id='123456', library_type='user', api_key='ABC1234XYZ')

# 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())

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

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.