Skip to main content
Glama
Zotero MCP
by 54yyyu

Zotero MCP: Chat with your Research Library—Local or Web—in Claude, ChatGPT, and more.

Zotero MCP seamlessly connects your Zotero research library with ChatGPT, Claude, and other AI assistants (e.g., Cherry Studio, Chorus, Cursor) via the Model Context Protocol. Review papers, get summaries, analyze citations, extract PDF annotations, and more!


✨ Features

  • Vector-based similarity search over your entire research library (requires [semantic] extra)

  • Multiple embedding models: Default (free, local), OpenAI, and Gemini

  • Intelligent results with similarity scores and contextual matching

  • Auto-updating database with configurable sync schedules

🔍 Search Your Library

  • Find papers, articles, and books by title, author, or content

  • Perform complex searches with multiple criteria

  • Browse collections, tags, and recent additions

  • Semantic search for conceptual and topic-based discovery

📚 Access Your Content

  • Retrieve detailed metadata for any item (markdown or BibTeX export)

  • Get full text content (when available)

  • Look up items by BetterBibTeX citation key

📝 Work with Annotations

  • Extract and search PDF annotations with page numbers

  • Access Zotero's native annotations

  • Create and update notes and annotations

  • Extract PDF table of contents / outlines (requires [pdf] extra)

✏️ Write Operations

  • Add papers by DOI with auto-fetched metadata and open-access PDF cascade (Unpaywall, arXiv, Semantic Scholar, PMC)

  • Add papers by URL (arXiv, DOI links, generic webpages) or from local files

  • Create and manage collections, update item metadata, batch-update tags

  • Find and merge duplicate items with dry-run preview

  • Hybrid mode: local reads + web API writes for local-mode users

📊 Scite Citation Intelligence (optional [scite] extra)

  • Citation tallies: See how many papers support, contrast, or mention each item — the MCP version of the Scite Zotero Plugin

  • Retraction alerts: Scan your library for retracted or corrected papers

  • No Scite account required — uses public API endpoints

🌐 Flexible Access Methods

  • Local mode for offline access (no API key needed)

  • Web API for cloud library access

  • Hybrid mode: read from local Zotero, write via web API

Related MCP server: zotero-mcp

🚀 Quick Install

New to the command line? Try the community-built Zotero MCP Setup — includes a macOS GUI installer (DMG), one-click install scripts for Mac/Windows, and a step-by-step guide. No Terminal experience needed.

Default Installation (core tools only)

The base install is lightweight — it includes search, metadata retrieval, annotations, and write operations. No ML/AI dependencies are pulled in.

uv tool install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pip

pip install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Installing via pipx

pipx install zotero-mcp-server
zotero-mcp setup  # Auto-configure (Claude Desktop supported)

Optional Extras

Heavy ML/PDF dependencies are separated into optional extras so the base install stays fast and small:

Extra

What it adds

Install command

semantic

Semantic search via ChromaDB, sentence-transformers, OpenAI/Gemini embeddings

pip install "zotero-mcp-server[semantic]"

pdf

PDF outline extraction (PyMuPDF) and EPUB annotation support

pip install "zotero-mcp-server[pdf]"

scite

Scite citation intelligence — tallies and retraction alerts (no account needed)

pip install "zotero-mcp-server[scite]"

all

Everything above

pip install "zotero-mcp-server[all]"

For example, with uv:

uv tool install "zotero-mcp-server[all]"    # Full install with all features
uv tool install "zotero-mcp-server[semantic]" # Just semantic search

If you only need basic library access (search, read, annotate, write), the default install with no extras is all you need.

Updating Your Installation

Keep zotero-mcp up to date with the smart update command:

# Check for updates
zotero-mcp update --check-only

# Update to latest version (preserves all configurations)
zotero-mcp update

Zotero MCP now includes powerful AI-powered semantic search capabilities that let you find research based on concepts and meaning, not just keywords.

During setup or separately, configure semantic search:

# Configure during initial setup (recommended)
zotero-mcp setup

# Or configure semantic search separately
zotero-mcp setup --semantic-config-only

Available Embedding Models:

  • Default (all-MiniLM-L6-v2): Free, runs locally, good for most use cases

  • OpenAI: Better quality, requires API key (text-embedding-3-small or text-embedding-3-large)

  • Gemini: Better quality, requires API key (gemini-embedding-001)

