zotero mcp

Local 2025-08-31 23:27:11 0

This server allows users to interact with their Zotero library through the Model Context Protocol, providing tools for searching items, retrieving metadata, and accessing full text using natural language queries.

This project is a python server that implements the Model Context Protocol (MCP) for Zotero, 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.

Features

This MCP server provides the following tools:

zotero_search_items: Search for items in your Zotero library using a text query
zotero_item_metadata: Get detailed metadata information about a specific Zotero item
zotero_item_fulltext: Get the full text of a specific Zotero item (i.e. PDF contents)

These can be discovered and accessed through any MCP client or through the MCP Inspector.

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.

Installation

To use this with Claude Desktop, add the following to the mcpServers configuration:

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

The ZOTERO_LOCAL setting points the plugin to the local Zotero API and requires Zotero 7 (or the beta version, see note below) running on the same machine as the client.

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

The following environment variables provide 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)

[!IMPORTANT] For access to the fulltext API locally, an upcoming Zotero release is required. In the meantime you'll need to install a Zotero Beta Build for that functionality to work (as of 2025-03-07). See https://github.com/zotero/zotero/pull/5004 for more information.

Development

Clone this repository
Install dependencies with uv by running: uv sync
Create a .env file in the project root with the environment variables above

Start the MCP Inspector for local development:

npx @modelcontextprotocol/inspector uv run zotero-mcp

Running Tests

To run the test suite:

uv run pytest

Relevant Documentation

https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
https://github.com/modelcontextprotocol/python-sdk
https://pyzotero.readthedocs.io/en/latest/
https://www.zotero.org/support/dev/web_api/v3/start

[
  {
    "description": "Get metadata information about a specific Zotero item, given the item key.",
    "inputSchema": {
      "properties": {
        "item_key": {
          "title": "Item Key",
          "type": "string"
        }
      },
      "required": [
        "item_key"
      ],
      "title": "get_item_metadataArguments",
      "type": "object"
    },
    "name": "zotero_item_metadata"
  },
  {
    "description": "Get the full text content of a Zotero item, given the item key of a parent item or specific attachment.",
    "inputSchema": {
      "properties": {
        "item_key": {
          "title": "Item Key",
          "type": "string"
        }
      },
      "required": [
        "item_key"
      ],
      "title": "get_item_fulltextArguments",
      "type": "object"
    },
    "name": "zotero_item_fulltext"
  },
  {
    "description": "Search for items in your Zotero library, given a query string, query mode (titleCreatorYear or everything), and optional tag search (supports boolean searches). Returned results can be looked up with zotero_get_fulltext or zotero_get_metadata.",
    "inputSchema": {
      "properties": {
        "limit": {
          "anyOf": [
            {
              "type": "integer"
            },
            {
              "type": "null"
            }
          ],
          "default": 10,
          "title": "Limit"
        },
        "qmode": {
          "anyOf": [
            {
              "enum": [
                "titleCreatorYear",
                "everything"
              ],
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": "titleCreatorYear",
          "title": "Qmode"
        },
        "query": {
          "title": "Query",
          "type": "string"
        },
        "tag": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": {
            "path": "README.md",
            "type": "blob"
          },
          "title": "Tag"
        }
      },
      "required": [
        "query"
      ],
      "title": "search_itemsArguments",
      "type": "object"
    },
    "name": "zotero_search_items"
  }
]