ZotSeek | AI-Powered Semantic Search & MCP Server for Zotero

Find similar papers by meaning, not just keywords. 100% local, no data leaves your machine. Now with a built-in MCP server for AI agents.

Status: ✅ Stable release · Zotero 8 & 9 · Transformers.js running locally

New: 🤖 MCP server built in — Claude Code, Codex, and any MCP client can search your library and cite papers with links that open straight to the matched PDF page. Fully local, read-only, opt-in. Set it up in one line →

Features

• 🔒 100% Local - No data sent to cloud, works completely offline
• 🧠 True Semantic Search - Find papers by meaning, not just keywords
• 🤖 AI Agent Access (MCP) - Let Claude Code and other MCP clients search your library, fully local and opt-in (docs)
• 🔍 Find Similar Documents - Right-click any paper → discover related research
• 📖 Search from PDF Selection - Select text while reading → right-click → find documents about that concept
• 🔎 Natural Language Search - Search with queries like "machine learning in healthcare"
• 🔀 Multi-Query Search - Combine up to 4 queries with AND/OR logic to find topic intersections
• 🔗 Hybrid Search - Combines AI + keyword search for best results
• ⚡ Lightning Fast - Searches complete in <100ms
• 📑 Section-Aware - See which section matched (Abstract, Methods, Results)
• 📄 Matched-Passage Preview - Hover a result to read the exact passage that matched, with query terms highlighted
• 📍 Passage-Level Location - Jump to exact page & paragraph in Full Document mode
• ✅ Multi-Select in Results - Select multiple search results, right-click to add to collections
• 📁 Save Results as Collection - One click saves the full result set into a new Zotero collection so you can revisit the list later without re-running the search
• 🔄 Auto-Index - Automatically index new papers when you add them to your library
• 🗑️ Auto-Cleanup - Embeddings automatically removed when items are deleted or trashed
• 🚫 Tag-Based Exclusion - Tag items with zotseek-exclude to skip them during indexing
• 📊 Indexing Status Column - "ZotSeek" column in the item list shows whether each paper is fully indexed, partially indexed (chunk limit hit), out of date, excluded, or not indexed
• ⏸️ Pause & Cancel - Pause or cancel long-running indexing operations at any time
• 💾 Crash-Resilient - Checkpoint saving every 10 items, auto-resume on next startup if a bulk run was interrupted, worker recovery on sleep/wake, skips problematic chunks automatically
• 🔌 Plugin API - Other Zotero plugins can call ZotSeek's search programmatically
• ⚙️ Configurable - Customize via Zotero Settings → ZotSeek (also accessible from search dialog)
• 🌐 Localized - UI available in English and Chinese (zh-CN)

Privacy & Security

ZotSeek is designed with privacy as a core principle:

What this means:

• Your research never leaves your machine
• No cloud services, no API keys, no subscriptions
• No telemetry or usage tracking
• Uninstalling the plugin removes all ZotSeek data

More Screenshots

How It Works

The Big Picture

flowchart TD
    subgraph INDEX["1️⃣ INDEX"]
        A[📄 Paper] --> B[🤖 AI Model] --> C[768 numbers]
    end
    
    subgraph SEARCH["2️⃣ SEARCH"]
        D[🔍 Query] --> E[Query → 768 numbers]
        E --> F{Compare all papers}
        F --> G[📊 Ranked results]
    end
    
    C -.->|stored| F

How it works: Each paper becomes 768 numbers capturing its meaning. To search, we convert your query to numbers and find papers with similar numbers.

Step-by-Step Process

1️⃣ Indexing Your Library

When you use "Index Current Collection" or "Update Library Index":

For each paper:
  1. Extract title + abstract (Abstract mode)
     — OR —
     Extract PDF text page-by-page with exact page numbers (Full Document mode)
  2. Split into paragraphs, filter out References/Bibliography
  3. Send to local AI model (nomic-embed-text-v1.5)
  4. Model outputs 768 numbers per chunk (the "embedding")
  5. Save embeddings + location metadata to local database (zotseek.sqlite)

Time: ~3 seconds per chunk

2️⃣ Finding Similar Documents

When you right-click → "Find Similar Documents":

  1. Load the selected paper's embedding
  2. Compare against all indexed papers (cached in memory)
  3. Rank by semantic similarity
  4. Show top results

Time: ~70ms (with cache)

Hybrid Search

The plugin combines semantic search (AI embeddings) with Zotero's keyword search using Reciprocal Rank Fusion (RRF) for optimal results.

Search Modes

Why Hybrid Search?

Result Indicators

