Skip to content
Back to search

zotero-mcp

Lightweight Model Context Protocol (MCP) server for the Zotero API, in Python

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/kujenga--zotero-mcp/badge.svg)](/listings/kujenga--zotero-mcp)

HTML

<a href="/listings/kujenga--zotero-mcp"><img src="/api/listings/kujenga--zotero-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This server can either run against either a [local API offered by the Zotero desktop application](https://groups.google.com/g/zotero-dev/c/ElvHhIFAXrY/m/fA7SKKwsAgAJ)) or through the [Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start). The local API can be a bit more responsive, but requires that the Zotero app be running on the same computer with the API enabled. To enable the local API, do the following steps:

1. Open Zotero and open "Zotero Settings" 1. Under the "Advanced" tab, check the box that says "Allow other applications on this computer to communicate with Zotero".

To use the Zotero Web API, you'll need to create an API key and find your Library ID (usually your User ID) in your Zotero account settings here: <https://www.zotero.org/settings/keys>

These are the available configuration options:

- `ZOTERO_LOCAL=true`: Use the local Zotero API (default: false, see note below) - `ZOTERO_API_KEY`: Your Zotero API key (not required for the local API) - `ZOTERO_LIBRARY_ID`: Your Zotero library ID (your user ID for user libraries, not required for the local API) - `ZOTERO_LIBRARY_TYPE`: The type of library (user or group, default: user)

[`uvx`](https://docs.astral.sh/uv/getting-started/installation/) with Local Zotero API

To use this with Claude Desktop and a direct python install with [`uvx`](https://docs.astral.sh/uv/getting-started/installation/), add the following to the `mcpServers` configuration:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp@latest"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

The `@latest` specifier is optional and will pull the latest version when new ones are available. If you don't have `uvx` installed you can use `pipx run` instead, or clone this repository locally and use the instructions in [Development](#development) below.

Docker with Zotero Web API

If you want to run this MCP server in a Docker container, you can use the following configuration, inserting your API key and library ID:

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ],
    }
  }
}

