Zoterobridge

🚀 ZoteroBridge

A Model Context Protocol (MCP) server that connects to the Zotero SQLite database, enabling AI assistants like Claude, ChatGPT, and GitHub Copilot to interact with your Zotero library.

🚀 Quick Start

Prerequisites

• Node.js 18.0 or higher
• Zotero 7.0 or higher
• An AI client supporting MCP (e.g., Claude Desktop, Cursor, VS Code Copilot)

Installation

Method 1: Global installation via npm (Recommended)

npm install -g zotero-bridge

Method 2: Build from source

# Clone the repository
git clone https://github.com/Combjellyshen/ZoteroBridge.git
cd ZoteroBridge

# Install dependencies
npm install

# Build the project
npm run build

Configure AI Clients

Claude Desktop

Add the following to the Claude Desktop configuration file: Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge"],
      "env": {}
    }
  }
}

If built from source:

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "node",
      "args": ["path/to/ZoteroBridge/dist/index.js"],
      "env": {}
    }
  }
}

Cursor IDE

Create a .cursor/mcp.json in the project root directory:

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge"]
    }
  }
}

VS Code Copilot

1. Open VS Code settings (Ctrl+,).
2. Search for github.copilot.chat.mcpServers.
3. Click "Edit in settings.json".
4. Add the following configuration:

"github.copilot.chat.mcpServers": {
  "zotero-bridge": {
    "command": "npx",
    "args": ["-y", "zotero-bridge"]
  }
}

Custom Database Path

If your Zotero database is not in the default location:

{
  "mcpServers": {
    "zotero-bridge": {
      "command": "npx",
      "args": ["-y", "zotero-bridge", "--db", "D:/MyZotero/zotero.sqlite"]
    }
  }
}

✨ Features

• 🗂️ Folder Management - Create, rename, move, and delete Zotero folders (collections).
• 🏷️ Tag Management - Add, remove, and query tags for documents.
• 📖 Item Operations - Search for items, get details, and manage folder relationships.
• 📝 Content Management - Read/set abstracts and add notes.
• 📄 PDF Processing - Extract full text, generate summaries, perform full-text searches, and get annotations.
• 🔍 Identifier Search - Find documents by DOI, ISBN, PMID, arXiv, or URL.
• 🔗 Related Items - Find similar documents with manual associations, shared tags/authors.
• 🛠️ Library Maintenance - Find duplicates, validate attachments, clean up orphan records, and merge items.

📦 Installation Guide

The installation methods are described in the "Quick Start" section above.

💻 Usage Examples

Using with Claude/Copilot

# Search for documents
Search for items with "deep learning" in the title

# Get details
Get detailed information about the item with itemID 1234

# Manage folders
Create a new folder named "Machine Learning Papers"
Add item 1234 to folder 5678

# PDF operations
Extract the full text of the PDF with attachment ID 100
Search for "neural network" in this PDF

# Find by DOI
Find the document with DOI 10.1126/science.aaa2397

# Get annotations
Get all highlighted annotations of item 1234

# Library maintenance
Find duplicate items in my library
Check if the attachment of item 1234 is valid

📚 Documentation

Available Tools (13 tools)

manage_collection - Folder Management

Manage all operations related to Zotero folders (collections).

manage_tags - Tag Management

Manage all operations related to tags.

search_items - Search Items

Search for Zotero items by title.

get_item_details - Get Item Details

Get detailed information about an item by ID or Key.

manage_item_content - Content Management

Manage the abstracts and notes of items.

manage_pdf - PDF Operations

Perform various operations on PDF files.

find_by_identifier - Identifier Search

Find documents by various identifiers, with automatic detection supported.

get_annotations - Get Annotations

Get PDF annotations (highlights, notes, etc.), with filtering or searching by type and color supported.

search_fulltext - Full-Text Search

Search in the Zotero full-text index or get the full-text content of attachments.

find_related_items - Find Related Items

Find related documents in various ways.

get_database_info - Database Information

Get information about the Zotero database (path, storage location, statistics).

raw_query - Raw SQL Query

Execute a raw SQL query (only SELECT is supported, read-only).