Section-Aware Results

The Source column shows which section of the paper matched your query:

Matched-Passage Preview

Hover any result row to see a tooltip with the exact passage that matched your query, along with its location (page & paragraph), section type, and match score. This lets you judge whether a result is relevant without opening the paper. In Keyword and Hybrid searches the query terms are highlighted inside the passage, and the preview is centered on the first match so the relevant text is always in view. (Pure semantic search has no literal terms to highlight, so the passage is shown without highlighting.)

Result Granularity (Full Document Mode)

When using Full Document indexing mode, you can toggle between two result views:

By Section - Aggregates all chunks per paper and shows the highest-scoring match. The Location column shows where that best match was found (page & paragraph), so you get one diverse result per paper without losing the exact location:

By Location - Returns every matching paragraph individually with its own score:

In By Location mode, clicking a result opens the PDF to the exact page where the match was found.

Multi-Query Search

Combine up to 4 search queries to find papers at the intersection of multiple topics:

1. Click the "+" button next to the search field to add more queries
2. Choose AND or OR to combine results
3. For AND mode, select a combination formula

Example: Search for papers about "machine learning" AND "healthcare" AND "ethics" to find AI ethics papers specifically in the medical domain.

Match column with multiple queries: Shows combined score plus individual per-query scores:

• 73% (77|73|68) = 73% combined, with 77% for Q1, 73% for Q2, 68% for Q3

For technical details, see docs/SEARCH_ARCHITECTURE.md.

Indexing Modes

Configure via Zotero → Settings → ZotSeek.

How Full Document Mode Works

For papers with PDFs, the chunker:

1. Extracts text page-by-page with exact page numbers
2. Splits each page into paragraphs
3. Prepends title to each chunk for context
4. Automatically filters out References/Bibliography sections

When searching, if any chunk matches your query, the paper ranks highly (MaxSim aggregation in "By Section" mode).

References Filtering

The chunker automatically detects and excludes bibliography sections:

• Detects headers: "References", "Bibliography", "Works Cited", "Literature Cited"
• Recognizes citation patterns: [1], Smith, J. (2021)., DOI links
• Stops indexing once references section is detected

This keeps your search results focused on the actual content of papers.

Chunk Size Trade-offs

The maxTokens setting controls how text is split for embedding. It's a ceiling, not a target — chunks are split at paragraph boundaries and may be smaller.

Default: 2000 tokens. Firefox 140+ handles larger chunks efficiently.

Recommendations:

• Large libraries with full-paper indexing: use defaults
• Finding specific methodologies: try 500-600
• Broad topic discovery: try 2000-3000

For detailed chunking documentation, see docs/SEARCH_ARCHITECTURE.md.

Indexing Status Column

ZotSeek adds a "ZotSeek" column to the Zotero item list so you can see at a glance how each paper has been indexed. The first time you install this version the column appears automatically; you can hide or reorder it from the column-header menu like any other Zotero column.

After indexing, a one-line summary in the progress window also warns when any paper hit the chunk limit, and the same warning is written to the debug log per affected paper.

The AI Model

nomic-embed-text-v1.5

Why This Model?

• ✅ Superior retrieval quality - Outperforms OpenAI text-embedding-3-small and jina-v2 on MTEB benchmarks
• ✅ 8K context window - Most papers fit in 1-3 chunks (vs 10-20 with 512-token models)
• ✅ Instruction-aware - Uses search_document: for indexing and search_query: for queries
• ✅ Matryoshka embeddings - 768 dims can be truncated to 256/128 with minimal quality loss
• ✅ Fully open - Open weights, open training data, reproducible
• ✅ Works in Zotero - Compatible with Transformers.js v3 via wasmPaths configuration

How Embeddings Work

The model converts text into 768 numbers that capture semantic meaning:

"Machine learning for medical diagnosis"  →  [0.023, -0.045, 0.012, ...]
"AI in healthcare applications"           →  [0.021, -0.048, 0.015, ...]  ← Similar!
"Organic chemistry synthesis"             →  [-0.089, 0.034, 0.067, ...]  ← Different!

Papers with similar meanings have similar numbers, even if they use different words.

Architecture

System Overview

flowchart LR
    subgraph Main["Main Thread"]
        A[Plugin] <--> B[(SQLite)]
        A <--> C[Search]
    end
    
    subgraph Worker["ChromeWorker"]
        D[Transformers.js]
        E[nomic-embed-v1.5]
    end
    
    A -->|text| Worker
    Worker -->|embeddings| A

Why ChromeWorker?