To update to a newer version, run `docker pull ghcr.io/kujenga/zotero-mcp:main`. It is also possible to use the docker-based installation to talk to the local Zotero API, but you'll need to modify the above command to ensure that there is network connectivity to the Zotero application's local API interface.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 174 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Model Context Protocol server for Zotero
  2. [![GitHub branch status](https://img.shields.io/github/check-runs/kujenga/zotero-mcp/main)](https://github.com/kujenga/zotero-mcp/actions)
  3. [![PyPI - Version](https://img.shields.io/pypi/v/zotero-mcp)](https://pypi.org/project/zotero-mcp/)
  4. <!-- Ownership verification marker for the official MCP registry, which
  5. matches it against the name in server.json when this README is rendered on
  6. PyPI: https://modelcontextprotocol.io/registry/package-types -->
  7. <!-- mcp-name: io.github.kujenga/zotero-mcp -->
  8. This project is a python server that implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) for [Zotero](https://www.zotero.org/), giving you access to your Zotero library within AI assistants. It is intended to implement a small but maximally useful set of interactions with Zotero for use with [MCP clients](https://modelcontextprotocol.io/clients).
  9. <a href="https://glama.ai/mcp/servers/jknz38ntu4">
  10. <img width="380" height="200" src="https://glama.ai/mcp/servers/jknz38ntu4/badge" alt="Zotero Server MCP server" />
  11. </a>
  12. ## Features
  13. This MCP server provides the following tools:
  14. - `zotero_search_items`: Search for items in your Zotero library using a text query
  15. - `zotero_item_metadata`: Get the complete metadata for a specific Zotero item, covering every populated field grouped into publication details, identifiers, timestamps, and library information
  16. - `zotero_item_fulltext`: Get the full text of a specific Zotero item (i.e. PDF contents)
  17. These can be discovered and accessed through any MCP client or through the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
  18. Each tool returns formatted text containing relevant information from your Zotero items, and AI assistants such as Claude can use them sequentially, searching for items then retrieving their metadata or text content.
  19. ## Installation
  20. This server can either run against either a [local API offered by the Zotero desktop application](https://groups.google.com/g/zotero-dev/c/ElvHhIFAXrY/m/fA7SKKwsAgAJ)) or through the [Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start). The local API can be a bit more responsive, but requires that the Zotero app be running on the same computer with the API enabled. To enable the local API, do the following steps:
  21. 1. Open Zotero and open "Zotero Settings"
  22. 1. Under the "Advanced" tab, check the box that says "Allow other applications on this computer to communicate with Zotero".
  23. To use the Zotero Web API, you'll need to create an API key and find your Library ID (usually your User ID) in your Zotero account settings here: <https://www.zotero.org/settings/keys>
  24. These are the available configuration options:
  25. - `ZOTERO_LOCAL=true`: Use the local Zotero API (default: false, see note below)
  26. - `ZOTERO_API_KEY`: Your Zotero API key (not required for the local API)
  27. - `ZOTERO_LIBRARY_ID`: Your Zotero library ID (your user ID for user libraries, not required for the local API)
  28. - `ZOTERO_LIBRARY_TYPE`: The type of library (user or group, default: user)
  29. ### [`uvx`](https://docs.astral.sh/uv/getting-started/installation/) with Local Zotero API
  30. To use this with Claude Desktop and a direct python install with [`uvx`](https://docs.astral.sh/uv/getting-started/installation/), add the following to the `mcpServers` configuration:
  31. ```json
  32. {
  33. "mcpServers": {
  34. "zotero": {
  35. "command": "uvx",
  36. "args": ["zotero-mcp@latest"],
  37. "env": {
  38. "ZOTERO_LOCAL": "true",
  39. "ZOTERO_API_KEY": "",
  40. "ZOTERO_LIBRARY_ID": ""
  41. }
  42. }
  43. }
  44. }
  45. ```
  46. The `@latest` specifier is optional and will pull the latest version when new ones are available. If you don't have `uvx` installed you can use `pipx run` instead, or clone this repository locally and use the instructions in [Development](#development) below.
  47. ### Docker with Zotero Web API
  48. If you want to run this MCP server in a Docker container, you can use the following configuration, inserting your API key and library ID:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "zotero": {
  53. "command": "docker",
  54. "args": [
  55. "run",
  56. "--rm",
  57. "-i",
  58. "-e", "ZOTERO_API_KEY=PLACEHOLDER",
  59. "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
  60. "ghcr.io/kujenga/zotero-mcp:main"
  61. ],
  62. }
  63. }
  64. }
  65. ```
  66. To update to a newer version, run `docker pull ghcr.io/kujenga/zotero-mcp:main`. It is also possible to use the docker-based installation to talk to the local Zotero API, but you'll need to modify the above command to ensure that there is network connectivity to the Zotero application's local API interface.
  67. ## Development
  68. Information on making changes and contributing to the project.
  69. 1. Clone this repository
  70. 1. Install dependencies with [uv](https://docs.astral.sh/uv/) by running: `uv sync`
  71. 1. Create a `.env` file in the project root with the environment variables above
  72. Start the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for local development:
  73. ```bash
  74. npx @modelcontextprotocol/inspector uv run zotero-mcp
  75. ```
  76. To test the local repository against Claude Desktop, run `echo $PWD/.venv/bin/zotero-mcp` in your shell within this directory, then set the following within your Claude Desktop configuration
  77. ```json
  78. {
  79. "mcpServers": {
  80. "zotero": {
  81. "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
  82. "env": {
  83. // Whatever configuration is desired.
  84. }
  85. }
  86. }
  87. }
  88. ```
  89. ### Running Tests
  90. To run the test suite:
  91. ```bash
  92. uv run pytest
  93. ```
  94. ### Releasing
  95. 1. Bump the version in `pyproject.toml` and `server.json` (two places: the
  96. server version and the package version).
  97. 1. Publish to PyPI with `make publish`.
  98. 1. Publish updated metadata to the [official MCP
  99. registry](https://github.com/modelcontextprotocol/registry) with `make
  100. publish-mcp`, authenticating first with `mcp-publisher login github` if
  101. needed.
  102. ### Docker Development
  103. Build the container image with this command:
  104. ```sh
  105. docker build . -t zotero-mcp:local
  106. ```
  107. To test the container with the MCP inspector, run the following command:
  108. ```sh
  109. npx @modelcontextprotocol/inspector \
  110. -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
  111. -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
  112. docker run --rm -i \
  113. --env ZOTERO_API_KEY \
  114. --env ZOTERO_LIBRARY_ID \
  115. zotero-mcp:local
  116. ```
  117. ## Relevant Documentation
  118. - https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
  119. - https://github.com/modelcontextprotocol/python-sdk
  120. - https://pyzotero.readthedocs.io/en/latest/
  121. - https://www.zotero.org/support/dev/web_api/v3/start
  122. - https://modelcontextprotocol.io/llms-full.txt can be utilized by LLMs
  123. ## Appendix: notes on Zotero's API
  124. Item metadata is rendered from whatever fields the API returns rather than from
  125. a fixed list. Fields it omits are skipped, and fields this server doesn't know
  126. about appear under an "Other Fields" heading, so a Zotero upgrade never
  127. silently drops metadata.
  128. The two APIs differ in one way worth knowing: the local API's quick search
  129. indexes citation keys, while the Web API does not, so searching for one returns
  130. nothing over the Web API even though the field is present in the data.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.