### Zotero MCP Setup and Help

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Access help for setup options or configure only semantic search. Use setup-info to display installation path and configuration details.

```bash
zotero-mcp setup --help
```

```bash
zotero-mcp setup --semantic-config-only
```

```bash
zotero-mcp setup-info
```

--------------------------------

### Install Zotero MCP Server with uv

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Install the Zotero MCP Server using the uv package manager. Use the `[semantic]` extra for semantic search or `[all]` for all features. Run `zotero-mcp setup` to auto-configure for Claude Desktop.

```bash
# Base installation (search, metadata, annotations, write operations)
uv tool install zotero-mcp-server

# With semantic search
uv tool install "zotero-mcp-server[semantic]"

# With all features
uv tool install "zotero-mcp-server[all]"

# Auto-configure for Claude Desktop
zotero-mcp setup
```

--------------------------------

### Install Zotero MCP via uv

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Recommended installation method using the uv package manager.

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

--------------------------------

### Install Zotero MCP with Optional Extras

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Use pip to install zotero-mcp-server with specific extras like 'semantic' for semantic search or 'all' for all features. The base install is minimal.

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

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

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

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

--------------------------------

### Install Zotero MCP Server with pip

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Install the Zotero MCP Server using pip. Include `[semantic]` for semantic search or `[all]` for all features. Execute `zotero-mcp setup` for Claude Desktop auto-configuration.

```bash
pip install zotero-mcp-server
pip install "zotero-mcp-server[semantic]"  # With semantic search
pip install "zotero-mcp-server[all]"       # All features
zotero-mcp setup
```

--------------------------------

### Install Zotero MCP Server

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Install the Zotero MCP server using pip. This is the initial step for setting up the server.

```bash
pip install zotero-mcp-server
```

--------------------------------

### Install Zotero MCP via pip

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Standard installation method using pip.

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

--------------------------------

### Example Environment JSON for Chorus.sh

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

This is an example of the environment configuration JSON required for integrating zotero-mcp with Chorus.sh. It should be provided as a single line.

```json
{"ZOTERO_LOCAL": "true"}
```

--------------------------------

### Install Zotero MCP using uv tool

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Install zotero-mcp-server with all features or just semantic search using the uv tool. This is an alternative to pip.

```bash
uv tool install "zotero-mcp-server[all]"    # Full install with all features
```

```bash
uv tool install "zotero-mcp-server[semantic]" # Just semantic search
```

--------------------------------

### Install Zotero MCP via pipx

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Installation method using pipx for isolated environment management.

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

--------------------------------

### Start Zotero MCP Server for Tunneling

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Start the zotero-mcp server with SSE transport, listening on all interfaces and port 8000. Ensure Zotero environment variables are set beforehand.

```bash
# Make sure your Zotero environment variables are set first!
# e.g., export ZOTERO_LOCAL=true
zotero-mcp serve --transport sse --host 0.0.0.0 --port 8000
```

--------------------------------

### Start zotero-mcp Server with stdio Transport

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Manually start the zotero-mcp server using the stdio transport. This is useful for clients that communicate via standard input/output.

```bash
zotero-mcp serve --transport stdio
```

--------------------------------

### Usage Example of Zotero Create Annotation Tool

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Demonstrates how to call the 'zotero_create_annotation' tool with specific parameters for highlighting text in a PDF attachment.

```python
# Via MCP tool
zotero_create_annotation(
    attachment_key="NHZFE5A7",
    page=1,
    text="We challenge two tenets of lifecycle investing",
    comment="Key thesis of the paper",
    color="#ffd400"
)
```

--------------------------------

### Look Up Paper by Citation Key

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Use this command to find a paper in your Zotero library using its citation key. Ensure you replace the example key with one that exists in your library. This leverages the BetterBibTeX API if installed, otherwise falls back to searching the Extra field.

```text
Look up the paper with citation key "Smith2024" in my library.
(Replace "Smith2024" with an actual citation key from your library.)
```

--------------------------------

### Run Zotero MCP Server

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Start the Zotero-MCP server directly. You can specify the transport method using the --transport flag.

```bash
zotero-mcp serve
```

```bash
zotero-mcp serve --transport stdio|streamable-http|sse
```

--------------------------------

### Start zotero-mcp Server with SSE Transport

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Manually start the zotero-mcp server using the SSE (Server-Sent Events) transport. This is suitable for HTTP/SSE-based clients, specifying the host and port.

```bash
zotero-mcp serve --transport sse --host localhost --port 8000
```

--------------------------------

### Setup Zotero MCP with Web API

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Use this command to set up Zotero-MCP for remote access via the web API. Replace YOUR_API_KEY and YOUR_LIBRARY_ID with your actual Zotero credentials.

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

--------------------------------

### Update and Version Commands

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Manage Zotero MCP Server updates and view version information. `--check-only` verifies updates without installing. `setup-info` displays installation details.

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

# Update to latest version
zotero-mcp update

# Show version
zotero-mcp version