Transformers.js can't run directly in Zotero's main thread because:

• Missing browser globals (self, navigator, indexedDB)
• Cache API crashes Zotero
• Would block UI during model inference

Solution: Run in a separate ChromeWorker thread with special configuration.

Data Storage

Embeddings are stored in a separate SQLite database (zotseek.sqlite) attached to Zotero's connection:

• Location: <Zotero Data Directory>/zotseek.sqlite
• Size: ~15KB per paper (abstract mode), ~150KB per paper (full document mode)
• Benefits: O(1) indexed lookups, in-memory caching, atomic updates, clean uninstall

The SQLite backend uses the ATTACH DATABASE pattern (inspired by Better BibTeX):

• Separate file - Keeps Zotero's main database clean and unbloated
• Smart caching - Pre-normalized Float32Arrays cached in memory after first search
• Reliable queries - Uses columnQueryAsync() and valueQueryAsync() for robust data retrieval
• Clean uninstall - Database file automatically removed when plugin is uninstalled

Copying the database between machines

ZotSeek stores its embeddings in zotseek.sqlite inside your Zotero data directory. The file is local and is not synced by Zotero's built-in sync.

If you use Zotero on multiple machines and want to avoid re-indexing your library on each one, you can copy the file manually:

1. Quit Zotero on both machines.
2. Find your Zotero data directory (Preferences → Advanced → Files and Folders).
3. Copy zotseek.sqlite from one machine to the other.
4. Start Zotero on the destination machine.

The plugin identifies items by Zotero's stable item keys (the same identifiers visible in the Zotero web API), so the database works correctly regardless of which machine indexed the items.

Notes:

• Both Zotero libraries must be in sync — items not yet present on the destination will appear as "unresolved embeddings" in Preferences → Database Health until sync completes.
• The file can be large (hundreds of MB for libraries with full-document indexing). It is not designed to be cloud-synced continuously.
• Group libraries are supported via stable group IDs assigned by Zotero's server.

Cosine Similarity

The math behind "how similar are two papers":

$$\text{similarity} = \frac{A \cdot B}{|A| \times |B|}$$

Where:

• A · B = sum of (a[i] × b[i]) for all 768 dimensions
• ‖A‖ = sqrt(sum of a[i]²)
• ‖B‖ = sqrt(sum of b[i]²)

Result: 0.0 (completely different) to 1.0 (identical)

Interpretation:

• 0.9+ = Very similar (probably same topic)
• 0.7-0.9 = Related topics
• 0.5-0.7 = Loosely related
• <0.5 = Different topics

Use with AI Agents (MCP)

ZotSeek can let Claude Code and other MCP clients search your library semantically, so an agent can find relevant papers and cite them with links that open straight to the right page in Zotero. Each result carries zotero:// deep links: one opens the item, one opens its PDF at the exact page that matched your query.

What this enables — real workflows from a thesis-writing session:

• "Find me a citable definition of human-AI collaboration" → the agent searches the library, proposes three candidate papers with the matched passages, and links each one so it opens in Zotero at the relevant page.
• Mark claims in a draft with [citation needed] → the agent hunts your library for sources that actually support each claim and flags the ones nothing supports.
• "A reviewer says these statements are too strong — what evidence do I have?" → the agent cross-checks the argument against what you have actually collected, paper by paper.

It runs entirely on your machine and is opt-in (off by default). Enable it in Settings → ZotSeek → AI Agent Access, make sure Zotero's local HTTP server is allowed (Settings → Advanced), then connect Claude Code with:

claude mcp add --transport http --scope user zotseek http://localhost:23119/zotseek/mcp

The same searches are also available as plain REST endpoints for scripts. Everything is read-only — nothing can modify your library or index. See docs/MCP.md for the full setup, tool reference, REST API, and security notes.

Installation

For Users

Requirements: Zotero 8.0 or newer (Zotero 9.0 supported).

1. Download the latest zotseek-X.Y.Z.xpi from the Releases page.
2. In Zotero, open Tools → Plugins.
3. Click the gear icon (⚙️) in the top-right and choose Install Plugin From File…
4. Select the downloaded .xpi file.
5. Restart Zotero when prompted.

After installation, ZotSeek is ready to use — open Zotero → Settings → ZotSeek to configure it, then right-click a collection and choose "Update Library Index" to build your index.

Updating: ZotSeek checks for updates automatically. New releases are delivered through Zotero's built-in plugin update mechanism, so you'll be notified when a new version is available.

For Developers

# Clone the repository
git clone https://github.com/introfini/ZotSeek
cd zotseek

