API Documentation | Zotero MCP

Semantic Search Search Tools Content Tools Notes & Annotations Management Tools Usage Examples

Semantic Search Tools New

AI-powered vector search for finding conceptually related papers

`zotero_semantic_search`

Perform AI-powered semantic search across your Zotero library. Finds papers based on conceptual similarity rather than exact keyword matches.

Parameters

Name	Type	Description	Default
`query`	string	Semantic search query (can be natural language, concepts, or even an abstract)	Required
`limit`	integer	Maximum number of results to return	10

Returns

Markdown-formatted results with similarity scores and item metadata.

Example

{
  "query": "machine learning applications in medical imaging",
  "limit": 5
}

`zotero_update_search_database`

Manually trigger an update of the semantic search database.

Parameters

Name	Type	Description	Default
`extract_fulltext`	boolean	Whether to extract full-text content from PDFs	false
`force_rebuild`	boolean	Force complete database rebuild	false

`zotero_get_search_database_status`

Get the current status and statistics of the semantic search database.

Parameters

None

Returns

Database statistics including item count, last update time, and embedding model info.

Search Tools

Traditional keyword and criteria-based search tools

`zotero_search_items`

Search for items in your Zotero library by keywords.

Parameters

Name	Type	Description	Default
`query`	string	Search query string	Required
`qmode`	string	Query mode: "titleCreatorYear" or "everything"	"titleCreatorYear"
`item_type`	string	Item type filter. Use "-attachment" to exclude attachments.	"-attachment"
`limit`	integer	Maximum results to return	10
`tag`	array	List of tag conditions to filter by	null

Example

{
  "query": "machine learning",
  "qmode": "everything",
  "limit": 5
}

`zotero_search_by_tag` New

Search for items using tag filters with AND/OR logic and exclusions.

Parameters

Name	Type	Description	Default
`tag`	array	List of tag conditions. Use "\|\|" for OR, "-" for exclusion. Example: ["research \|\| important", "-draft"]	Required
`item_type`	string	Item type filter	"-attachment"
`limit`	integer	Maximum results to return	10

Example

{
  "tag": ["#ML || #AI", "-#draft"],
  "limit": 20
}

Tags are ANDed together. Each tag can contain OR conditions (||) or exclusions (-).

`zotero_advanced_search`

Perform advanced search with multiple criteria.

Parameters

Name	Type	Description	Default
`conditions`	array	List of condition objects: {field, operation, value}	Required
`join_mode`	string	"all" (AND) or "any" (OR)	"all"
`sort_by`	string	Field to sort by (dateAdded, dateModified, title, creator)	null
`sort_direction`	string	"asc" or "desc"	"asc"
`limit`	integer	Maximum results to return	50

Example

{
  "conditions": [
    {"field": "creator", "operation": "contains", "value": "Smith"},
    {"field": "date", "operation": "is", "value": "2023"}
  ],
  "join_mode": "all",
  "sort_by": "dateAdded",
  "sort_direction": "desc"
}

`zotero_get_collections`

List all collections in your Zotero library with hierarchical structure.

Parameters

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

`zotero_get_collection_items`

Get all items in a specific collection.

Parameters

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

`zotero_get_tags`

Get all tags used in your library, organized alphabetically.

Parameters

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

`zotero_get_recent`

Get recently added items to your library.

Parameters

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

Content Tools

Access item metadata, full text, and attachments

`zotero_get_item_metadata`

Get detailed metadata for a specific item. Supports BibTeX export format.

Parameters

Name	Type	Description	Default
`item_key`	string	Zotero item key/ID	Required
`include_abstract`	boolean	Whether to include the abstract	true
`format`	string	Output format: "markdown" or "bibtex"	"markdown"

Example: BibTeX Export

{
  "item_key": "ABC123XY",
  "format": "bibtex"
}

For best BibTeX results, install the Better BibTeX plugin.

`zotero_get_item_fulltext`

Get the full text content of an item from its PDF or HTML attachment.

Parameters

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

Requires Zotero 7+ for local full-text access.

`zotero_get_item_children`

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

Parameters

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

Notes & Annotations Tools

Work with PDF annotations and research notes

`zotero_get_annotations`

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

Parameters

Name	Type	Description	Default
`item_key`	string	Filter by parent item (optional)	null
`use_pdf_extraction`	boolean	Extract directly from PDF as fallback	false
`limit`	integer	Maximum annotations to return	null

For best results, install the Better BibTeX plugin.

`zotero_get_notes`

Retrieve notes from your library.

Parameters

Name	Type	Description	Default
`item_key`	string	Filter by parent item (optional)	null
`limit`	integer	Maximum notes to return	20

