Supported Python versions Docs PyPI Version Anaconda-Server Badge Downloads

Pyzotero: An API Client for the Zotero API

Quickstart

  1. uv add pyzotero or pip install pyzotero or conda install conda-forge::pyzotero
  2. 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 the group settings link. The ID is the integer after /groups/
  3. You'll also need† to get an API key here
  4. Are you accessing your own Zotero library? library_type is 'user'
  5. Are you accessing a shared group library? library_type is '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 need no authentication. Writes need the user's consent, given through a dialog in Zotero, and a Zotero version that supports local writes.

Using the local API

  1. In Zotero, enable Settings > Advanced > "Allow other applications on this computer to communicate with Zotero".
  2. Create a client with local=True. You can now read from the library.
  3. To write, call authorize_local() first, and approve the dialog Zotero displays:
from pyzotero import Zotero

zot = Zotero("0", "user", local=True)
auth = zot.authorize_local("My Application")  # Zotero prompts the user
zot.create_items([item])

How local write access works

authorize_local() returns a dict with a key and a remember flag. A key granted with "Allow" is single-use: the first successful write consumes it. A key granted with "Always Allow" has remember set to True; you can store it and pass it back on a later run as the local_api_key argument.

Versions reported by the local API are unrelated to web API versions, and are typically lower than those the local API reported before write support was added. They are scoped to zot.server_id, which identifies the Zotero instance. A program that persists local objects or versions must persist that ID alongside them and partition by it. See the documentation for a full explanation, more 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 with local API access enabled: Zotero > Settings > Advanced > "Allow other applications on this computer to communicate with Zotero". The CLI does not modify your library; its authorize command exists to obtain a local API key for granting write access to the MCP server. The MCP server is read-only by default, and needs that key only if started with --enable-writes.

Command-Line Interface

Pyzotero includes an optional CLI for searching and querying your local Zotero library.

Installing the CLI

  • Using uv: uv add "pyzotero[cli]"
  • Using pip: pip install "pyzotero[cli]"

Or run it directly without installing:

  • Using uvx: uvx --from "pyzotero[cli]" pyzotero search -q "your query"
  • Using pipx: pipx run --spec "pyzotero[cli]" pyzotero search -q "your query"

Usage

# Search for top-level items
pyzotero search -q "machine learning"

# Search with full-text mode
pyzotero search -q "climate change" --fulltext

# Filter by item type
pyzotero search -q "methodology" --itemtype book --itemtype journalArticle

# Search for top-level items within a collection
pyzotero search --collection ABC123 -q "test"

# Output as JSON for machine processing
pyzotero search -q "climate" --json

# List all collections
pyzotero listcollections

# List available item types
pyzotero itemtypes

# Obtain a local API key, for granting write access to the MCP server
pyzotero authorize --app-name "Claude Desktop"

Search Behaviour

By default, pyzotero search searches only top-level item titles and metadata fields.

When the --fulltext flag is used, the search expands to include all full-text indexed content, including PDFs and other attachments. Since most full-text content comes from PDF attachments rather than top-level items, the CLI automatically retrieves the parent bibliographic items for any matching attachments. This ensures you receive useful bibliographic records (journal articles, books, etc.) rather than raw attachment items.

Output Format

By default, the CLI outputs human-readable text with a subset of metadata including:

  • Title, authors, date, publication
  • Volume, issue, DOI, URL
  • PDF attachments (with local file paths)

Use the --json flag to output structured JSON.

MCP Server

Pyzotero includes an optional MCP server that exposes your local Zotero library and Semantic Scholar integration as tools for LLMs. This lets sandboxed applications such as Claude Desktop access your Zotero library without needing direct CLI access.

Installing the MCP server

  • Using uv: uv add "pyzotero[mcp]"
  • Using pip: pip install "pyzotero[mcp]"
  • As a standalone tool: uv tool install "pyzotero[mcp]"

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

If pyzotero-mcp is installed:

{
  "mcpServers": {
    "zotero": {
      "command": "pyzotero-mcp"
    }
  }
}

Or, without installing, using uvx:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--from", "pyzotero[mcp]", "pyzotero-mcp"]
    }
  }
}

Available Tools

Zotero Library Tools

Tool Description
search Search the local Zotero library by query, item type, collection, tag, or full-text content
get_item Get a single Zotero item by its key
get_children Get child items (attachments, notes) of a Zotero item
list_collections List all collections in the library
list_tags List all tags, optionally filtered by collection
get_fulltext Get full-text content of a PDF or other attachment

Semantic Scholar Tools

Tool Description
find_related Find semantically similar papers using SPECTER2 embeddings
get_citations Find papers that cite a given paper
get_references Find papers referenced by a given paper
search_semantic_scholar Search across Semantic Scholar's paper index

The Semantic Scholar tools can optionally check whether results already exist in your local Zotero library (enabled by default via the check_library parameter).

Write Tools (opt-in)

The server is read-only unless started with --enable-writes.

Enabling write tools

  1. Obtain a persistent local API key, choosing "Always Allow" in Zotero's dialog:

    pyzotero authorize --app-name "Claude Desktop"

  2. Pass the key in the server's environment, and add the --enable-writes flag:

    {
  "mcpServers": {
    "zotero": {
      "command": "pyzotero-mcp",
      "args": ["--enable-writes"],
      "env": { "PYZOTERO_LOCAL_API_KEY": "your-key-here" }
    }
  }
}

  3. Optional: set PYZOTERO_LOCAL_SERVER_ID in the same env block to save one request at startup. Without it, the server fetches the ID automatically.

Available write tools

Tool Description
list_item_fields List the fields and creator types valid for an item type
create_item Create a new item
update_item Update fields on an existing item
add_tags Add tags to an existing item
create_collection Create a collection, optionally nested
add_to_collection File an existing item under a collection
add_attachment Attach a file on disk to an existing item
delete_item Permanently delete an item. Requires --enable-deletes