# Install dependencies (includes zotero-plugin-toolkit for stable progress windows)
npm install

# Build the plugin
npm run build

# Create extension proxy file (macOS)
echo "$(pwd)/build" > ~/Library/Application\ Support/Zotero/Profiles/*.default/extensions/zotseek@zotero.org

# Restart Zotero with debug console
open -a Zotero --args -purgecaches -ZoteroDebugText -jsconsole

Building a Distributable XPI

npm run release

The interactive release script bumps the version, syncs manifest.json and update.json, rebuilds, and packages zotseek-X.Y.Z.xpi at the project root.

Usage

Index Your Library

1. Right-click on a collection → "Index Current Collection"
2. Or use "Update Library Index" to index all items
3. A progress window will appear showing:
   • Current item being processed
   • Progress percentage
   • Estimated time remaining (ETA)
   • Option to cancel at any time
4. Indexing speed: ~3 seconds per chunk

Crash-Resilient Indexing:

• Progress is saved every 25 items (checkpoint saving)
• If Zotero crashes or you need to stop, simply re-run "Update Index"
• Already-indexed items are automatically skipped
• No need to start over from scratch

Progress Window Features:

• ✅ AI model loaded status
• ✅ Extraction progress (chunks from items)
• 📊 Current paper being processed
• 📈 Progress bar with percentage
• ⏱️ ETA countdown
• ⏸ Pause/resume button (pauses at batch boundaries, all progress saved)
• ✕ Cancel button (shows quiet notification, no error alert)

Find Similar Documents

1. Select any paper in your library
2. Right-click → "Find Similar Documents"
3. Results appear showing similarity percentages

Save Results as Collection

Every ZotSeek search result set can be saved into a Zotero collection so you can come back to the same list later without re-running the search:

• In the search dialog, click "Save Results as Collection" in the footer to export every result.
• Or right-click any subset of results and choose Add to Collection → New collection... to export just the selection.
• The same button appears in the Find Similar Documents dialog.

The modal pre-fills a sensible name (your query + today's date, e.g. ZotSeek: "machine learning" · 2026-04-21) that you can edit. A live status line shows N items → My Library so you know where the collection will land.

New collections are created at the target library's root. If you want them in a specific subfolder, drag them from Zotero's sidebar after the export — faster and more flexible than a dropdown.

When search results span multiple libraries (for example, your personal library and a group library), a Library dropdown appears so you can pick which library receives the new collection. Items in other libraries are reported as skipped in the confirmation status.

Search from PDF Selection

While reading a PDF, you can search for related documents based on selected text:

1. Open a PDF in Zotero's reader
2. Select a passage that describes a concept you want to explore
3. Right-click → "Find Related Documents"
4. ZotSeek opens with the selected text as the search query
5. Results show documents related to that concept (current document is excluded)

This is useful for:

• Exploring unfamiliar concepts while reading
• Finding additional sources on a specific topic
• Discovering related work mentioned in a paper

Auto-Index New Papers

ZotSeek can automatically index papers as you add them to your library:

1. Go to Zotero → Settings → ZotSeek
2. Enable "Auto-index new items"
3. Now when you add papers (via browser connector, drag & drop, etc.), they'll be indexed automatically

How it works:

• Detects when new items are added to your library
• Waits for PDF attachments to arrive (with automatic retry)
• Batches multiple items together with a configurable delay (default: 10 seconds)
• Each new item resets the countdown, preventing indexing during bulk imports
• Shows a brief progress indicator while indexing
• Respects your indexing mode setting (Abstract or Full Document)

Configuring the delay: Go to Zotero Settings > ZotSeek and adjust the Auto-index delay slider (1-300 seconds). Longer delays are useful when importing large batches via browser connector or RSS feeds.

Managing the Index

Automatic cleanup: When you delete or trash items in Zotero, their embeddings are automatically removed from the ZotSeek index. This prevents ghost search results and keeps the index clean — no action needed on your part.

Manual removal: To remove specific items from the index without deleting them:

1. Select one or more items in Zotero
2. Right-click → "Remove from ZotSeek Index"
3. A notification confirms how many items were removed

This is useful when you want to re-index specific items (e.g., after updating a PDF), or to exclude items from search results without deleting them from your library.

Excluding Items from Indexing

You can prevent specific items from being indexed by tagging them:

1. Select one or more items in Zotero
2. Add the tag zotseek-exclude (or your custom tag name)
3. These items will be skipped during all indexing operations

Customizing the tag name: Go to Zotero → Settings → ZotSeek → Advanced Settings and change the Exclude tag field. Leave it empty to disable tag-based exclusion.

Tip: Use Zotero's advanced search (Edit → Advanced Search) to find items by title, type, collection, etc., then bulk-tag them. This is more flexible than regex-based filtering since it leverages Zotero's native search capabilities.

ZotSeek Search Dialog

1. Click the ZotSeek button in the toolbar (🔍✨)
2. Or right-click → "Open ZotSeek..."
3. Enter a natural language query (e.g., "machine learning for medical diagnosis")
4. Optional: Click "+" to add more queries (up to 4) and combine with AND/OR
5. View results ranked by semantic similarity
6. Double-click any result to open it in Zotero
7. Click ⚙ Settings (bottom-left) to quickly access ZotSeek preferences

Working with Multiple Search Results

Select multiple items in the ZotSeek search results:

1. Select multiple items:
   • Shift+click to select a range of items
   • Cmd+click (Mac) or Ctrl+click (Windows/Linux) to toggle individual items
2. Right-click on the selection to open the context menu:
   • Show in Library - Selects all items in Zotero's main pane
   • Add to Collection - Add all selected items to any collection
3. Click "Open Selected" to select all items in the Zotero library (when multiple selected)

View Debug Output

Help → Debug Output Logging → View Output

Look for [ZotSeek] entries.

Configuration

Settings Panel

Access settings via Zotero → Settings → ZotSeek (or Zotero → Preferences on macOS).

The settings panel allows you to configure:

• Indexing Mode: Abstract only or Full Document
• Search Options: Maximum results, minimum similarity threshold
• Exclusion: Exclude books, exclude by tag
• Actions: Clear index, re-index library

Preferences Reference

Preferences are stored in Zotero's preferences system:

Search Settings:

Indexing Settings:

Hybrid Search Settings:

You can also access preferences via about:config (Help → Debug Output Logging → View Output, then navigate to about:config).

Performance

Tested on MacBook Pro M3:

Performance Optimizations

The plugin includes several performance optimizations:

1. Tuned Chunk Size - 2000 tokens (~3s/chunk) balances recall and speed while avoiding the O(n²) attention bottleneck
2. In-Memory Caching - Embeddings cached after first search
3. Pre-normalized Vectors - Float32Arrays normalized on load for fast dot product
4. Parallel Searches - Semantic and keyword searches run simultaneously
5. Reliable SQLite Methods - Uses columnQueryAsync() and valueQueryAsync()

GPU Acceleration (Experimental)

ZotSeek automatically detects and uses WebGPU for GPU-accelerated embeddings when available:

Current status (April 2026):

• Firefox 141 shipped WebGPU on Windows only (July 2025)
• macOS and Linux WebGPU support is still in progress at Mozilla
• Both Zotero 8 and Zotero 9 ship Firefox 140 ESR — one version before the first WebGPU build, so GPU acceleration is still gated on an upstream Firefox ESR bump

When will GPU work? Once Zotero upgrades to a Firefox ESR with WebGPU support for your platform, GPU acceleration will automatically activate — no plugin update needed.

Check if GPU is being used: Look for "Model loaded on GPU" or "Model loaded on CPU" in Zotero's debug console (Help → Debug Output Logging → View Output).

Note: If WebGPU is unavailable or fails, the plugin automatically falls back to CPU without interruption.

Limitations

• English-optimized search - The embedding model is trained primarily on English text (UI available in English and Chinese)
• Large plugin size - ~131MB due to bundled AI model
• CPU only (for now) - GPU acceleration ready but waiting for Zotero/Firefox WebGPU support
• Zotero 8 or newer required - As of v1.12.0, Zotero 7 is no longer supported. Users on Zotero 7 should upgrade to Zotero 8 or later, or stay on ZotSeek v1.11.x.

Comparison with OpenAI

Technical Details

See the docs/ folder for detailed documentation:

• API.md - Plugin API for integration with other Zotero plugins
• SEARCH_ARCHITECTURE.md - Hybrid search, RRF fusion, chunking strategy
• DEVELOPMENT.md - Development guide, ChromeWorker + Transformers.js implementation
• ROADMAP.md - Planned features and improvements
• MCP.md - Local MCP server and REST API for AI agents and scripts

Changelog

See CHANGELOG.md for version history.

License

MIT License - see LICENSE

Acknowledgments

• Transformers.js by Hugging Face
• sentence-transformers for the embedding model
• Zotero for the amazing reference manager
• windingwind's Zotero Plugin Docs for invaluable guidance

ZotSeek: AI-Powered Semantic Search for Zotero — Built by José Fernandes