library_maintenance - Library Maintenance 🆕

Tools for maintaining and cleaning up the Zotero library.

🔧 Technical Details

Project Structure

ZoteroBridge/
├── src/
│   ├── index.ts      # MCP server entry
│   ├── database.ts   # Zotero SQLite database operations
│   ├── pdf.ts        # PDF processing module
│   └── tools.ts      # MCP tool definitions (13 integrated tools)
├── dist/             # Compiled output
├── test/             # Test files
├── package.json
├── tsconfig.json
└── README.md

Development Guide

Development Mode

# Watch for file changes and compile automatically
npm run dev

Build

npm run build

Command-Line Arguments

# Show help
zotero-bridge --help

# Specify the database path
zotero-bridge --db /path/to/zotero.sqlite

# Read-only mode
zotero-bridge --readonly

📄 License

This project is licensed under the MIT License.

🙏 Acknowledgments

• Zotero - An open-source literature management tool
• Model Context Protocol - An AI tool integration protocol
• cookjohn/zotero-mcp - Project reference

📬 Contact Information

• Author: Combjellyshen
• GitHub: https://github.com/Combjellyshen/ZoteroBridge
• npm: https://www.npmjs.com/package/zotero-bridge

Welcome to submit issues or pull requests!

Changelog

v1.1.5 (2026-02-01)

🗑️ Recycle Bin Recognition Feature

• ✅ All query functions now correctly exclude items in the deletedItems table.
• ✅ The getItemDetails method now has isDeleted and dateDeleted fields.
• ✅ findItemByDOI/ISBN/Identifier automatically skips items in the recycle bin.
• ✅ A new isItemDeleted() method is added to check if an item is in the recycle bin.
• ✅ A new getDeletedItems() method is added to get the content of the recycle bin.
• ✅ A new getDeletedItemsCount() method is added to get the number of items in the recycle bin.
• ✅ Attachment queries also exclude deleted attachments.

v1.1.4 (2026-02-01)

🔧 Important Fix - Database Compatibility

• ✅ Fixed the inconsistent duplicate query issue - findItemByDOI/ISBN now always returns the most recently modified item.
• ✅ Fixed the itemTags.type field - this field is NOT NULL and a value must be provided.
• ✅ Dynamically obtain the itemTypeID of note/attachment, no longer hard-coded.
• ✅ All queries now exclude deleted items in the deletedItems table.

🚀 New Features

• ✨ Added transaction support (beginTransaction/commitTransaction/rollbackTransaction).
• ✨ mergeItems now uses transactions to ensure data consistency.
• ✨ mergeItems now has a new attachment transfer function.
• ✨ Duplicate queries now return _duplicateWarning warning information.

🛡️ Security Improvements

• Check the Zotero process status before all write operations.
• Automatically create a database backup.
• Protect batch operations with transactions.

v1.1.3 (2026-02-01)

🔧 Fixes

• ✅ Fixed the collection (folder) creation function - added the required clientDateModified field.
• ✅ Fixed the collection renaming function - correctly updated the clientDateModified timestamp.
• ✅ Fixed the collection moving function - ensured the correct establishment of parent-child relationships.
• ✅ All collection operations now fully comply with the Zotero official database specification.

Now you can:

• Create a new collection (top-level folder).
• Create a sub-collection (supports multi-level nesting).
• Rename a collection.
• Move a collection to another parent collection.
• Get the list of sub-collections.

v1.1.2 (2025-02-01)

• Updated all dependencies to the latest versions.
• Fixed the Zod 4.x compatibility issue.
• Fixed the pdf-parse 2.x ESM import issue.

v1.1.1 (2025-02-01)

• Integrated 42 tools into 13 action-based tools.
• Added the library_maintenance tool (duplicate detection, attachment validation, orphan cleanup, item merging).

v1.1.0

• Initial integrated version.

⚠️ Important Note

• Close Zotero: When using write functions, close the Zotero client to avoid database locking.
• Backup Data: Back up zotero.sqlite before making modifications.
• Read-Only Mode: Use the --readonly parameter for safer data reading.
• Attachment Validation: Use the validate_attachments function in library_maintenance to check if files exist.