How the write tools behave

Without --enable-writes, the write tools are not merely disabled: they are never registered, so they do not appear in the model's tool list at all, and content in your library cannot induce a call to one.

add_attachment requires an absolute path. The server runs as a subprocess of your MCP client, so its working directory is not yours, and a relative path would resolve somewhere unintended; relative paths are rejected rather than guessed at. The file is copied into Zotero's storage, and syncs with the library if sync is enabled. Attaching a file that is already attached to the item is reported as unchanged rather than duplicated, so a retried call is safe.

delete_item is behind a second flag because deletion via the local API is irreversible: items are erased outright rather than moved to the trash, and the deletion propagates on sync. --enable-deletes implies --enable-writes.

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:

  1. MAJOR version will increment with incompatible API changes,
  2. MINOR version will increment when functionality is added in a backwards-compatible manner, and
  3. PATCH version will increment with backwards-compatible bug fixes.

Citation

Pyzotero has a DOI: DOI You may also cite Pyzotero using CITATION.cff. A sample citation (APA 6th edition) might look like:

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.

Project links

Data verified by PyPI on Aug 18, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for urschrei from gravatar.com urschrei

Credits

Author/Maintainer: Stephan Hügel

GitHub Statistics

Data verified by PyPI on Aug 18, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

BlueOak-1.0.0
View SPDX License List

Requires

Python >=3.10

Provides Extra

cli mcp

Tags

Zotero DH

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyzotero-1.14.0.tar.gz (577.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

pyzotero-1.14.0-py3-none-any.whl (63.2 kB view details)

Uploaded Python 3

File details

Details for the file pyzotero-1.14.0.tar.gz.

File metadata

  • Download URL: pyzotero-1.14.0.tar.gz
  • Upload date:
  • Size: 577.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyzotero-1.14.0.tar.gz
Algorithm Hash digest
SHA256 7cdb33c7a592b86502660ed1ef51886af72a23f5d467b711294522044f41d78b
MD5 acfa056e5fdb3bef5545dcf8cdfd7e59
BLAKE2b-256 4c2d7f53cf7a0f422758ffb0ad36c08c84b3458e61d0f93a1306d440f5f4740a

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyzotero-1.14.0.tar.gz:

Publisher: tests.yml on urschrei/pyzotero

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pyzotero-1.14.0-py3-none-any.whl.

File metadata

  • Download URL: pyzotero-1.14.0-py3-none-any.whl
  • Upload date:
  • Size: 63.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyzotero-1.14.0-py3-none-any.whl
Algorithm Hash digest
SHA256 394a14f074c417055fceaa2970b594ce925a6094c9d3dcc8a734e07426ecf415
MD5 e7ba43806699e0d82749f486cc2a03c1
BLAKE2b-256 fd34488df35f6d33de5d97828defd971be124e31cbe533f74479741ed4942dfa

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyzotero-1.14.0-py3-none-any.whl:

Publisher: tests.yml on urschrei/pyzotero

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

1.14.0 This release

2 files

1.13.7

2 files

1.13.6

2 files

1.13.5

2 files

1.13.4

2 files

1.13.3

2 files

1.13.2

2 files

1.13.1

2 files

1.13.0

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.0

2 files

1.9.0

2 files

1.8.0

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.17

2 files

1.6.16

2 files

1.6.15

2 files

1.6.14

2 files

1.6.13

2 files

1.6.11

2 files

1.6.10

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.28

2 files

1.5.27

2 files

1.5.25

2 files

1.5.24

2 files

1.5.20

2 files

1.5.19

2 files

1.5.18

2 files

1.5.17

2 files

1.5.16

2 files

1.5.15

2 files

1.5.10

2 files

1.5.9

2 files

1.5.5

2 files

1.5.4

2 files

1.5.3

2 files

1.5.2

2 files

1.5.1

2 files

1.5

1 file

1.4.26

2 files

1.4.25

2 files

1.4.24

2 files

1.4.23

2 files

1.4.22

2 files

1.4.21

2 files

1.4.20

2 files

1.4.18

2 files

1.4.16

2 files

1.4.15

2 files

1.4.14

2 files

1.4.13

2 files

1.4.12

2 files

1.4.11

2 files

1.4.10

2 files

1.4.9

2 files

1.4.8

2 files

1.4.7

2 files

1.4.6

2 files

1.4.5

2 files

1.4.4

2 files

1.4.3

2 files

1.4.1

2 files

1.4.0

2 files

1.3.16

2 files

1.3.15

2 files

1.3.12

2 files

1.3.11

2 files

1.3.10

2 files

1.3.9

2 files

1.3.8

2 files

1.3.7

2 files

1.3.6

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.15

2 files

1.2.14

2 files

1.2.13

2 files

1.2.12

2 files

1.2.11

2 files

1.2.10

2 files

1.2.9

2 files

1.2.8

2 files

1.2.7

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.0

2 files

1.1.24

2 files

1.1.22

2 files

1.1.21

2 files

1.1.20

2 files

1.1.19

2 files

1.1.18

2 files

1.1.17

2 files

1.1.16

2 files

1.1.15

2 files

1.1.14

2 files

1.1.13

1 file

1.1.12

2 files

1.1.11

2 files

1.1.10

2 files

1.1.9

2 files

1.1.8

2 files

1.1.7

2 files

1.1.6

2 files

1.1.5

2 files

1.1.4

2 files

1.1.3

2 files

1.1.2

2 files

1.1.1

2 files

1.1.0

2 files

1.0.1

2 files

1.0.0

2 files

0.10.2

1 file

0.10.1

1 file

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page