Zotero MCP

Overview Schema Source Related Servers Discussions Admin

Zotero Add Item

zotero_add_item

Add items to Zotero from a DOI, URL, ISBN, BibTeX, CSL JSON, or local file. Resolves metadata and files each item into specified collections.

Instructions

Add item(s) to Zotero from any source: DOI, URL, ISBN, BibTeX, CSL JSON, or a local file. Use for every 'add this to Zotero' request. source: the identifier, URL, citation text, or ABSOLUTE file path. DOI/URL/ISBN also take many at once (list or comma/newline-separated), each resolved independently. BibTeX/CSL JSON may be inline (many entries per call) or a path to .bib/.bibtex/.json/.csljson; documents are .pdf, .epub, .docx and similar. source_type: 'auto' (default) detects it, incl. comma/newline DOI lists; override for URL/ISBN batches. Routing: doi → CrossRef (best metadata — prefer a DOI when you have one); url → doi.org/arxiv.org get full metadata, anything else becomes a bare 'webpage' item that is often not citable, so resolve to a DOI first; isbn → Open Library then Google Books (noisy — verify after); bibtex/csl_json → one item per entry, citation key kept in Extra; file → extracts the PDF's DOI and enriches via CrossRef, else guesses from filename/text, then attaches the file. collections: keys, names, or '/'-paths ('_project/topic'), validated before anything is created — an unknown or ambiguous spec fails the call rather than leaving an unfiled item; create_missing_collections=True creates them instead. if_exists: 'duplicate' (default) always creates; 'file' is idempotent — reuses the item matching the DOI/ISBN/URL, adding missing collections/tags, never removing; 'skip' leaves a match untouched. attach_mode: 'auto' (default) attaches an OA PDF, 'linked_url' bookmarks it, 'none' skips, 'required' fails without one. title: file sources only, when extraction misses. Requires a writable library (fails in local-only mode). Run zotero_update_search_database afterwards for semantic search. Example: zotero_add_item(source='10.1145/3708319', collections=['9SU943GB'], if_exists='file').

Input Schema

TableJSON Schema

Name	Required	Default
`tags`	No
`title`	No
`source`	Yes
`if_exists`	No	duplicate
`attach_mode`	No	auto
`collections`	No
`source_type`	No	auto
`create_missing_collections`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 2, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses metadata-source quality, validation-before-create failure behavior, idempotence semantics, attachment resolution, local-only mode failure, and the follow-up search-database step.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but dense and every clause carries useful behavioral or routing information. It front-loads the core purpose, walks through each source type and parameter in order, and closes with a concrete example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 8-parameter tool with no annotations, the description is nearly complete: it covers source routing, edge cases, failure modes, prerequisites, and post-conditions. The only notable gap is the undocumented 'tags' parameter; output-return concerns are reasonably deferred to the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description compensates for most parameters in detail: source, source_type, collections, create_missing_collections, if_exists, attach_mode, and title. However, 'tags' is never described, so an agent must guess whether it expects a list, a single string, or what behavior it triggers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource: 'Add item(s) to Zotero from any source: DOI, URL, ISBN, BibTeX, CSL JSON, or a local file.' It also states its role directly with 'Use for every add this to Zotero request,' distinguishing it from update/delete/attachment sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance ('Use for every add this to Zotero request') and rich routing heuristics, such as preferring a DOI and resolving URLs to DOIs first. It does not explicitly name sibling alternatives or when-not cases, but the context is otherwise clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server