# Show installation info
zotero-mcp setup-info
```

--------------------------------

### Start ngrok Tunnel

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Start an ngrok tunnel to securely expose the local zotero-mcp server (running on port 8000) to a public URL. This is necessary for web-based clients like ChatGPT.

```bash
ngrok http 8000
```

--------------------------------

### Configure Semantic Search for Zotero MCP

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Set up semantic search during initial setup or separately. The default embedding model is free and runs locally.

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

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

--------------------------------

### Run Zotero MCP Server

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Start the Zotero MCP Server. The default `stdio` transport is for Claude Desktop. Use `streamable-http` for web clients on a specified host and port, or the deprecated `sse` transport.

```bash
# Default stdio transport (for Claude Desktop)
zotero-mcp serve

# HTTP transport for web clients
zotero-mcp serve --transport streamable-http --host localhost --port 8000

# SSE transport (deprecated)
zotero-mcp serve --transport sse --port 8000
```

--------------------------------

### Get all collections

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

List all collections in your library, including their hierarchy, using `get_collections`. A limit can be specified.

```python
# Get all collections
result = get_collections(limit=100)
# Returns hierarchical list:
# - **Research** (Key: KMMQDFQ4)
#   - **Machine Learning** (Key: XYZ12345)
```

--------------------------------

### Get all tags

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

List all tags present in your Zotero library using `get_tags`. A limit can be specified for the number of tags returned.

```python
result = get_tags(limit=500)
# Returns alphabetically grouped tags
```

--------------------------------

### Update Zotero MCP Installation

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Check for available updates or update to the latest version of zotero-mcp. This command preserves existing configurations.

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

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

--------------------------------

### Error Handling Example for Text Search Failure

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Illustrates the error message format when text search fails, including the searched text and a 'Did you mean' suggestion with a confidence score.

```text
Error: Could not find text on page 21

Text searched: "16.27% savings rate"

==================================================
DID YOU MEAN (score: 76%):

  "we find a couple must save 16.27% (i.e., 63% more) to achieve
  the same expected utility with the TDF..."

  (Found on page 21)
==================================================

