Zotero MCP

Zotero Attach File

zotero_attach_file

Attach a local file or direct PDF URL to an existing Zotero item as a child attachment, so you can add full text or supporting files to a reference already in your library.

Instructions

Attach a file to an EXISTING Zotero item as an imported child attachment (uploads the file bytes). Use when the item is already in the library and you have its key — e.g. attaching a PDF you found for a reference. To create a NEW item from a file, use zotero_add_item(source=) instead. item_key: key of the existing REGULAR item. Passing an attachment/note key fails with a hint to use its parent. file_path: ABSOLUTE local path (.pdf, .epub, .djvu, .doc, .docx, .odt, .rtf). url: direct http(s) link, downloaded server-side — PDF-only; for other formats download locally and use file_path. Exactly one of file_path/url must be given. filename: optional stored-filename override; defaults to the file's basename or the URL's last path segment (falling back to <item_key>.pdf); a missing extension is appended automatically. Returns the created attachment's key. Idempotent: if the item already has an attachment with the same filename or identical content (MD5), nothing is re-uploaded. Requires a writable library (fails in local-only mode). Uploads count against the Zotero cloud storage quota unless WebDAV sync is configured. Run zotero_update_search_database afterwards to index the new file for semantic search. link_mode: 'import' (default) uploads the file bytes; 'linked' records the absolute path only (like Zotero's 'Add Link to File') — the file is NOT moved or copied and no cloud quota is used. 'linked' requires file_path (not url) and a writable library; filename then only sets the title. Example: zotero_attach_file(item_key='ABCD2345', file_path='/Users/me/smith-2020.pdf').

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "item_key": "<item_key>"
    },
    "name": "zotero_attach_file"
  }
}

Input Schema

Name	Required	Default
`url`	No
`filename`	No
`item_key`	Yes
`file_path`	No
`link_mode`	No	import

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 7, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations are supplied, so the description carries the full burden and does so: it discloses idempotency behavior (skips on matching filename or MD5), the writable-library requirement and local-only-mode failure, cloud quota consumption vs WebDAV, and that 'linked' mode moves nothing and uses no quota. These are exactly the side effects an agent needs before committing to a mutation.

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

Conciseness4/5

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

Purpose and the sibling alternative are front-loaded, and nearly every sentence adds a distinct fact. It is dense and long for a description, with parameter notes packed inline rather than separated, which slightly hurts scannability but not correctness.

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

Completeness5/5

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

For a five-parameter mutation tool with an output schema, the description covers invocation, side effects, failure modes, and follow-up indexing, so nothing an agent needs to call it correctly is missing. Return-value detail is rightly minimal since the output schema exists.

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

Parameters5/5

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

Schema description coverage is 0%, and the description compensates fully: item_key must be a regular item key, file_path must be absolute and lists accepted extensions, url is PDF-only and server-side fetched, exactly one of file_path/url is required, filename has documented defaulting and extension-appending rules, and link_mode's two values and file_path-only constraint are explained.

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?

Opens with a precise verb+resource ('Attach a file to an EXISTING Zotero item as an imported child attachment') and immediately contrasts with the sibling zotero_add_item for the new-item case. The distinction from zotero_add_item is stated explicitly, so an agent can route correctly without inspecting either schema.

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

Usage Guidelines5/5

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

Gives when-to-use ('item already in the library and you have its key'), the alternative for the other case (zotero_add_item with a file path), and an exclusion: passing an attachment/note key fails with a hint to use its parent. It also prescribes the follow-up step (zotero_update_search_database) and distinguishes link_mode='linked' from 'import'.

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

Deploy Server