Update Frequency Options:

  • Manual: Update only when you run zotero-mcp update-db

  • Auto on startup: Update database every time the server starts

  • Daily: Update once per day automatically

  • Every N days: Set custom interval

After setup, initialize your search database:

# Build the semantic search database (fast, metadata-only)
zotero-mcp update-db

# Build with full-text extraction (slower, more comprehensive)
zotero-mcp update-db --fulltext

# Use your custom zotero.sqlite path
zotero-mcp update-db --fulltext --db-path "/Your_custom_path/zotero.sqlite"

# If you have embedding conflicts or changed models, force a rebuild
zotero-mcp update-db --force-rebuild

# Check database status
zotero-mcp db-status

Example Semantic Queries in your AI assistant:

  • "Find research similar to machine learning concepts in neuroscience"

  • "Papers that discuss climate change impacts on agriculture"

  • "Research related to quantum computing applications"

  • "Studies about social media influence on mental health"

  • "Find papers conceptually similar to this abstract: [paste abstract]"

The semantic search provides similarity scores and finds papers based on conceptual understanding, not just keyword matching.

🖥️ Setup & Usage

Full documentation is available at Zotero MCP docs.

Requirements

  • Python 3.10+

  • Zotero 7+ (for local API with full-text access)

  • An MCP-compatible client (e.g., Claude Desktop, ChatGPT Developer Mode, Cherry Studio, Chorus)

For ChatGPT setup: see the Getting Started guide.

For Claude Desktop (example MCP client)

Configuration

After installation, either:

  1. Auto-configure (recommended):

    zotero-mcp setup
  2. Manual configuration: Add to your claude_desktop_config.json:

    {
      "mcpServers": {
        "zotero": {
          "command": "zotero-mcp",
          "env": {
            "ZOTERO_LOCAL": "true"
          }
        }
      }
    }

Usage

  1. Start Zotero desktop (make sure local API is enabled in preferences)

  2. Launch Claude Desktop

  3. Access the Zotero-MCP tool through Claude Desktop's tools interface

Example prompts:

  • "Search my library for papers on machine learning"

  • "Find recent articles I've added about climate change"

  • "Summarize the key findings from my paper on quantum computing"

  • "Extract all PDF annotations from my paper on neural networks"

  • "Search my notes and annotations for mentions of 'reinforcement learning'"

  • "Show me papers tagged '#Arm' excluding those with '#Crypt' in my library"

  • "Search for papers on operating system with tag '#Arm'"

  • "Export the BibTeX citation for papers on machine learning"

  • "Find papers conceptually similar to deep learning in computer vision" (semantic search)

  • "Research that relates to the intersection of AI and healthcare" (semantic search)

  • "Papers that discuss topics similar to this abstract: [paste text]" (semantic search)

For Cherry Studio

Configuration

Go to Settings -> MCP Servers -> Edit MCP Configuration, and add the following:

{
  "mcpServers": {
    "zotero": {
      "name": "zotero",
      "type": "stdio",
      "isActive": true,
      "command": "zotero-mcp",
      "args": [],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

Then click "Save".

Cherry Studio also provides a visual configuration method for general settings and tools selection.

🔧 Advanced Configuration

Using Web API Instead of Local API

For accessing your Zotero library via the web API (useful for remote setups):

zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID

Environment Variables

Zotero Connection:

  • ZOTERO_LOCAL=true: Use the local Zotero API (default: false)

  • ZOTERO_API_KEY: Your Zotero API key (for web API)

  • ZOTERO_LIBRARY_ID: Your Zotero library ID (for web API)

  • ZOTERO_LIBRARY_TYPE: The type of library (user or group, default: user)

Semantic Search:

  • ZOTERO_EMBEDDING_MODEL: Embedding model to use (default, openai, gemini)

  • OPENAI_API_KEY: Your OpenAI API key (for OpenAI embeddings)

  • OPENAI_EMBEDDING_MODEL: OpenAI model name (text-embedding-3-small, text-embedding-3-large)

  • OPENAI_BASE_URL: Custom OpenAI endpoint URL (optional, for use with compatible APIs)

  • GEMINI_API_KEY: Your Gemini API key (for Gemini embeddings)

  • GEMINI_EMBEDDING_MODEL: Gemini model name (gemini-embedding-001)

  • GEMINI_BASE_URL: Custom Gemini endpoint URL (optional, for use with compatible APIs)

  • ZOTERO_DB_PATH: Custom zotero.sqlite path (optional)

Command-Line Options

# Run the server directly
zotero-mcp serve

# Specify transport method
zotero-mcp serve --transport stdio|streamable-http|sse

# Setup and configuration
zotero-mcp setup --help                    # Get help on setup options
zotero-mcp setup --semantic-config-only    # Configure only semantic search
zotero-mcp setup-info                      # Show installation path and config info for MCP clients

# Updates and maintenance
zotero-mcp update                          # Update to latest version
zotero-mcp update --check-only             # Check for updates without installing
zotero-mcp update --force                  # Force update even if up to date

# Semantic search database management
zotero-mcp update-db                       # Update semantic search database (fast, metadata-only)
zotero-mcp update-db --fulltext             # Update with full-text extraction (comprehensive but slower)
zotero-mcp update-db --force-rebuild       # Force complete database rebuild
zotero-mcp update-db --fulltext --force-rebuild  # Rebuild with full-text extraction
zotero-mcp update-db --fulltext --db-path "your_path_to/zotero.sqlite" # Customize your zotero database path
zotero-mcp db-status                       # Show database status and info

# General
zotero-mcp version                         # Show current version

📑 PDF Annotation Extraction

Zotero MCP includes advanced PDF annotation extraction capabilities:

  • Direct PDF Processing: Extract annotations directly from PDF files, even if they're not yet indexed by Zotero

  • Enhanced Search: Search through PDF annotations and comments

  • Image Annotation Support: Extract image annotations from PDFs

  • Seamless Integration: Works alongside Zotero's native annotation system

For optimal annotation extraction, it is highly recommended to install the Better BibTeX plugin for Zotero. The annotation-related functions have been primarily tested with this plugin and provide enhanced functionality when it's available.

The first time you use PDF annotation features, the necessary tools will be automatically downloaded.

📚 Available Tools

🧠 Semantic Search Tools

  • zotero_semantic_search: AI-powered similarity search with embedding models

  • zotero_update_search_database: Manually update the semantic search database

  • zotero_get_search_database_status: Check database status and configuration

🔍 Search Tools

  • zotero_search_items: Search your library by keywords

  • zotero_advanced_search: Perform complex searches with multiple criteria

  • zotero_get_collections: List collections

  • zotero_get_collection_items: Get items in a collection

  • zotero_get_tags: List all tags

  • zotero_get_recent: Get recently added items

  • zotero_search_by_tag: Search your library using custom tag filters

📚 Content Tools

  • zotero_get_item_metadata: Get detailed metadata (supports BibTeX export via format="bibtex")

  • zotero_get_item_fulltext: Get full text content

  • zotero_get_item_children: Get attachments and notes

📝 Annotation & Notes Tools

  • zotero_get_annotations: Get annotations (including direct PDF extraction)

  • zotero_get_notes: Retrieve notes from your Zotero library

  • zotero_search_notes: Search in notes and annotations (including PDF-extracted)

  • zotero_create_note: Create a new note for an item (beta feature)

📊 Scite Citation Intelligence Tools

  • scite_enrich_item: Get Scite citation tallies and retraction alerts for a paper

  • scite_enrich_search: Search your Zotero library with Scite-enriched results (tallies + alerts inline)

  • scite_check_retractions: Scan items for retractions and editorial notices

📦 Item & Collection Management Tools

  • zotero_add_by_doi: Add a paper by DOI with automatic metadata and open-access PDF attachment

  • zotero_add_by_url: Add a paper by URL (arXiv, DOI URLs, and general webpages)

  • zotero_add_from_file: Import a local PDF or EPUB file with automatic DOI extraction

  • zotero_create_collection: Create a new collection (folder/project) in your library

  • zotero_search_collections: Search for collections by name to find their keys

  • zotero_manage_collections: Add or remove items from collections

  • zotero_update_item: Update metadata for an existing item (title, tags, abstract, date, etc.)

  • zotero_find_duplicates: Find duplicate items by title and/or DOI

  • zotero_merge_duplicates: Merge duplicate items with dry-run preview; consolidates all child items

  • zotero_get_pdf_outline: Extract the table of contents / outline from a PDF attachment

  • zotero_search_by_citation_key: Look up items by BetterBibTeX citation key (with Extra field fallback)

🧪 Testing

Unit Tests

uv run pytest tests/     # 294 tests, ~2 seconds

Integration Test Plan

A 45-point live integration test plan is included at docs/integration-test-plan.md. It's designed to be given to Claude in Claude Desktop, which will execute each test against your real Zotero library. Tests cover all tools, PDF attachment cascade, attach_mode, BetterBibTeX lookups, and multi-step showcase prompts. See the file for full instructions.

🔍 Troubleshooting

General Issues

  • No results found: Ensure Zotero is running and the local API is enabled. You need to toggle on Allow other applications on this computer to communicate with Zotero in Zotero preferences.

  • Can't connect to library: Check your API key and library ID if using web API

  • Full text not available: Make sure you're using Zotero 7+ for local full-text access

  • Local library limitations: Some functionality (tagging, library modifications) may not work with local JS API. Consider using web library setup for full functionality. (See the docs for more info.)

  • Installation/search option switching issues: Database problems from changing install methods or search options can often be resolved with zotero-mcp update-db --force-rebuild

Semantic Search Issues

  • "Missing required environment variables" when running update-db: Run zotero-mcp setup to configure your environment, or the CLI will automatically load settings from your MCP client config (e.g., Claude Desktop)

  • ChromaDB / stale embedding model errors: If you changed embedding models and see 404 errors (e.g., text-embedding-004 is not found), run zotero-mcp update-db --force-rebuild to recreate the collection with your current model. If that doesn't work, delete ~/.config/zotero-mcp/chroma_db/ and rebuild.

  • Database update takes long: By default, update-db is fast (metadata-only). For comprehensive indexing with full-text, use --fulltext flag. Use --limit parameter for testing: zotero-mcp update-db --limit 100

  • Semantic search returns no results: Ensure the database is initialized with zotero-mcp update-db and check status with zotero-mcp db-status

  • Limited search quality: For better semantic search results, use zotero-mcp update-db --fulltext to index full-text content (requires local Zotero setup)

  • OpenAI/Gemini API errors: Verify your API keys are correctly set and have sufficient credits/quota

Update Issues

  • Update command fails: Check your internet connection and try zotero-mcp update --force

  • Configuration lost after update: The update process preserves configs automatically, but check ~/.config/zotero-mcp/ for backup files

☕ Support

If you find Zotero MCP useful, consider buying me a coffee!

📄 License

MIT

Available Tools

35 tools
zotero_add_itemZotero Add ItemA

Add items from a DOI, URL, ISBN, PMID, BibTeX, CSL JSON or a local file; use it for every 'add this to Zotero' request. source: the identifier, URL, citation text or ABSOLUTE file path. DOI/URL/ISBN/PMID also take a comma- or newline-separated batch; BibTeX and CSL JSON may be inline (many entries) or a .bib/.json path. source_type: 'auto' (default) detects it. Prefer a DOI: a URL other than doi.org or arxiv.org becomes a bare webpage item, and ISBN metadata is noisy (verify it). For a file, its DOI is looked up, else metadata is guessed, then the file is attached; title overrides a missed title. collections: keys, names or 'Parent/Child' paths, checked before anything is created (create_missing_collections=True makes missing ones). if_exists: 'file' (default) reuses an item with the same DOI/arXiv ID/ISBN/URL, adding missing collections and tags; 'duplicate' always creates; 'skip' leaves a match alone. attach_mode: 'auto' (default) attaches an open-access PDF, 'linked_url' links it, 'none' skips, 'required' fails without one.

Inputs: source (required), tags, title, if_exists, +4 more.

zotero_attach_fileZotero Attach FileA

Attach a file to an EXISTING regular item (not an attachment or note). To create a new item from a file, use zotero_add_item(source=). Give exactly one of file_path (absolute; any regular file, no symlinks or .lnk) or url (a direct PDF link, downloaded by the server). filename: overrides the stored name. link_mode: 'import' (default) uploads a copy, which counts against Zotero storage unless WebDAV is set up; 'linked' links the file where it is (file_path only, nothing copied). Skips the upload when the item already has the same file. Returns the attachment key.

Inputs: item_key (required), url, filename, file_path, +1 more.

zotero_authorize_local_writesZotero Authorize Local WritesA

Ask the user to allow writes to the local Zotero library (Zotero 10+). BLOCKS until they answer a dialog in the Zotero app, so tell them to switch to Zotero first. 'Always Allow' saves a reusable key; 'Allow' covers one write. Call it when a write fails and zotero_write_capabilities says local writes are supported but no key is held. app_name: shown in the dialog. timeout: seconds to wait (5-55, default 45). Zotero allows about 5 prompts a minute: do not retry in a loop.

Inputs: timeout, app_name.

zotero_batch_updateZotero Batch UpdateA

Edit many items in one call: add or remove tags, and set or remove Key: value lines in Extra (BetterBibTeX keys, tex.* fields). Select by item_keys, or by query and/or tag (ANDed; a list of tags ORs); item_keys wins. Needs a selector and an action. add_tags/remove_tags leave other tags alone. set_keys upserts Extra lines by case-insensitive key; remove_keys deletes them. limit: items selected by query/tag (default 50, up to 1000); the report says if more matched. Example: (tag='to-read', add_tags=['reviewed'], remove_tags=['to-read']).

Inputs: tag, limit, query, add_tags, +4 more.

zotero_create_annotationZotero Create AnnotationA

Annotate a PDF (EPUB: highlights and underlines only). One mode per call: text= highlights that exact text (underline=True underlines it), matched against the text layer (scanned PDFs will not match); rect=[x, y, width, height] draws an area box over a figure or table; note=[x, y] places a sticky note at that point, its text in comment. rect and note are PDF only, normalized 0-1 from the page's top-left: take boxes from zotero_get_page_layout instead of guessing. attachment_key: the attachment, NOT the parent item (zotero_get_item_children lists it). page: 1-indexed (EPUB: chapter). comment, color (hex, default '#ffd400') and tags are optional. Needs PyMuPDF (the [pdf] extra). Example: (attachment_key='NHZFE5A7', page=7, rect=[0.15, 0.22, 0.6, 0.35], comment='Figure 3').

Inputs: page (required), attachment_key (required), note, rect, +5 more.

zotero_delete_annotationZotero Delete AnnotationA

Permanently delete a Zotero annotation. This cannot be undone. Annotations are deleted outright, as Zotero's own PDF reader does: a trashed annotation stays visible in the reader with no way to remove it there.

Inputs: annotation_key (required).

zotero_delete_itemZotero Delete ItemA

Move an item to the Trash (recoverable in Zotero). Any item type, but for notes use zotero_manage_note(action='delete'), or pass allow_note=True.

Inputs: item_key (required), allow_note.

zotero_export_bibliographyZotero Export BibliographyA

Format references with Zotero's CSL engine. item_keys: up to 100 item keys (takes precedence); or collection_key; neither exports the active library's top-level items. style: a CSL style short name (default 'apa'; e.g. 'modern-language-association', 'chicago-note-bibliography', 'ieee'). export_format: 'bib' (reference list, default), 'citation' (in-text citations) or 'bibtex'.

Inputs: style, item_keys, export_format, collection_key.

zotero_get_annotationsZotero Get AnnotationsA

Get PDF/EPUB annotations (highlights and their comments) for one item, or for the whole active library when item_key is omitted (can be thousands, so pass item_key when you know it). item_key: the parent item or an attachment. use_pdf_extraction=True parses the PDF itself when Zotero has no stored annotations (e.g. ones made in another reader). limit: default all. format: 'markdown' (default) or 'json' (normalized records).

Inputs: limit, format, item_key, use_pdf_extraction.

zotero_get_attachment_pathZotero Get Attachment PathA

Return the local filesystem path(s) of a Zotero item's attachments. Local mode only. Useful when you want to read a large PDF directly (e.g., a book) instead of going through zotero_get_item_fulltext, which is page-limited.

Inputs: item_key (required).

zotero_get_collection_itemsZotero Get Collection ItemsA

List the items in one collection. detail: 'keys_only', 'summary' (default, no abstracts) or 'full' (with abstracts). include_subcollections=True adds items in nested collections. Page with limit (default 50) and offset; the response names the next offset. To find papers on a topic, zotero_semantic_search is better.

Inputs: collection_key (required), limit, detail, offset, +1 more.

zotero_get_collectionsZotero Get CollectionsA

List every collection in the active library as an indented tree with keys. To find one collection by name, zotero_search_collections is cheaper. limit: default 100, up to 5000. include_trashed=True also shows collections in the Trash.

Inputs: limit, include_trashed.

zotero_get_item_childrenZotero Get Item ChildrenA

List the child attachments and notes of one or more items. Use it to get the attachment key that zotero_create_annotation and zotero_get_page_layout need. item_key: one key or an array of keys; pass all of them in one call (a bad key is reported, not fatal). One key shows attachments (type, filename) and notes in full; several show one line per child, grouped by parent.

Inputs: item_key (required).

zotero_get_item_fulltextZotero Get Item FulltextA

Return the extracted text of an item's PDF or EPUB: most of the paper, often 10K+ tokens. Use it only when the user wants the paper READ, never to search (zotero_semantic_search, zotero_search_items) or for metadata (zotero_get_item_metadata); avoid reading several papers unless asked. item_key: normally the parent item, whose best attachment is picked (PDF first unless attachment_priority says otherwise); an attachment's own key reads exactly that file. PDFs stop at fulltext_display_max_pages (default 10), and a TRUNCATED heading names the pages read: continue with zotero_read_pdf_pages. Scanned PDFs without OCR may return little text.

Inputs: item_key (required).

zotero_get_item_metadataZotero Get Item MetadataA

Metadata for ONE item by its 8-character key (not a DOI or title): title, creators, date, DOI, tags, abstract, URL, collections (as keys). format: 'markdown' (default), 'json' (the Zotero record) or 'bibtex'. Signed attachment URLs are omitted. include_abstract=False shortens markdown output. Trashed items are returned too, marked In Trash. To read the paper use zotero_get_item_fulltext; to find items, the search tools.

Inputs: item_key (required), format, include_abstract.

zotero_get_notesZotero Get NotesA

Read notes in the active library. Without query it LISTS notes: an item's child notes with item_key, else notes library-wide. With query it SEARCHES note and annotation text (case-insensitive substring, library-wide, so not with item_key). limit: default 20. truncate=False returns whole bodies (list mode). raw_html=True returns the note's HTML, for editing and passing back to zotero_manage_note(action='update').

Inputs: limit, query, item_key, raw_html, +1 more.

zotero_get_page_layoutZotero Get Page LayoutA

Detect figure, table and display-equation regions on one PDF page and return their boxes (x, y, width, height, normalized 0-1), each with its caption or equation number, a confidence and a ready-made zotero_create_annotation call. Use it before an area annotation instead of guessing coordinates. Boxes cover the graphic itself: labels inside a figure or unruled table headers can fall outside, and confidence reflects caption matching, not box completeness. attachment_key: the PDF attachment, NOT the parent item (zotero_get_item_children lists it). page: 1-indexed. PDFs only.

Inputs: page (required), attachment_key (required).

zotero_get_pdf_outlineZotero Get Pdf OutlineA

Return a PDF's table of contents with page numbers, usually under 200 tokens: find the pages you need, then read them with zotero_read_pdf_pages instead of the full text. item_key: the parent item or the PDF attachment. Says so when the PDF has no outline. PDFs only; needs PyMuPDF (the [pdf] extra).

Inputs: item_key (required).

zotero_get_recentZotero Get RecentA

List the most recently ADDED items, newest first, in the active library or one collection (collection_key). For 'what did I add lately', not topic search or a collection's full contents. Includes standalone notes and attachments. limit: default 10.

Inputs: limit, collection_key.

zotero_get_tagsZotero Get TagsA

List every tag in the active library, one per line. Use it to find tag names before filtering with zotero_search_items(tag=...) or editing with zotero_batch_update. limit: default all.

Inputs: limit.

zotero_list_librariesZotero List LibrariesA

List the libraries you can switch to: the personal library, group libraries (with group IDs) and, in local mode, RSS feeds, each with its item count. Use it to get an ID for zotero_switch_library. The active library is not marked.

Inputs: no named parameters.

zotero_manage_collectionZotero Manage CollectionA

Create, update or delete a collection. action='create': name, and optionally parent_collection for a subcollection. 'update': collection_key plus a new name, a new parent_collection, or to_top_level=True; the key, items and subcollections are kept, and a collection cannot move under itself or its own subcollection. 'delete': collection_key; permanent (Zotero does not trash collections) and takes its subcollections with it, but the items stay in the library. parent_collection: a key, name or 'Parent/Child' path. To file items into collections use zotero_set_item_collections.

Inputs: action (required), name, to_top_level, collection_key, +1 more.

zotero_manage_noteZotero Manage NoteA

Create, update or trash a note. item_key: the PARENT item for action='create'; the NOTE's own key for 'update' and 'delete' (zotero_get_notes finds it). note_text: Markdown with $math$ plus (or background-color), or note HTML (sanitized). note_title becomes a heading and tags are optional (create). update REPLACES the body unless append=True; to keep formatting, edit the HTML from zotero_get_notes(raw_html=True) and pass it back whole. delete moves the note to the Trash (recoverable). Notes only: other items go through zotero_delete_item.

Inputs: action (required), item_key (required), tags, append, +2 more.

zotero_read_pdf_pagesZotero Read Pdf PagesA

Read chosen pages of an item's PDF, e.g. after zotero_get_pdf_outline. item_key: the paper or its PDF attachment. Reads start_page through end_page (1-indexed; omit end_page for one page). format='text' (default) returns Markdown and flags pages whose equations, figures or tables the text garbles; format='image' returns PNG page images (up to 10) to read those exactly. rect=[x, y, width, height] (normalized 0-1, e.g. from zotero_get_page_layout) returns just that region of start_page, zoomed in.

Inputs: item_key (required), start_page (required), rect, format, +1 more.

zotero_search_by_citation_keyZotero Search By Citation KeyA

Find the one item with this BetterBibTeX citation key (exact, case-sensitive), e.g. 'smith2024'. Checks Zotero's citationKey field, then 'Citation Key:' lines in Extra. For partial keys or free text use zotero_search_items.

Inputs: citekey (required).

zotero_search_collectionsZotero Search CollectionsA

Find collections by name in the active library; returns their keys and parents. Case-insensitive substring on the collection's own name, and every word must match ('reading list' needs both). include_trashed=True also matches collections in the Trash.

Inputs: query (required), include_trashed.

zotero_search_itemsZotero Search ItemsA

Keyword search of item metadata: substring match on title, creators and year (qmode='everything' adds abstracts). Keep queries short, like 'Brewer 2011' or a surname: every extra word narrows the match. For topics or concepts use zotero_semantic_search. If nothing matches it retries simpler queries, then semantic search, and says so. tag: conditions that are ANDed; within one, ' OR ' alternates and a leading '-' excludes, e.g. ['methods OR methodology', '-draft']. Omit query to list items by tag alone (zotero_get_tags lists the names). item_type: '-attachment' (default) excludes attachments, or e.g. 'journalArticle'. limit: default 10. collection_key: search one collection (no retries); include_subcollections adds its subcollections. search_all_libraries=True searches every library and labels each result; needs a query, not with collection_key.

Inputs: tag, limit, qmode, query, +4 more.

zotero_set_item_collectionsZotero Set Item CollectionsA

Add items to, or remove them from, collections, leaving their other memberships alone. item_keys: an array of item keys. add_to / remove_from: arrays of collection keys, names or 'Parent/Child' paths, all checked before anything changes. To replace memberships wholesale use zotero_update_item; to create, rename or delete a collection, zotero_manage_collection.

Inputs: item_keys (required), add_to, remove_from.

zotero_set_item_parentZotero Set Item ParentB

Set or clear the parent of a Zotero item. Pass a parent item key to assign or change the parent, or null to make the item top-level. Zotero validates whether the requested parent-child relationship is allowed.

Inputs: item_key (required), parent_key (required).

zotero_switch_libraryZotero Switch LibraryA

Set the library that every later tool call reads and writes, for the rest of the session. library_id: an ID from zotero_list_libraries ('user' or '0' for the personal library). library_type: 'group' (default), 'user', 'feeds', or 'default' to go back to the configured library (library_id is then ignored). Fails if the library is not accessible.

Inputs: library_id (required), library_type.

zotero_synthesize_annotationsZotero Synthesize AnnotationsA

Gather highlights, comments and child notes across a scope into a per-paper digest for YOU to synthesize; no LLM is called. collection_key: only papers in that collection; omit for the whole active library. tag: a tag or list of tags to filter papers by. limit: annotations and notes scanned (default 200). format: 'markdown' (default, grouped by paper with a count summary) or 'json'. Use it before writing a thematic review.

Inputs: tag, limit, format, collection_key.

zotero_update_annotationZotero Update AnnotationA

Update an existing Zotero annotation. Editable fields: text (highlight text), comment, color (hex like '#ffd400'), and tags. Tags can be replaced wholesale via tags, or edited incrementally via add_tags/remove_tags (mutually exclusive with tags). Position/page/sortIndex are anchored to the PDF/EPUB geometry and are not editable.

Inputs: annotation_key (required), tags, text, color, +3 more.

zotero_update_itemZotero Update ItemA

Change metadata on one item; only what you pass changes. fields: {name: value} with snake_case names (title, date, doi, url, abstract, publication_title, short_title, book_title, citation_key, item_type, place, extra, volume, issue, pages, publisher, issn, isbn, edition, language, access_date) or raw Zotero field names. Unknown names fail and list the valid ones; names the item's type lacks are skipped and reported. citation_key sets the BetterBibTeX key; item_type converts the item, dropping fields the new type lacks. creators: a full replacement list of {creatorType, firstName, lastName}. tags REPLACES all tags; add_tags/remove_tags edit incrementally (preferred; not with tags). collections (keys) or collection_names REPLACE membership (collections=[] clears it); for incremental moves use zotero_set_item_collections. For notes use zotero_manage_note.

Inputs: item_key (required), tags, fields, add_tags, +4 more.

zotero_write_capabilitiesZotero Write CapabilitiesA

Report whether this server can write to Zotero (local API, web API, hybrid, or not at all) and what is missing. Instant; opens no dialog. Call it when a write tool reports no writable backend, before asking the user: if local writes are supported but no key is held, call zotero_authorize_local_writes; otherwise web API credentials are needed.

Inputs: no named parameters.

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 35 tools

    Disambiguation4/5

    The toolset is mostly well-separated, with detailed descriptions that route agents between search, retrieval, annotation, and write operations. However, several retrieval tools overlap in practice—zotero_search_items, zotero_advanced_search, zotero_search_by_citation_key, zotero_get_recent, and zotero_get_collection_items—and note/annotation retrieval versus synthesis can require careful reading to choose correctly.

    Naming Consistency4/5

    Names consistently use the zotero_ prefix and snake_case, and the vast majority follow an action_resource pattern such as zotero_get_annotations or zotero_manage_collection. A few names deviate from strict verb_noun form, notably zotero_advanced_search, zotero_batch_update, and zotero_write_capabilities, but the overall pattern remains predictable.

    Tool Count2/5

    At 35 tools, the surface is well beyond the recommended range and feels heavy even for a feature-rich Zotero integration. Many specialized PDF, annotation, library, and authorization tools are justified individually, but the set would benefit from consolidation or clearer grouping.

    Completeness4/5

    Coverage is broad: items, collections, notes, annotations, PDF access, bibliography export, batch updates, and library switching are all represented. The notable gap is that zotero_semantic_search is repeatedly recommended in other descriptions but is not exposed as a tool, creating a dead end for topic-based discovery; trash restore/empty operations are also absent.

    Maintenance

    ActivityActive
    ResponsivenessUsually handled

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects your Zotero research library with AI assistants (Claude, ChatGPT, etc.) via the Model Context Protocol, enabling paper review, summaries, annotations, and semantic search both locally and through the web API.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search a Zotero library, retrieve complete item metadata, and fetch full text from attached documents such as PDFs through the Model Context Protocol.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to search a Zotero library, retrieve complete item metadata, and fetch full text such as PDF contents through the Model Context Protocol.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Connects a Zotero research library to Claude, ChatGPT, and other AI assistants so users can search, read, summarize, cite, and annotate papers, add and organize items, and find research by meaning. Supports local Zotero access or the web API, plus optional semantic search, PDF page images, and citation tallies.
      38
      MIT