TIP: Copy the exact text from the PDF instead of paraphrasing.
```

--------------------------------

### Get item children

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve attachments, notes, and other child items associated with a specific item using `get_item_children`.

```python
result = get_item_children(item_key="ABCD1234")
# Returns: Attachments (PDFs, etc.), Notes, Other child items
```

--------------------------------

### Get annotations

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve annotations from specific items or across the entire library using `get_annotations`. Can optionally fallback to direct PDF extraction.

```python
# Get annotations for a specific item
result = get_annotations(
    item_key="ABCD1234",
    use_pdf_extraction=True  # Fallback to direct PDF extraction
)
```

```python
# Get all annotations in library (can be large)
result = get_annotations(limit=100)
```

--------------------------------

### Get recently added items

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve recently added items using `get_recent`. Can fetch items library-wide or from a specific collection.

```python
# Recent items library-wide
result = get_recent(limit=10)
```

```python
# Recent items in a collection
result = get_recent(
    limit=20,
    collection_key="KMMQDFQ4"
)
```

--------------------------------

### Get item full text

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve the full text content of a paper using `get_item_fulltext`. This operation can be resource-intensive.

```python
# Retrieve full paper text
result = get_item_fulltext(item_key="ABCD1234")
# Returns: Metadata + "## Full Text" section with extracted content
```

--------------------------------

### Get items in a specific collection

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve items from a specific collection using `get_collection_items`. Supports different detail levels: 'summary', 'keys_only', or 'full'.

```python
# Summary view (default)
result = get_collection_items(
    collection_key="KMMQDFQ4",
    detail="summary",
    limit=50
)
```

```python
# Keys only (minimal)
result = get_collection_items(
    collection_key="KMMQDFQ4",
    detail="keys_only"
)
```

```python
# Full details with abstracts
result = get_collection_items(
    collection_key="KMMQDFQ4",
    detail="full",
    limit=20
)
```

--------------------------------

### Get item metadata

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve detailed metadata for a specific item using `get_item_metadata`. Supports different output formats like markdown or BibTeX, and can include abstracts.

```python
# Get metadata in markdown format
result = get_item_metadata(
    item_key="ABCD1234",
    include_abstract=True,
    format="markdown"
)
```

```python
# Export as BibTeX
result = get_item_metadata(
    item_key="ABCD1234",
    format="bibtex"
)
```

--------------------------------

### Zotero MCP Update Commands

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Update Zotero-MCP to the latest version, check for updates without installing, or force an update. These commands manage the tool's version.

```bash
zotero-mcp update
```

```bash
zotero-mcp update --check-only
```

```bash
zotero-mcp update --force
```

--------------------------------

### Get Semantic Search Database Status

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieves the current status and configuration of the semantic search database. This includes document count, embedding model used, last update timestamp, and auto-update settings.

```python
result = get_search_database_status()
# Returns: Document count, embedding model, last update, auto-update settings
```

--------------------------------

### Build Zotero MCP Semantic Search Database

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Initialize the semantic search database. Use --fulltext for comprehensive extraction, specify --db-path for custom locations, and --force-rebuild if needed.

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

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

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

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

```bash
# Check database status
zotero-mcp db-status
```

--------------------------------

### Configure Zotero MCP for Claude Desktop

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Set up Zotero MCP for use with Claude Desktop. Auto-configuration is recommended, but manual configuration by adding to `claude_desktop_config.json` is also supported.

```bash
# Auto-configure (recommended):
zotero-mcp setup
```

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

--------------------------------

### Verify Note Key with create_note

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Create a note and verify that the returned key accurately corresponds to the created note, fixing a previous issue where '0' was returned.

```shell
Create another note on the Nature paper. Check that the returned
note key actually corresponds to the note (search for it by key).
```

--------------------------------

### Configure Zotero Web API

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Set environment variables for Zotero API key, library ID, and library type to connect via the Zotero Web API. Obtain the API key from zotero.org/settings/keys.

```bash
export ZOTERO_API_KEY=your_api_key
```

```bash
export ZOTERO_LIBRARY_ID=your_library_id
```

```bash
export ZOTERO_LIBRARY_TYPE=user  # or 'group' for group libraries
```

--------------------------------

### Configure Claude Desktop with Zotero MCP

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Add Zotero MCP server configuration to Claude Desktop's JSON config file. Restart Claude Desktop after modifying the file.

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

--------------------------------

### Configure Zotero MCP Server in Cherry Studio

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Add this JSON configuration to Cherry Studio's MCP Servers settings to enable the Zotero integration. Ensure the local API is enabled in Zotero preferences.

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

--------------------------------

### Create Note with JSON String Tags

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Create a note using `create_note` and pass tags as a JSON string to test Pydantic validation and correct tag assignment.

```shell
Create a note on the Nature paper with:
- title: "Test Note"
- text: "This is a test note created by the MCP test plan."
- tags: Pass the tags as a JSON string: '["test-note", "regression-test"]'
```

--------------------------------

### Define Zotero Create Annotation Tool

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Defines the 'zotero_create_annotation' tool with parameters for attachment key, page number, text to highlight, and optional comment and color.

```python
@mcp.tool(name="zotero_create_annotation")
def create_annotation(
    attachment_key: str,   # PDF attachment key
    page: int,             # 1-indexed page number
    text: str,             # Text to highlight
    comment: str = None,   # Optional comment
    color: str = "#ffd400" # Highlight color
) -> str:
```

--------------------------------

### Run Zotero MCP PDF Utilities Tests

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Executes Python code to import and test Zotero MCP PDF utility functions. Tests run automatically upon import.

```bash
.venv/bin/python -c "
from zotero_mcp.pdf_utils import (
    normalize_text, normalize_for_matching,
    find_text_position, _extract_anchor
)
# Tests run automatically on import
print('All imports successful')
"
```

--------------------------------

### Configure Local Zotero API

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Set the ZOTERO_LOCAL environment variable to true to connect to a local Zotero 7+ API. Ensure the local API is enabled in Zotero preferences.

```bash
export ZOTERO_LOCAL=true
```

--------------------------------

### Run Unit Tests with Pytest

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Execute all unit tests for the project using pytest. Ensure Zotero is running and the local API is enabled for some tests.

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

--------------------------------

### Web API Configuration

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Configure Zotero MCP Server for Web API access. Provide your `ZOTERO_API_KEY`, `ZOTERO_LIBRARY_ID`, and `ZOTERO_LIBRARY_TYPE` in the environment variables.

```json
{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_API_KEY": "your-api-key",
        "ZOTERO_LIBRARY_ID": "your-library-id",
        "ZOTERO_LIBRARY_TYPE": "user"
      }
    }
  }
}
```

--------------------------------

### Create Zotero Highlight Annotation

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Creates a highlight annotation on a PDF or EPUB attachment in Zotero. Requires the attachment key, page number, and the text from the PDF. Optional parameters include a comment and highlight color.

```python
# Requires: pip install zotero-mcp-server[pdf]
result = create_annotation(
    attachment_key="PDFKEY12",
    page=5,  # 1-indexed page number
    text="This exact text from the PDF",
    comment="Important finding!",
    color="#ffd400"  # Yellow highlight
)
```

--------------------------------

### Configure zotero-mcp Connector for ChatGPT

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Use this configuration for the MCP Server URL when setting up zotero-mcp as a custom connector in ChatGPT. Ensure the trailing slash on \"/sse/\" and a valid UUIDv4 for the session ID.

```text
https://<YOUR_NGROK_URL>.ngrok-free.app/sse/?session_id=<YOUR_UUID>
```

--------------------------------

### Zotero MCP Version and General Commands

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Display the current version of Zotero-MCP. This command provides basic version information.

```bash
zotero-mcp version
```

--------------------------------

### Create a new note

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Create a new note attached to a specific item using `create_note`. Allows specifying title, text content, and tags.

```python
result = create_note(
    item_key="ABCD1234",
    note_title="Summary",
    note_text="Key findings from this paper:\n\n1. First point\n2. Second point",
    tags=["summary", "review"]
)
```

--------------------------------

### Merge Duplicates and Verify Trash

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Create two duplicate items, merge them using `confirm=True`, and verify that the trashed item appears in Zotero's Trash. Ensures the keeper item retains all tags.

```shell
Create two duplicates (add DOI 10.1038/s41586-020-2649-2 twice with
tags "merge-test-1" and "merge-test-2").
Find them, then merge with confirm=True.
Check Zotero's Trash (View > Show Trash).
```

--------------------------------

### List All Zotero Collections

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Command to list all collections and subcollections within your Zotero library. This is particularly useful for testing pagination fixes if you have more than 25 collections. Ensure the output matches the collections visible in Zotero's sidebar.

```text
List all my Zotero collections.
```

--------------------------------

### zotero_create_annotation

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Create a highlight annotation on a PDF or EPUB document.

```APIDOC
## zotero_create_annotation