`zotero_search_notes`

Search for notes and annotations by content.

Parameters

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

`zotero_create_note` Beta

Create a new note for a Zotero item.

Parameters

Name	Type	Description	Default
`item_key`	string	Parent item key to attach note to	Required
`note_title`	string	Title for the note	Required
`note_text`	string	Note content (supports basic HTML)	Required
`tags`	array	Tags to apply to the note	null

Example

{
  "item_key": "ABC123XY",
  "note_title": "Summary Notes",
  "note_text": "Key findings from this paper...",
  "tags": ["summary", "important"]
}

Management Tools

Batch operations and library management

`zotero_batch_update_tags`

Batch add or remove tags across multiple items.

Parameters

Name	Type	Description	Default
`query`	string	Search query to find items	Required
`add_tags`	array	Tags to add	null
`remove_tags`	array	Tags to remove	null
`limit`	integer	Maximum items to process	50

Example

{
  "query": "machine learning",
  "add_tags": ["AI", "research"],
  "remove_tags": ["to-read"],
  "limit": 100
}

Usage Examples

Real-world examples of using Zotero MCP with your AI assistant

Semantic Search for Related Research

You: Find papers in my library related to transformer architectures in computer vision

Claude: I'll search your library for conceptually related papers using semantic search.

[Uses zotero_semantic_search with the query]

Claude: I found 5 papers related to transformers in vision:

"Vision Transformer: An Image is Worth 16x16 Words" (Score: 0.92)
"Swin Transformer: Hierarchical Vision Transformer" (Score: 0.87)
...

BibTeX Export for Paper Writing

You: Export the BibTeX citation for my attention mechanism paper

Claude: Let me find and export that paper.

[Uses zotero_search_items, then zotero_get_item_metadata with format="bibtex"]

Claude: Here's your BibTeX citation:

@article{vaswani2017attention,
  title={Attention is all you need},
  author={Vaswani, Ashish and Shazeer, Noam and ...},
  journal={Advances in neural information processing systems},
  year={2017}
}

Tag-Based Organization

You: Show me all papers tagged with #ML but not #reviewed

Claude: I'll search using tag filters.

[Uses zotero_search_by_tag with tag=["#ML", "-#reviewed"]]

Claude: Found 12 papers with #ML that haven't been reviewed yet:

"Deep Learning for Natural Language Processing" - Added 3 days ago
"Reinforcement Learning: An Introduction" - Added 1 week ago
...

Extracting and Summarizing Annotations

You: Extract my annotations from the quantum computing paper and create a summary note

Claude: I'll extract your annotations and create a summary.

[Uses zotero_search_items to find the paper]

[Uses zotero_get_annotations to extract highlights and notes]

[Uses zotero_create_note to save the summary]

Claude: I found 15 annotations in your paper. Key themes:

5 highlights on quantum circuit optimization
3 notes about error correction methods
7 highlights on experimental results

I've created a summary note attached to the paper with all your annotations organized by topic.

Semantic Search Tools New

zotero_semantic_search

Parameters

Returns

Example

zotero_update_search_database

Parameters

zotero_get_search_database_status

Parameters

Returns

Search Tools

zotero_search_items

Parameters

Example

zotero_search_by_tag New

Parameters

Example

zotero_advanced_search

Parameters

Example

zotero_get_collections

Parameters

zotero_get_collection_items

Parameters

zotero_get_tags

Parameters

zotero_get_recent

Parameters

Content Tools

zotero_get_item_metadata

Parameters

Example: BibTeX Export

zotero_get_item_fulltext

Parameters

zotero_get_item_children

Parameters

Notes & Annotations Tools

zotero_get_annotations

Parameters

zotero_get_notes

Parameters

zotero_search_notes

Parameters

zotero_create_note Beta

Parameters

Example

Management Tools

zotero_batch_update_tags

Parameters

Example

Usage Examples

Semantic Search for Related Research

BibTeX Export for Paper Writing

Tag-Based Organization

Extracting and Summarizing Annotations

`zotero_semantic_search`

`zotero_update_search_database`

`zotero_get_search_database_status`

`zotero_search_items`

`zotero_search_by_tag` New

`zotero_advanced_search`

`zotero_get_collections`

`zotero_get_collection_items`

`zotero_get_tags`

`zotero_get_recent`

`zotero_get_item_metadata`

`zotero_get_item_fulltext`

`zotero_get_item_children`

`zotero_get_annotations`

`zotero_get_notes`

`zotero_search_notes`

`zotero_create_note` Beta

`zotero_batch_update_tags`