Pyzotero

Pyzotero is a Python client library for the Zotero Web API. It wraps Zotero’s REST endpoints so you can programmatically read and write bibliographic data in personal and group libraries: fetch and create items, manage collections and tags, handle attachments and file uploads, and page through large result sets without dealing with raw HTTP.

Widely used in the digital-humanities and research-tooling communities, Pyzotero maps Zotero’s data model onto convenient Python methods, handles authentication with API keys, and takes care of pagination, retries, and response parsing. Recent versions also ship async support, a CLI, and an MCP server for exposing Zotero data to AI agents.

What You Get

• A Zotero client covering items, collections, tags, groups, and searches
• Read and write access: create, update, and delete items and collections
• File attachment handling and uploads to Zotero storage
• Pagination, retries, and multiple response formats (JSON, BibTeX, formatted citations)
• Async client, a command-line interface, and an MCP server for AI-agent access

Common Use Cases

• Automating bibliography and reference management from Python scripts
• Bulk-importing or syncing references into a Zotero group library
• Exporting formatted citations or BibTeX for a research project
• Exposing a Zotero library to an LLM agent via the bundled MCP server

Under The Hood

Architecture - The package lives under src/pyzotero with a clear separation of concerns: zotero.py/_client.py hold the main client, _decorators.py implements pagination and response-format handling, _search.py builds queries, _upload.py handles attachments, and _types.py/errors.py define the data and error surface. Optional integrations (cli.py, mcp_server.py, semantic_scholar.py, async client) build on the same core.

Tech Stack - Pure Python packaged with pyproject.toml and managed via uv (uv.lock), using requests-style HTTP transport with a custom filetransport.py, and py.typed for shipped type hints. Docs are built for Read the Docs.

Code Quality - The project is actively maintained (~20 commits/month) with a substantial test suite (tests/test_zotero.py, test_async.py, test_mcp.py) backed by recorded API response fixtures under tests/api_responses. Modules are typed and cohesive, and errors are modeled explicitly in dedicated modules.

API Design - The client API is ergonomic and reads close to the Zotero data model (items(), collections(), top(), create_items()), with decorators hiding pagination and content-negotiation boilerplate. Extensive Read the Docs documentation and a quickstart keep onboarding short.