Skip to main content
Glama

Local Zotero MCP

An MCP server that gives an LLM read-only access to your local Zotero library via the desktop app's Local API. It talks to Zotero over http://127.0.0.1:23119, so nothing leaves your machine and no API keys are required.

Requirements

  • Zotero desktop app, running, with Settings > Advanced > "Allow other applications on this computer to communicate with Zotero" enabled.

  • uv installed.

Related MCP server: zotero-mcp

Quickstart

No cloning or installing required - uvx fetches the published package from PyPI and runs it. Add this to your Claude Desktop config (claude_desktop_config.json):

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

Restart Claude Desktop and the Zotero tools should be available. uvx caches the environment after the first run, so subsequent launches are fast; add --refresh to args if you want to force-pull the latest version.

Tools

Every library-scoped tool takes an optional library argument - "user" (default) for your personal library, or a group ID to read a group library synced locally. Use list_groups to find group IDs.

Tool

Description

list_groups

List group libraries available to the local Zotero install

search_items

Search the library by title/creator/year or full text

get_item

Get full data for an item, optionally with citation/bibliography

get_item_children

List an item's notes and attachments

list_top_level_items

List top-level items in the library

list_trashed_items

List items in the trash

list_publications

List items in "My Publications"

list_collections

List collections

get_collection

Get full data for a single collection

get_subcollections

List the direct subcollections of a collection

get_collection_items

List items in a collection

get_collection_tags

List tags used on items in a collection

list_tags

List tags

get_item_tags

List tags attached to a single item

get_bibliography

Generate a formatted bibliography for one or more items

get_attachment_file_path

Get the local file path of an attachment

get_item_types

List item types supported by Zotero

The two tools below have no equivalent in the Zotero Web API - they read the attachment file resolved by get_attachment_file_path and process it locally with PyMuPDF. Both accept remove_headers_footers: when true, lines that repeat near the top/bottom of most pages (running titles, page numbers, etc.) are detected and stripped from the returned/saved text. For convert_document this only applies to output_format="txt" - PDF output preserves the original pages as-is.

Tool

Description

read_document

Read the text content of a PDF or EPUB attachment

convert_document

Convert a PDF or EPUB attachment to TXT or PDF and save it to a location you specify

Claude Plugin

This repo also ships as a Claude Code plugin bundling four Agent Skills for Zotero-based research, on top of the same MCP tools listed above:

Skill

Covers

searching-zotero-library

Searching and browsing items, collections, tags, groups

reading-zotero-documents

Full-text PDF/EPUB reading, quoting, and comparison

generating-zotero-bibliographies

Formatted citations and reading lists

analyzing-zotero-research

Thematic clustering, gap analysis, trajectory tracing, reading-list prioritization

The plugin's .mcp.json runs the server the same way as the Quickstart above (uvx --from local-zotero-mcp zotero-mcp), so it always tracks the published PyPI package.

Install

Add this repo as a plugin marketplace, then install the plugin:

/plugin marketplace add virtualarchitectures/Local-Zotero-MCP
/plugin install local-zotero-mcp@local-zotero-mcp

Local development

To try it locally instead, clone the repo and run:

claude --plugin-dir /path/to/Local-Zotero-MCP

Then invoke a skill directly, e.g. /local-zotero-mcp:searching-zotero-library, or just ask Claude a research question about your library and let it pick the right skill.

See TESTING.md for a manual test checklist to run against a real Zotero library after changing a skill.

Local development

Clone the repo and install it locally:

uv sync

Run it directly from the checkout:

uv run zotero-mcp

Point Claude Desktop at your local checkout instead of GitHub with:

{
  "mcpServers": {
    "zotero": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/Local-Zotero-MCP", "zotero-mcp"]
    }
  }
}

Run the tests:

uv run pytest

Tests mock the Zotero HTTP responses, so a running Zotero instance isn't required. To smoke-test against your own Zotero library:

uv run mcp dev zotero_mcp/server.py

Acknowledgements

The skills in this repository have been adapted from urschrei/zotero_search_skill. This version has been adapted to remove the dependencies on Pyzotero and the Semantic Scholar integration, interfacing directly with a local Zotero instance via MCP instead.

Available Tools

10 tools
get_attachment_file_pathA

Get the local filesystem path of an attachment's file.

Args: item_key: The attachment item's Zotero key.

Inputs: item_key (required). Returns: result

get_bibliographyA

Generate a formatted bibliography for one or more items.

Args: item_keys: Zotero keys of the items to include. style: CSL style name (e.g. "apa", "chicago-note-bibliography"). locale: Locale for the bibliography (e.g. "en-US").

Inputs: item_keys (required), style, locale. Returns: result

get_collection_itemsA

List items in a collection.

Args: collection_key: The collection's Zotero key. top_level_only: If true, exclude child items (e.g. notes/attachments). limit: Maximum number of results (1-100).

Inputs: collection_key (required), limit, top_level_only. Returns: result

get_itemB

Get the full data for a single item.

Args: item_key: The item's Zotero key. include_bib: If true, also include a formatted citation and bibliography entry. style: CSL style to use for the citation/bibliography when include_bib is true.

Inputs: item_key (required), style, include_bib.

get_item_childrenB

List the notes and attachments attached to an item.

Inputs: item_key (required). Returns: result

list_collectionsA

List collections in the library.

Args: top_level_only: If true, only return top-level collections (no subcollections).

Inputs: top_level_only. Returns: result

list_saved_searchesA

List saved searches defined in the library.

Inputs: no named parameters. Returns: result

list_tagsA

List tags used in the library.

Args: filter: Optional substring to filter tag names by. limit: Maximum number of results (1-100).

Inputs: limit, filter. Returns: result

search_itemsA

Search the library by title/creator/year or full text.

Args: query: Search text. qmode: "titleCreatorYear" (default) or "everything" for a full-text search. item_type: Optional item type filter (e.g. "book", "journalArticle"). tag: Optional tag filter. limit: Maximum number of results (1-100).

Inputs: query (required), tag, limit, qmode, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: searching, retrieving single items, listing collections/tags/saved searches, generating bibliographies, and resolving attachment paths. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., get_bibliography, search_items, list_collections, execute_saved_search). The verbs are semantically appropriate and the naming is predictable.

    Tool Count5/5

    With 10 tools, the set is well-scoped for a local Zotero MCP. It covers the primary read and search operations without unnecessary bloat, and each tool serves a functional need.

    Completeness4/5

    The tool set thoroughly covers read access to a Zotero library: searching, retrieving items, navigating collections/tags/saved searches, generating bibliographies, and locating attachment files. The only notable gap is the lack of write operations (create/update/delete), but the server appears intentionally read-only, so this is a minor limitation.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers