Zotero MCP by cookjohn

Zotero MCP - Model Context Protocol Integration for Zotero

Zotero MCP is an open-source project designed to seamlessly integrate powerful AI capabilities with the leading reference management tool, Zotero, through the Model Context Protocol (MCP). This project consists of two core components: a Zotero plugin and an MCP server, which work together to provide AI assistants (like Claude) with the ability to interact with your local Zotero library. This README is also available in: :cn: 简体中文 | :gb: English.

---

Fork us on Wechat

MP	Forum

📚 Project Overview

The Zotero MCP server is a tool server based on the Model Context Protocol that provides seamless integration with the Zotero reference management system for AI applications like Claude Desktop. Through this server, AI assistants can:

• 🔍 Smart Search: Multi-dimensional library search (title/creator/year/tags/fulltext/semantic) with boolean operators and relevance scoring
• 📖 Content Extraction: Extract PDF full-text, notes, abstracts, webpage snapshots with fine-grained mode control
• 📝 Annotation Analysis: Search and analyze PDF highlights and annotations by color, tags, and keywords
• 📂 Collection Browsing: Browse and search collection hierarchies, retrieve items within collections
• 🧠 Semantic Search: AI-powered concept matching via embedding vectors, discover related literature across languages
• ✏️ Write Operations: Create notes, manage tags, update metadata, create new items and attach PDFs
• 💾 Full-text Database: Access and search cached PDF full-text content

This enables AI assistants to help you with literature reviews, citation management, content analysis, annotation organization, knowledge base management, and more.

🚀 Project Structure

This project now features a unified architecture with an integrated MCP server:

• zotero-mcp-plugin/: A Zotero plugin with integrated MCP server that communicates directly with AI clients via Streamable HTTP protocol
• IMG/: Screenshots and documentation images
• README.md / README-zh.md: Documentation files

Unified Architecture:

AI Client ↔ Streamable HTTP ↔ Zotero Plugin (with integrated MCP server)

This eliminates the need for a separate MCP server process, providing a more streamlined and efficient integration.

---

🚀 Quick Start Guide

This guide is intended to help general users quickly configure and use Zotero MCP, enabling your AI assistant to work seamlessly with your Zotero library.

1. Installation (For General Users)

What is Zotero MCP?

Simply put, Zotero MCP is a bridge connecting your AI client (like Cherry Studio, Gemini CLI, Claude Desktop, etc.) and your local Zotero reference management software. It allows your AI assistant to directly search, query, and cite references from your Zotero library, greatly enhancing academic research and writing efficiency.

Two-Step Quick Start:

1. Install the Plugin:

   • Go to the project's Releases Page to download the latest zotero-mcp-plugin-x.x.x.xpi file.
   • In Zotero, install the .xpi file via Tools -> Add-ons.
   • Restart Zotero.

2. Configure the Plugin:

   • In Zotero's Preferences -> Zotero MCP Plugin tab, configure your connection settings:
     • Enable Server: Start the integrated MCP server
     • Port: Default is 23120 (you can change this if needed)
     • Generate Client Configuration: Click this button to get configuration for your AI client

---

2. Connect to AI Clients

Important: The Zotero plugin now includes an integrated MCP server that uses the Streamable HTTP protocol. No separate server installation is needed.

Streamable HTTP Connection

The plugin uses Streamable HTTP, which enables real-time bidirectional communication with AI clients:

1. Enable Server in the Zotero plugin preferences
2. Generate Client Configuration by clicking the button in plugin preferences
3. Copy the generated configuration to your AI client

Supported AI Clients

• Claude Desktop: Streamable HTTP MCP support
• Cherry Studio: Streamable HTTP support
• Cursor IDE: Streamable HTTP MCP support
• Custom implementations: Streamable HTTP protocol

For detailed client-specific configuration instructions, see the Chinese README.

---

👨‍💻 Developer Guide

Prerequisites

• Zotero 7.0 or higher
• Node.js 18.0 or higher
• npm or yarn
• Git

Step 1: Install and Configure the Zotero Plugin

1. Download the latest zotero-mcp-plugin.xpi from the Releases Page.
2. Install it in Zotero via Tools -> Add-ons.
3. Enable the server in Preferences -> Zotero MCP Plugin.

Step 2: Development Setup

1. Clone the repository:

   git clone https://github.com/cookjohn/zotero-mcp.git
   cd zotero-mcp
   

2. Set up the plugin development environment:

   cd zotero-mcp-plugin
   npm install
   npm run build
   

3. Load the plugin in Zotero:

   # For development with auto-reload
   npm run start
   
   # Or install the built .xpi file manually
   npm run build
   

Step 3: Connect AI Clients (Development)

The plugin includes an integrated MCP server that uses Streamable HTTP:

1. Enable the server in Zotero plugin preferences
2. Generate client configuration using the plugin's built-in generator
3. Configure your AI client with the generated Streamable HTTP configuration

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "zotero": {
      "transport": "streamable_http",
      "url": "http://127.0.0.1:23120/mcp"
    }
  }
}

---

🧩 Features

zotero-mcp-plugin Features

• Integrated MCP Server: Built-in MCP server using Streamable HTTP protocol, no separate process needed
• Advanced Search Engine: Full-text search with boolean operators, relevance scoring, filtering by title, creator, year, tags, item type, and more
• Unified Content Extraction: Extract content from PDFs, attachments, notes, abstracts, webpage snapshots with four modes (minimal/preview/standard/complete)
• Smart Annotation System: Search and retrieve PDF highlights, annotations, and notes by color, tags, and keywords with intelligent ranking
• Collection Management: Browse, search collection hierarchies, get collection details, subcollections, and item lists
• Semantic Search: AI-powered semantic search using embedding vectors
  • Supports OpenAI and Ollama embedding APIs (auto-detection)
  • Vector indexing with SQLite-vec storage
  • Index status column in main library view
  • Collection/item context menu for index management
• Write Operations: Create/modify notes, manage tags, update metadata fields, create new items and reparent standalone PDFs
• Full-text Database: Cached PDF full-text database with list, search, get, and stats operations
• Standalone Attachment Management: Search and manage standalone PDF items without parent metadata
• Client Configuration Generator: Automatically generates configuration for various AI clients
• Security: Local-only operation ensuring complete data privacy
• User-Friendly: Easy configuration through Zotero preferences interface

---

📸 Screenshots

Here are some screenshots demonstrating the functionality of Zotero MCP:

Feature	Screenshot
Feature Demonstration
Literature Search
Viewing Metadata
Full-text Reading 1
Full-text Reading 2
Searching Attachments (Gemini CLI)
Reading PDF (Gemini CLI)

---

🔧 API Reference (MCP Tools)

The integrated MCP server provides 32 tools in 6 categories:

1. Search & Query (7 tools)

search_library

Advanced library search with multi-dimensional filtering, boolean operators, relevance scoring, and intelligent mode control.

• q, title, titleOperator, yearRange, fulltext, fulltextMode, itemType, includeAttachments, mode (minimal/preview/standard/complete), relevanceScoring, sort, limit, offset

search_annotations

Search annotations by query, colors, or tags with intelligent ranking.

• q, itemKeys, types (note/highlight/annotation/ink/text/image), colors, tags, mode, limit, offset

search_fulltext

Full-text search across all document content with context snippets.

• q (required), itemKeys, mode, contextLength, caseSensitive

search_collections

Search collections by name. Params: q, limit.

get_item_details

Get complete metadata for a single item. Params: itemKey (required), mode.

get_item_abstract

Get item abstract/summary. Params: itemKey (required), format (json/text).

get_content

Unified content extraction: PDF full-text, notes, abstracts, webpage snapshots from items or specific attachments.

• itemKey, attachmentKey, mode, include (pdf/attachments/notes/abstract/webpage), contentControl, format (json/text)

2. Collection Management (4 tools)

get_collections

Get all collections. Params: mode, limit, offset.

get_collection_details

Get details of a specific collection. Params: collectionKey (required).

get_collection_items

Get items in a collection. Params: collectionKey (required), limit, offset.

get_subcollections

Get subcollections. Params: collectionKey (required), limit, offset, recursive.

3. Semantic Search (3 tools, can be disabled in preferences)

semantic_search

AI-powered semantic search using embedding vectors. Finds conceptually related content even without exact keyword matches.

• query (required), topK, minScore, language (zh/en/all)

find_similar

Find items semantically similar to a given item.

• itemKey (required), topK, minScore

semantic_status

Get semantic search service status and index statistics. No parameters required.

4. Full-text Database (1 tool)

fulltext_database

Access cached full-text content database (read-only).

• action (required: list/search/get/stats), query, itemKeys, limit

5. Write Operations (6 tools, can be disabled in preferences)

write_note

Create or modify Zotero notes. Supports Markdown auto-conversion to HTML.

• action (required: create/update/append), parentKey, noteKey, content (required), tags

write_tag

Add, remove, or replace tags on items.

• action (required: add/remove/set), itemKey (required), tags (required)

write_metadata

Update metadata fields on items (title, abstract, date, DOI, creators, etc.).

• itemKey (required), fields, creators

write_item

Create new items, reparent existing attachments, or import local files as attachments.

• action (required: create/reparent/import), itemType, fields, creators, tags, attachmentKeys, parentKey, filePath, parentItemKey, title, linkMode (import: imported_file copies into Zotero storage, linked_file links in place — personal library only), libraryID

add_by_identifier

Import items by identifier (DOI, arXiv, ISBN, PMID, ADS bibcode) using Zotero's native resolvers — the same pipeline as the desktop "magic wand", including translator metadata and automatic attachment fetching.

• identifiers (required), libraryID, collectionKey, saveAttachments, duplicates, titleDuplicates, dryRun, async, jobID

trash_item

Move one or more items to Zotero Trash. Items stay recoverable until the user empties Trash; permanent deletion is not supported (permanent is rejected).

• itemKeys (required, array of item keys; deduplicated), libraryID

6. Citation & Bibliography (3 tools)

export_bibliography

Export one or more Zotero items as BibLaTeX/BibTeX (or CSL-JSON/CSL-YAML) entries powered by the zotero-better-bibtex (BBT) plugin. Requires Better BibTeX to be installed and running in Zotero.

• itemKeys (required), format (biblatex/bibtex/csljson/cslyaml), libraryID

get_citation

Generate a formatted reference (bibliography entry) or in-text citation for one or more items using a CSL citation style. If no style is specified, uses the Zotero default Quick Copy style. Works without Better BibTeX.

• itemKeys (required), style, contentType (html/text), mode (bibliography/citation), libraryID

list_citation_styles

List CSL citation styles available in Zotero (for use with get_citation).

• filter

---

🔌 External Tool Registration API

Other Zotero plugins can register custom MCP tools that are exposed through this plugin's MCP server. This allows third-party plugins to extend the AI-accessible toolset without running their own HTTP server.

How It Works

1. Your plugin calls Zotero.ZoteroMCP.api.registerTool(...) to register a tool.
2. The tool appears in tools/list alongside built-in tools.
3. When an AI client calls the tool, the MCP server dispatches the call to your handler.
4. On disable/uninstall, call Zotero.ZoteroMCP.api.unregisterTool(...) or unregisterAllTools(pluginID).

API Methods

Method	Description
registerTool(def)	Register a custom MCP tool. Throws on invalid input or name collision.
unregisterTool(name)	Unregister a tool by name. Returns true if removed.
unregisterAllTools(pluginID)	Unregister all tools from a specific plugin. Returns count removed.
getRegisteredTools()	List registered tools (readonly, handler excluded).
isToolRegistered(name)	Check if a tool name is already registered.
onToolListChanged(cb)	Subscribe to tool list changes. Returns an unsubscribe function.

Tool Definition

{
  name: string;           // Unique, matches /^[a-z][a-z0-9_]*$/, must not collide with built-in tools
  description: string;    // Shown to AI clients
  inputSchema: object;    // JSON Schema for input parameters
  handler: (args: any) => Promise<any> | any;  // Called when AI invokes the tool
  pluginID?: string;      // Optional: your plugin ID (for bulk cleanup)
  enabled?: boolean;      // Optional: visibility toggle (default: true)
}

Example (from another plugin)

// Register a custom MCP tool from your Zotero plugin
const mcp = Zotero.ZoteroMCP;
if (mcp && mcp.api && mcp.api.registerTool) {
  mcp.api.registerTool({
    name: 'my_plugin_count_items',
    description: 'Count items in the Zotero library by type',
    inputSchema: {
      type: 'object',
      properties: {
        itemType: { type: 'string', description: 'Filter by item type (e.g. journalArticle)' }
      }
    },
    handler: async (args) => {
      const items = await Zotero.Items.getAll(Zotero.Libraries.userLibraryID);
      const filtered = args.itemType
        ? items.filter(i => i.itemType === args.itemType)
        : items;
      return { total: filtered.length, itemType: args.itemType || 'all' };
    },
    pluginID: 'my-plugin@example.com'
  });
}

Cleanup on Uninstall

// In your plugin's shutdown hook:
const mcp = Zotero.ZoteroMCP;
if (mcp && mcp.api && mcp.api.unregisterAllTools) {
  mcp.api.unregisterAllTools('my-plugin@example.com');
}

Notes

• Tool names must not collide with built-in tools (see list above). Use a prefix like my_plugin_*.
• The registry survives MCP server restarts (e.g. port changes). Tools registered before the server starts will appear once it does.
• Handler errors are caught and returned as MCP error responses — no need to wrap in try/catch.
• Results are JSON-serialised and wrapped in MCP text content automatically.
• External tools are not covered by this plugin's "Enable write operations" switch. If your tool modifies the library, gate it in your own plugin.
• Registrations live in this plugin's memory. They are dropped when Zotero MCP is disabled, updated or reloaded, so register again whenever Zotero.ZoteroMCP.api becomes available.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit pull requests, report issues, or suggest enhancements.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgements

• Zotero - An excellent open-source reference management tool.
• Model Context Protocol - The protocol for AI tool integration.
• Contact us