### Description
Create a highlight annotation on a PDF or EPUB.

### Parameters
#### Request Body
- **attachment_key** (string) - Required - The key of the PDF/EPUB attachment.
- **page** (integer) - Required - 1-indexed page number.
- **text** (string) - Required - Exact text from the PDF.
- **comment** (string) - Optional - Annotation comment.
- **color** (string) - Optional - Hex color code for the highlight.

### Request Example
{
  "attachment_key": "PDFKEY12",
  "page": 5,
  "text": "This exact text from the PDF",
  "comment": "Important finding!",
  "color": "#ffd400"
}
```

--------------------------------

### Annotate Paper with Core Findings

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Use this command to find a specific paper and highlight sentences representing its core findings in the abstract, discussion, or conclusion. This requires the paper to be in your library with an attached PDF. Verify that the highlights are correctly applied in Zotero's reader.

```text
Take a look at the 2025 paper on digital mindfulness interventions
by Wang et al. and highlight in green any sentences in the abstract,
discussion, or conclusion that you feel represent the core findings.
```

--------------------------------

### Import Local PDF to Zotero

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Imports a local PDF file into Zotero, automatically extracting the DOI to fetch metadata. A fallback title can be provided if no DOI is found. Supports specifying collections and tags.

```python
result = add_from_file(
    file_path="/absolute/path/to/paper.pdf",
    title="Fallback Title",  # Used if no DOI found
    collections=["KMMQDFQ4"],
    tags=["imported"]
)
# Extracts DOI from PDF metadata/text, fetches rich metadata if found
```

--------------------------------

### Auto Mode Reports URL When Download Fails

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add a paywalled paper using `attach_mode="auto"`. The cascade should attempt to download a PDF, fail, and report the found URL without creating a linked attachment. The item should have no attachment.

```shell
Add a paywalled paper by DOI: 10.1016/j.cell.2015.11.015
Tag it with "_MCP-test-to-delete".
Use attach_mode="auto" (or don't specify, since auto is the default).
```

--------------------------------

### Add arXiv Paper with PDF Attachment

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add an arXiv paper by its URL and verify that the associated PDF is automatically attached.

```shell
Add this arXiv paper: https://arxiv.org/abs/2301.00774
Check if the arXiv PDF was automatically attached.
```

--------------------------------

### List accessible libraries

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

List all accessible libraries, including user, group, and RSS feeds (in local mode), using `list_libraries`.

```python
result = list_libraries()
# Shows: User Library, Group Libraries, RSS Feeds (local mode only)
```

--------------------------------

### Search Zotero Items by Keywords

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Use `search_items` for basic keyword searches in your Zotero library. Supports substring matching and filtering by tags or collection keys. `qmode` specifies the search field.

```python
# Basic search by author
result = search_items(
    query="Smith 2023",
    qmode="titleCreatorYear",
    limit=10
)

# Search with tag filter
result = search_items(
    query="machine learning",
    tag=["research", "-draft"],  # Has 'research' tag, NOT 'draft'
    limit=20
)

# Search within a collection
result = search_items(
    query="neural networks",
    collection_key="ABCD1234",
    limit=15
)
```

--------------------------------

### Handle Citation Key Not Found

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Test the system's response when a citation key does not exist in the library. The expected outcome is a clear 'not found' message, avoiding errors or crashes.

```text
Look up the paper with citation key "NonexistentKey9999".
```

--------------------------------

### Identify and List Test-Created Items for Deletion

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Search for all items tagged '_MCP-test-to-delete' and list their titles and keys. This is a final step to identify items created solely for testing purposes, preparing them for removal.

```text
Search for all items tagged "_MCP-test-to-delete" and list their
titles and keys.
```

--------------------------------

### Search notes and annotations

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Search through notes and annotations using `search_notes` with a query string. Supports limiting results and controlling raw HTML output.

```python
result = search_notes(
    query="reinforcement learning",
    limit=20,
    raw_html=False
)
```

--------------------------------

### Graceful Failure: Paywalled, No OA PDF

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add a paywalled paper by DOI and verify that the item is created with full metadata but no PDF is attached. The response should indicate 'No open-access PDF found' without errors.

```shell
Add this paper by DOI: 10.1016/j.tetlet.2019.151042
Check the response message about PDF attachment.
```

--------------------------------

### Verify Per-Phase Cleanup of Tags

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Check existing library items for any tags added during testing phases (e.g., 'mcp-test-verified', 'attention-paper', 'neuroscience') and ensure they have been removed. This verifies that end-of-phase cleanup procedures were effective.

```text
Check that any tags added to EXISTING library items during testing
(like "mcp-test-verified", "attention-paper", "neuroscience") have
been removed. These should have been cleaned up at the end of each
phase, but verify nothing was missed.
```

--------------------------------

### Zotero Connection Environment Variables

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Set environment variables for Zotero connection. `ZOTERO_LOCAL` enables the local API. For the Web API, provide `ZOTERO_API_KEY`, `ZOTERO_LIBRARY_ID`, and `ZOTERO_LIBRARY_TYPE`.

```bash
# Zotero Connection
ZOTERO_LOCAL=true                    # Use local Zotero API
ZOTERO_API_KEY=xxx                   # Web API key
ZOTERO_LIBRARY_ID=12345              # Library ID
ZOTERO_LIBRARY_TYPE=user             # user or group

# Semantic Search
ZOTERO_EMBEDDING_MODEL=default       # default, openai, or gemini
OPENAI_API_KEY=xxx                   # For OpenAI embeddings
GEMINI_API_KEY=xxx                   # For Gemini embeddings
ZOTERO_DB_PATH=/path/to/zotero.sqlite
```

--------------------------------

### Retrieve notes

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieve notes from your library using `get_notes`. Can fetch notes for a specific item or all notes, with options for truncation and raw HTML output.

```python
# Notes for a specific item
result = get_notes(
    item_key="ABCD1234",
    truncate=True
)
```

```python
# All notes with raw HTML
result = get_notes(
    limit=20,
    raw_html=True  # For editing/round-tripping
)
```

--------------------------------

### PDF via Unpaywall (Gold OA)

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add an open-access paper by DOI and verify that a PDF is attached, with Unpaywall reported as the source. This tests the first step in the PDF cascade for gold open-access articles.

```shell
Add this open-access paper by DOI: 10.1371/journal.pone.0185809
Check if a PDF was automatically attached and which source provided it.
```

--------------------------------

### Zotero Annotation Configuration Constants

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Defines constants for text search strategies, including thresholds for anchor-based and fuzzy matching, and the number of neighboring pages to search.

```python
# Configuration Constants (lines 28-47)
ANCHOR_MIN_TEXT_LENGTH = 100      # Use anchor matching for text > 100 chars
ANCHOR_TARGET_LENGTH = 40         # Length of start/end anchors
ANCHOR_MATCH_THRESHOLD = 0.75     # Fuzzy threshold for anchors
FUZZY_THRESHOLD_SHORT = 0.85      # For text < 50 chars
FUZZY_THRESHOLD_MEDIUM = 0.75     # For text 50-150 chars
FUZZY_THRESHOLD_LONG = 0.65       # For text > 150 chars
DEFAULT_NEIGHBOR_PAGES = 2        # Pages to search on either side

# Character Replacement Maps
DASH_REPLACEMENTS = {...}         # em-dash, en-dash → hyphen
QUOTE_REPLACEMENTS = {...}        # curly quotes → straight
LIGATURE_REPLACEMENTS = {...}     # fi, fl, ff → expanded
```

--------------------------------

### Manage Zotero MCP Semantic Search Database

Source: https://github.com/54yyyu/zotero-mcp/blob/main/README.md

Update the semantic search database with metadata or full-text extraction. Use --force-rebuild for a complete database rebuild and specify a custom database path if needed.

```bash
zotero-mcp update-db
```

```bash
zotero-mcp update-db --fulltext
```

```bash
zotero-mcp update-db --force-rebuild
```

```bash
zotero-mcp update-db --fulltext --force-rebuild
```

```bash
zotero-mcp update-db --fulltext --db-path "your_path_to/zotero.sqlite"
```

```bash
zotero-mcp db-status
```

--------------------------------

### Enrich Zotero Item with Scite Citations

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieves citation counts (Supporting, Contrasting, Mentioning) and retraction alerts for a Zotero item using its DOI or item key. No Scite account is required.

```python
# By DOI
result = enrich_item(doi="10.1038/nature12373")

# By Zotero item key
result = enrich_item(item_key="ABCD1234")

# Returns: Supporting/Contrasting/Mentioning counts, retraction alerts
```

--------------------------------

### Create New Zotero Collection

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Creates a new collection (folder) in Zotero. Can create top-level collections or subcollections by specifying the parent collection's name or key.

```python
# Top-level collection
result = create_collection(name="2024 Research")

# Subcollection
result = create_collection(
    name="Deep Learning",
    parent_collection="Machine Learning"  # Name or key
)
```

--------------------------------

### Research Topic Collection and Paper Addition

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

This prompt initiates a multi-step process: identifying seminal papers on a topic, locating them, creating a Zotero collection, and adding the papers to it. Verify that the correct papers are found, added with metadata and PDFs, and placed in the newly created collection.

```text
What are the three most seminal papers on Predictive Coding?
Can you please locate them for me and then create a predictive
coding collection in my Zotero library and add those three papers?
```

--------------------------------

### Manage Semantic Search Database

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Manage the semantic search database. `update-db` builds metadata, `--fulltext` extracts full text (requires local mode), and `--force-rebuild` ensures a complete refresh. Specify `--db-path` for custom Zotero database locations.

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

# Build with full-text extraction (requires local mode)
zotero-mcp update-db --fulltext

# Force complete rebuild
zotero-mcp update-db --force-rebuild

# Custom Zotero database path
zotero-mcp update-db --fulltext --db-path "/path/to/zotero.sqlite"

# Check database status
zotero-mcp db-status

# Inspect indexed documents
zotero-mcp db-inspect --limit 50 --filter "machine learning"
zotero-mcp db-inspect --stats
```

--------------------------------

### Add Paper by URL to Zotero

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Adds a paper to Zotero from a given URL, which can be a DOI, arXiv link, or a generic webpage. Tags can be specified for organization.

```python
# arXiv paper
result = add_by_url(
    url="https://arxiv.org/abs/2301.00001",
    tags=["machine-learning"]
)

# DOI URL
result = add_by_url(
    url="https://doi.org/10.1038/nature12373"
)

# Generic webpage
result = add_by_url(
    url="https://example.com/article",
    collections=["WebClips"]
)
```

--------------------------------

### Create Zotero Area Annotation

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Creates an area or image annotation on a PDF attachment in Zotero. Requires the attachment key, page number, and normalized coordinates (x, y, width, height). Optional parameters include a comment and color.

```python
result = create_area_annotation(
    attachment_key="PDFKEY12",
    page=3,
    x=0.1,      # Normalized coordinates (0-1)
    y=0.2,
    width=0.4,
    height=0.3,
    comment="Important figure",
    color="#ff6666"
)
```

--------------------------------

### Switch active library

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Change the active library context for subsequent operations using `switch_library`. Supports switching to group libraries or resetting to default.

```python
# Switch to a group library
result = switch_library(
    library_id="6069773",
    library_type="group"
)
```

```python
# Reset to default
result = switch_library(
    library_id="",
    library_type="default"
)
```

--------------------------------

### Append to Existing Zotero Note

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Appends new content to an existing note in Zotero. Requires the item key of the note and the text to append.

```python
result = update_note(
    item_key="NOTE1234",
    note_text="<p>Additional content</p>",
    append=True
)
```

--------------------------------

### Search items by citation key

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Use `search_by_citation_key` to quickly find items using their BetterBibTeX citation key.

```python
# Find by citation key
result = search_by_citation_key(citekey="Smith2024")
```

```python
result = search_by_citation_key(citekey="jones2023deep")
```

--------------------------------

### Zotero Annotation Coordinate Conversion Functions

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Handles the conversion of PDF coordinates from PyMuPDF's top-left origin to Zotero's bottom-left origin.

```python
def _convert_rects_to_zotero():
    # Transform PyMuPDF → Zotero coords
    pass
def _build_sort_index():
    # Create annotation sort key
    pass
def _build_search_result():
    # Assemble result dict
    pass
```

--------------------------------

### Search Zotero Collections by Name

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Searches for Zotero collections by name, returning matching collections along with their keys and parent information.

```python
result = search_collections(query="machine learning")
# Returns matching collections with keys and parent info
```

--------------------------------

### create_note

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Creates a new note attached to a specific item.

```APIDOC
## create_note

### Description
Create a new note attached to an item.

### Parameters
#### Request Body
- **item_key** (string) - Required - The parent item key.
- **note_title** (string) - Optional - Title of the note.
- **note_text** (string) - Required - Content of the note.
- **tags** (array) - Optional - Tags to associate with the note.
```

--------------------------------

### PDF via arXiv from CrossRef Metadata

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add a paper by DOI and verify PDF attachment, expecting the cascade to find an arXiv preprint via CrossRef metadata when the journal version is paywalled.

```shell
Add this paper by DOI: 10.1103/PhysRevD.110.L081901
Check if a PDF was automatically attached.
```

--------------------------------

### Zotero Annotation Search Strategy Functions

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Implements various text search strategies, including anchor-based matching, fuzzy matching, and sliding window comparison, to find text within PDF pages.

```python
def _anchor_based_search():
    # Match start/end, highlight between
    pass
def _fuzzy_search_page():
    # Normalized text comparison
    pass
def _sliding_window_match():
    # SequenceMatcher-based fuzzy search
    pass
def _search_single_page():
    # Orchestrates all strategies
    pass
```

--------------------------------

### Search Zotero with Scite Data Inline

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Searches Zotero items and enriches the results with Scite citation tallies and retraction alerts. Each result includes title, authors, and Scite data.

```python
result = enrich_search(
    query="CRISPR gene editing",
    limit=10
)
# Each result shows: Title, Authors, + Scite tallies + retraction alerts
```

--------------------------------

### Manage Items in Zotero Collections

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Adds or removes specified items (by their keys) from Zotero collections (by their keys).

```python
result = manage_collections(
    item_keys=["KEY1", "KEY2", "KEY3"],
    add_to=["COLL1234"],
    remove_from=["COLL5678"]
)
```

--------------------------------

### Add Paper by DOI to Zotero

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Adds a paper to Zotero using its DOI, automatically fetching metadata and attempting to attach the PDF. Supports specifying collections, tags, and attachment mode.

```python
result = add_by_doi(
    doi="10.1038/nature12373",
    collections=["KMMQDFQ4"],
    tags=["to-read", "neuroscience"],
    attach_mode="auto"  # auto, linked, or none
)
# Fetches metadata from CrossRef, attempts open-access PDF from Unpaywall/arXiv/PMC
```

--------------------------------

### Force Rebuild Zotero Database

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/getting-started.md

Use this command to force a rebuild of the Zotero database if you encounter database-related issues. This is generally a low-risk operation.

```bash
zotero-mcp update-db --force-rebuild
```

--------------------------------

### Batch Update Tags for Zotero Items

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Applies tag updates (additions and removals) to multiple Zotero items based on a search query or an existing tag. A limit can be set for the number of items affected.

```python
result = batch_update_tags(
    query="machine learning",
    add_tags=["ML", "AI"],
    remove_tags=["uncategorized"],
    limit=50
)

# Filter by existing tag
result = batch_update_tags(
    tag="to-review",
    add_tags=["reviewed"],
    remove_tags=["to-review"],
    limit=100
)
```

--------------------------------

### List All Zotero Tags

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Retrieve a list of all tags present in your Zotero library. Compare the count and names against Zotero's tag selector to ensure completeness and accuracy.

```text
List all tags in my library.
```

--------------------------------

### Add Item to Collection with zotero_manage_collections

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Use `zotero_manage_collections` to add an item to a specific collection. This tests the fix for 'list indices must be integers' errors.

```shell
Use zotero_manage_collections (NOT update_item) to add the Nature
paper from Phase 3 to "MCP Test Collection". Use the add_to parameter.
```

--------------------------------

### Update an existing note

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Update the content of an existing note using `update_note`. Supports replacing the entire content or appending to it.

```python
# Replace note content
result = update_note(
    item_key="NOTE1234",
    note_text="<p>Updated content here</p>",
    append=False
)
```

--------------------------------

### Add Item by DOI with PDF Attachment

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add an open-access paper by DOI and verify that a PDF is automatically attached. This tests the initial PDF attachment functionality.

```shell
Add this open-access paper by DOI: 10.1371/journal.pone.0001636
Check if a PDF was automatically attached.
```

--------------------------------

### Zotero Annotation Page Text Extraction Functions

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Functions for extracting text spans with bounding boxes from PDF pages and building an index for efficient text searching.

```python
def _extract_page_spans():
    # Get text spans with bounding boxes
    pass
def _build_normalized_text_index():
    # Create position-to-span mapping
    pass
def _get_spans_in_range():
    # Find spans overlapping a position range
    pass
```

--------------------------------

### Zotero Annotation Text Normalization Functions

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/ANNOTATION_FEATURE.md

Provides functions for normalizing text to handle special characters like hyphens, dashes, and quotes, and for aggressive normalization used in matching.

```python
def normalize_text():
    # Handle hyphens, dashes, quotes, ligatures
    pass
def normalize_for_matching():
    # Aggressive: remove ALL spaces, lowercase
    pass
```

--------------------------------

### zotero_add_by_doi

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Add a paper to Zotero using its DOI.

```APIDOC
## zotero_add_by_doi

### Description
Add a paper by DOI with automatic metadata and PDF attachment.

### Parameters
#### Request Body
- **doi** (string) - Required - The DOI of the paper.
- **collections** (array) - Optional - List of collection keys.
- **tags** (array) - Optional - List of tags.
- **attach_mode** (string) - Optional - Attachment mode: auto, linked, or none.

### Request Example
{
  "doi": "10.1038/nature12373",
  "collections": ["KMMQDFQ4"],
  "tags": ["to-read", "neuroscience"],
  "attach_mode": "auto"
}
```

--------------------------------

### Verify Annotation Parent Titles

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Check that all annotations in your library correctly display the title of their parent paper, not a generic attachment title like 'Full Text PDF'. This confirms the two-hop grandparent resolution is functioning.

```text
Show me all my annotations across my entire library.
```

--------------------------------

### get_item_metadata

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Retrieves detailed metadata for a specific Zotero item.

```APIDOC
## get_item_metadata

### Description
Get detailed metadata for a specific item.

### Parameters
#### Request Body
- **item_key** (string) - Required - The unique key of the item.
- **include_abstract** (boolean) - Optional - Whether to include the abstract.
- **format** (string) - Optional - Output format (e.g., 'markdown', 'bibtex').
```

--------------------------------

### Find Duplicate Items in Zotero

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Finds duplicate items within Zotero based on title, DOI, or both. An optional collection key can scope the search, and a limit can be set.

```python
result = find_duplicates(
    method="both",  # "title", "doi", or "both"
    collection_key="KMMQDFQ4",  # Optional scope
    limit=50
)
```

--------------------------------

### Verify Note Parent Titles

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Ensure that all notes in your Zotero library are associated with their correct parent paper title, rather than an attachment title. This verifies the proper resolution of note-to-paper relationships.

```text
Show me all my notes across my entire library.
```

--------------------------------

### Preserve Collections with zotero_update_item

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Use `zotero_update_item` with the `collections` parameter to add an item to a new collection while preserving its existing collections. This ensures collections are merged, not replaced.

```shell
First, check what collections the Nature paper is currently in.
Then use zotero_update_item with collections=["<MCP Test Collection key>"]
to add it to that collection.
Verify it's still in any collections it was in before.
```

--------------------------------

### Search items by tag

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Use `search_by_tag` to find items based on tags, supporting OR logic and exclusions. Can be scoped to a specific collection using `collection_key`.

```python
# Items with specific tags
result = search_by_tag(
    tag=["research OR important", "-draft"],  # (research OR important) AND NOT draft
    limit=20
)
```

```python
# Scoped to collection
result = search_by_tag(
    tag=["#Arm"],
    collection_key="KMMQDFQ4",
    limit=50
)
```

--------------------------------

### Extract PDF Table of Contents

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Extracts the table of contents (outline) from a PDF attached to a Zotero item. Returns a hierarchical outline with page numbers.

```python
result = get_pdf_outline(item_key="ABCD1234")
# Returns hierarchical outline with page numbers
```

--------------------------------

### Update Semantic Search Database

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Manually updates the semantic search database. Set force_rebuild to True to rebuild the database from scratch. The limit parameter can be used to process a specific number of items, or None to process all.

```python
result = update_search_database(
    force_rebuild=False,
    limit=None  # Process all items
)
```

--------------------------------

### Semantic Search Database Management

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

APIs for managing the semantic search database, including updating and checking status.

```APIDOC
## Semantic Search Database

### zotero_update_search_database

#### Description
Manually update the semantic search database.

#### Method
Not specified (function call example provided)

#### Endpoint
Not specified

#### Parameters
##### Query Parameters
- **force_rebuild** (boolean) - Optional - If true, forces a full rebuild of the database.
- **limit** (integer) - Optional - Limits the number of items to process. If None, all items are processed.

#### Request Example
```python
result = update_search_database(
    force_rebuild=False,
    limit=None  # Process all items
)
```

### zotero_get_search_database_status

#### Description
Check database status and configuration.

#### Method
Not specified (function call example provided)

#### Endpoint
Not specified

#### Parameters
None

#### Request Example
```python
result = get_search_database_status()
```

### Response
#### Success Response (200)
- **result** (string) - Returns: Document count, embedding model, last update, auto-update settings.

#### Response Example
(Response structure not specified in the provided text)
```

--------------------------------

### Linked URL Attachment Mode

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add a paper by DOI using `attach_mode="linked_url"` to save the URL without downloading the PDF. The attachment icon in Zotero will indicate a link, not a file.

```shell
Add this paper by DOI: 10.1038/nature12373
Use attach_mode="linked_url" so it saves the URL without downloading.
```

--------------------------------

### advanced_search

Source: https://context7.com/54yyyu/zotero-mcp/llms.txt

Performs complex searches across the Zotero library using multiple criteria.

```APIDOC
## advanced_search

### Description
Performs an advanced search across the library based on multiple conditions.

### Parameters
#### Request Body
- **conditions** (array) - Required - List of condition objects containing field, operation, and value.
- **join_mode** (string) - Optional - Logic mode: 'all' (AND) or 'any' (OR).
- **sort_by** (string) - Optional - Field to sort by.
- **sort_direction** (string) - Optional - 'asc' or 'desc'.
- **limit** (integer) - Optional - Maximum number of results.

### Request Example
{
  "conditions": [{"field": "creator", "operation": "contains", "value": "Smith"}],
  "join_mode": "all"
}
```

--------------------------------

### Prevent Fake PDF Attachment for Paywalled Papers

Source: https://github.com/54yyyu/zotero-mcp/blob/main/docs/integration-test-plan.md

Add a paywalled paper via DOI and check its attachments. The system should not create a misleading 'PDF (linked URL)' attachment. Instead, it should report that no open-access PDF was found.

```text
Add this paywalled paper by DOI: 10.1016/j.tetlet.2019.151042
Check what attachments it has.
```