Pyzotero: An API Client for the Zotero API
Quickstart
uv add pyzoteroorpip install pyzoteroorconda install conda-forge::pyzotero- You'll need the ID of the personal or group library you want to access:
- Your personal library ID is available here, in the section
Your userID for use in API calls - For group libraries, the ID can be found by opening the group's page:
https://www.zotero.org/groups/groupname, and hovering over thegroup settingslink. The ID is the integer after/groups/
- Your personal library ID is available here, in the section
- You'll also need† to get an API key here
- Are you accessing your own Zotero library?
library_typeis'user' - Are you accessing a shared group library?
library_typeis'group'.
Then:
from pyzotero import Zotero
zot = Zotero(
library_id, library_type, api_key
) # local=True to use a running Zotero instead of the web API
items = zot.top(limit=5)
# we've retrieved the latest five top-level items in our library
# we can print each item's item type and ID
for item in items:
print(f"Item: {item['data']['itemType']} | Key: {item['data']['key']}")
Documentation
Full documentation of available Pyzotero methods, code examples, and sample output is available on Read The Docs.
Local Zotero API
Passing local=True directs Pyzotero at a running Zotero installation instead of the web API. Reads do not require authentication; writes require consent via a dialog in Zotero, and a Zotero version that supports local writes:
from pyzotero import Zotero
zot = Zotero("0", "user", local=True)
auth = zot.authorize_local("My Application") # Zotero prompts the user
zot.create_items([item])
A key granted with "Always Allow" can be stored and passed back later as local_api_key. Versions and keys are scoped to a single Zotero instance, identified by zot.server_id. See the local API documentation for how this works, how-to guides, and reference material.
Installation
- Using uv:
uv add pyzotero - Using pip:
pip install pyzotero - Using Anaconda:
conda install conda-forge::pyzotero
Pyzotero also provides an optional CLI and MCP server for working with a local Zotero library. Both require Zotero >= 7 (>= 10 for local writes) with local API access enabled: Zotero > Settings > Advanced > "Allow other applications on this computer to communicate with Zotero". Both are read-only unless you run pyzotero authorize, which stores a local API key. Both console scripts are installed whichever extra you choose.
Command-Line Interface
Pyzotero includes an optional CLI for searching your local Zotero library, adding items to it, and managing its collections.
- Using uv:
uv add "pyzotero[cli]" - Using pip:
pip install "pyzotero[cli]" - Without installing:
uvx --from "pyzotero[cli]" pyzotero search -q "your query"
pyzotero search -q "machine learning" --json
pyzotero search -q "climate change" --fulltext
pyzotero listcollections
pyzotero authorize --app-name "My tool" # store a local API key, which the write commands need
pyzotero createitem items.json --collection FD9AUNP2 --tag "to read"
Run pyzotero --help for the full list of commands, and see the CLI documentation for details of the write commands, search behaviour, and output formats.
MCP Server
Pyzotero includes an optional MCP server that exposes your local Zotero library and Semantic Scholar integration as tools.
- Using uv:
uv add "pyzotero[mcp]" - Using pip:
pip install "pyzotero[mcp]" - As a standalone tool:
uv tool install "pyzotero[mcp]"
Add it to your Claude Desktop configuration:
{
"mcpServers": {
"zotero": {
"command": "pyzotero-mcp"
}
}
}
The server is read-only by default. Starting it with --enable-writes registers tools that create and modify items and collections, and --enable-deletes additionally registers permanent deletion. See the MCP server documentation for the configuration, the full list of tools, and how the write tools behave.
Development
Installing from Source
git clone git://github.com/urschrei/pyzotero.git
cd pyzotero
git checkout main
# specify --dev if you're planning on running tests
uv sync
Testing
Run pytest . from the top-level directory. This requires the dev dependency group to be installed: uv sync --dev / pip install --group dev
Issues
The latest commits can be found on the main branch, although new features are currently rare. If you encounter an error, please open an issue.
Pull Requests
Pull requests are welcomed. Please read the contribution guidelines. In particular, please base your PR on the main branch.
Versioning
As of v1.0.0, Pyzotero is versioned according to Semver; version increments are performed as follows:
- MAJOR version will increment with incompatible API changes,
- MINOR version will increment when functionality is added in a backwards-compatible manner, and
- PATCH version will increment with backwards-compatible bug fixes.
Citation
Pyzotero has a DOI:
Stephan Hügel, The Pyzotero Authors (2019, May 18). urschrei/pyzotero: Version v1.3.15. http://doi.org/10.5281/zenodo.2917290
License
Pyzotero is licensed under the Blue Oak Model Licence 1.0.0. See LICENSE.md for details.
† This isn't strictly true: you only need an API key for personal libraries and non-public group libraries.
1 maintainer
Release files for pyzotero 1.15.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyzotero-1.15.2.tar.gz | 589.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyzotero-1.15.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 656.6 kB
Release files / pyzotero-1.15.2.tar.gz
| Download URL | pyzotero-1.15.2.tar.gz |
|---|---|
| Size | 589.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9affddd556ccfff88187fa0340ed3b36cb995ec3d1add5d697ae089b1f4ceaf2
|
|
BLAKE2b-256 checksum How to use checksums |
9dc5bb2688452fbcc0e2e58570ded39cb171c51c3ccb168717d7d7d6a7fbf70c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency logRelease files / pyzotero-1.15.2-py3-none-any.whl
| Download URL | pyzotero-1.15.2-py3-none-any.whl |
|---|---|
| Size | 67.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f793ac4163efce4b882c4c18bd9a395fe64ca009d7573afceec154fde1bedcdf
|
|
BLAKE2b-256 checksum How to use checksums |
566adce5377f1ddbb7e31c97c9607614c7072b61b63f9c704972521625057fd7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 18, 2026.
Transparency log
