API Documentation

Detailed documentation of all available Zotero MCP tools.

Search Tools Content Tools Notes & Annotations Management Tools Usage Examples

Search Tools

zotero_search_items

Search for items in your Zotero library, given a query string.

Parameters

Name Type Description Default
query string Search query string Required
qmode string Query mode, either "titleCreatorYear" or "everything" "titleCreatorYear"
item_type string Type of items to search for. Use "-attachment" to exclude attachments. "-attachment"
limit integer Maximum number of results to return 10

Returns

Markdown-formatted search results with item metadata.

Example

// Example of using zotero_search_items to find papers about machine learning
{
  "query": "machine learning",
  "qmode": "everything",
  "limit": 5
}

zotero_advanced_search

Perform an advanced search with multiple criteria.

Parameters

Name Type Description Default
conditions array List of search condition dictionaries, each containing: field, operation, value Required
join_mode string Whether all conditions must match ("all") or any condition can match ("any") "all"
sort_by string Field to sort by (dateAdded, dateModified, title, creator, etc.) null
sort_direction string Direction to sort ("asc" or "desc") "asc"
limit integer Maximum number of results to return 50

Returns

Markdown-formatted search results with item metadata.

Example

// Example of using zotero_advanced_search to find recent papers by a specific author
{
  "conditions": [
    {
      "field": "creator",
      "operation": "contains",
      "value": "Smith"
    },
    {
      "field": "date",
      "operation": "is",
      "value": "2023"
    }
  ],
  "join_mode": "all",
  "sort_by": "dateAdded",
  "sort_direction": "desc",
  "limit": 10
}

zotero_get_collections

List all collections in your Zotero library.

Parameters

Name Type Description Default
limit integer Maximum number of collections to return null (no limit)

Returns

Markdown-formatted list of collections with hierarchical structure.

zotero_get_collection_items

Get all items in a specific Zotero collection.

Parameters

Name Type Description Default
collection_key string The collection key/ID Required
limit integer Maximum number of items to return 50

Returns

Markdown-formatted list of items in the collection.

zotero_get_tags

Get all tags used in your Zotero library.

Parameters

Name Type Description Default
limit integer Maximum number of tags to return null (no limit)

Returns

Markdown-formatted list of tags organized alphabetically.

zotero_get_recent

Get recently added items to your Zotero library.

Parameters

Name Type Description Default
limit integer Number of items to return 10

Returns

Markdown-formatted list of recently added items.

Content Tools

zotero_get_item_metadata

Get detailed metadata for a specific Zotero item by its key.

Parameters

Name Type Description Default
item_key string Zotero item key/ID Required
include_abstract boolean Whether to include the abstract in the output true

Returns

Markdown-formatted item metadata.

zotero_get_item_fulltext

Get the full text content of a Zotero item by its key.

Parameters

Name Type Description Default
item_key string Zotero item key/ID Required

Returns

Markdown-formatted item metadata followed by the full text content.

Requires Zotero 7+ for local full-text access. The text is extracted from the first available PDF or HTML attachment.

zotero_get_item_children

Get all child items (attachments, notes) for a specific Zotero item.

Parameters

Name Type Description Default
item_key string Zotero item key/ID Required

Returns

Markdown-formatted list of child items, including attachments and notes.

Notes & Annotations Tools

zotero_get_annotations

Get all annotations for a specific item or across your entire Zotero library.

Parameters

Name Type Description Default
item_key string Optional Zotero item key/ID to filter annotations by parent item null
use_pdf_extraction boolean Whether to attempt direct PDF extraction as a fallback false
limit integer Maximum number of annotations to return null

Returns

Markdown-formatted list of annotations with context.

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

zotero_get_notes

Retrieve notes from your Zotero library, with options to filter by parent item.

Parameters

Name Type Description Default
item_key string Optional Zotero item key/ID to filter notes by parent item null
limit integer Maximum number of notes to return 20

Returns

Markdown-formatted list of notes.

zotero_search_notes

Search for notes across your Zotero library.

Parameters

Name Type Description Default
query string Search query string Required
limit integer Maximum number of results to return 20

Returns

Markdown-formatted search results with highlighted matches.

zotero_create_note

Create a new note for a Zotero item. Beta Feature

Parameters

Name Type Description Default
item_key string Zotero item key/ID to attach the note to Required
note_title string Title for the note Required
note_text string Content of the note (can include simple HTML formatting) Required
tags array List of tags to apply to the note null

Returns

Confirmation message with the new note key.

Management Tools

zotero_batch_update_tags

Batch update tags across multiple items matching a search query.

Parameters

Name Type Description Default
query string Search query to find items to update Required
add_tags array List of tags to add to matched items null
remove_tags array List of tags to remove from matched items null
limit integer Maximum number of items to process 50

Returns

Summary of the batch update operation.

Example

// Example of using zotero_batch_update_tags to tag all machine learning papers
{
  "query": "machine learning",
  "add_tags": ["ai", "research"],
  "remove_tags": ["to-read"],
  "limit": 100
}

Usage Examples

Finding Recent Papers

You can ask Claude to help you find the most recent papers in your library:

You: Find my most recently added papers about machine learning

Claude: I'll search your Zotero library for recently added papers about machine learning.

[Claude uses zotero_search_items with query "machine learning" and sorts by date added]

Claude: I found 5 recently added papers about machine learning in your Zotero library:

  1. "Transformers for Time Series: A Survey" (2023) by Chen et al.
  2. "A Survey of Large Language Models for Healthcare" (2023) by Zhang et al.
  3. ...

Would you like me to get the full text or metadata for any of these papers?

Summarizing a Paper

You can ask Claude to summarize a paper from your library:

You: Summarize the key findings from the paper "Transformers for Time Series" in my library

Claude: Let me find and summarize that paper for you.

[Claude uses zotero_search_items to find the paper, then zotero_get_item_fulltext to access its content]

Claude: Here's a summary of the key findings from "Transformers for Time Series: A Survey":

The paper identifies four main advantages of transformer architectures for time series analysis: (1) ability to model long-range dependencies, (2) parallelizable training, (3) flexibility in handling multivariate data, and (4) transfer learning capabilities. The authors review over 30 transformer-based approaches for time series tasks, categorizing them based on their architectures and showing that transformer models consistently outperform traditional methods on benchmark datasets for forecasting, classification, and anomaly detection tasks.

Organizing Your Library

You can ask Claude to help organize your Zotero library:

You: Tag all my papers about deep learning with the tags "neural-networks" and "ai"

Claude: I'll help you tag those papers.

[Claude uses zotero_batch_update_tags with query "deep learning" and add_tags ["neural-networks", "ai"]]

Claude: I've updated the tags for 15 papers about deep learning in your library. All of them now have the tags "neural-networks" and "ai". Would you like me to show you the list of updated papers?

Working with Annotations

You can ask Claude to work with your PDF annotations:

You: Extract all annotations from my recent paper on quantum computing

Claude: I'll help you extract those annotations.

[Claude first uses zotero_search_items to find the paper, then zotero_get_annotations to extract annotations]

Claude: I've found 12 annotations in your quantum computing paper. Here are the highlights:

  • 4 highlights on quantum circuit optimization
  • 2 text annotations discussing error correction
  • 3 notes on future research directions
  • 3 highlighted equations with your comments

Would you like me to summarize these annotations or organize them by topic?

Parameters

Name Type Description Default
item_key string Optional Zotero item key/ID to filter annotations by parent item null
use_pdf_extraction boolean Whether to attempt direct PDF extraction as a fallback false
limit integer Maximum number of annotations to return null

Returns

Markdown-formatted list of annotations with context.

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