List all collections (folders) in your Zotero library. Returns collection keys, names, and parent relationships. Use collection keys with get_collection_items or as parent_collection in create_collection. Trashed collections are excluded by default.

Get all items in a specific Zotero collection (only items directly in it, not those in its subcollections). Returns item keys, titles, authors, and dates. Use the collectionKey from get_collections. Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.

Get metadata for multiple Zotero items in a single call. Accepts an array of item keys and returns a map of key → metadata. Use this instead of one call per item. Returns all type-specific fields (e.g. bookTitle for bookSection, proceedingsTitle for conferencePaper, university for thesis). Set include_abstract to include abstracts (excluded by default to keep responses lightweight). Keys not found in the library are listed in not_found (present only when some are missing).

Search your Zotero library or list items sorted by a field.

When 'query' is provided, matches it against titles, creator names and years (not abstracts, tags or full text). When 'query' is omitted, lists items sorted by the chosen field (default: dateAdded, descending).

Examples:

• Search: { "query": "deep learning" }

• Recent items: { "sort": "dateAdded", "limit": 10 }

• Recent with search: { "query": "transformers", "sort": "dateAdded", "limit": 5 }

Use the returned item keys with get_items_details, get_item_fulltext, or inject_citations.

Create a new collection (folder) in your Zotero library. Optionally nest it under a parent collection. Returns the new collection key and name. Use the key as collection_key in add_items_by_doi or add_items to organize imported papers.

Add items to your Zotero library by resolving DOIs. Works with ANY item type that has a DOI — journal articles, books, datasets, preprints, conference papers, reports, etc. For each DOI, resolves metadata via content negotiation and creates the item in Zotero with the correct type automatically. Returns a list of successfully added items (with item_key and title) and any failures.

WHEN TO USE vs add_items:

• Use add_items_by_doi when the item HAS a DOI — it auto-resolves all metadata and attaches open-access PDFs (when the server has UNPAYWALL_EMAIL set).

• Use add_items when the item does NOT have a DOI, or when you need to override specific metadata fields (add_items_by_doi does not allow metadata overrides).

• Mixed batch: if some items have DOIs and others don't, make two separate calls — add_items_by_doi for the DOIs and add_items for the rest.

WORKFLOW TIPS:

• To collect metadata for all added items, call get_items_details with the returned item_keys (single batch call).

• To create a cited Word document, use the returned item_keys as placeholders in a .docx, then call inject_citations. See inject_citations description for the full workflow.

Replace placeholder tags in a .docx file with native Zotero field codes that Zotero for Word can recognize and manage. The tool fetches item metadata from Zotero automatically — you only need to provide the .docx file.

WORKFLOW — how to create a Word document with live Zotero citations:

1. Collect item keys: use add_items_by_doi or add_items (or search_library for existing items)

2. Generate .docx: create a Word document (e.g. with the "docx" npm package) with placeholders where citations should appear. Each MUST be in its own dedicated TextRun — do NOT mix it with surrounding text.

3. Call this tool with the .docx file path. It replaces every zcite tag with a Zotero field code and appends a bibliography.

4. Tell the user to open the file in Word with the Zotero plugin, click Zotero → Add/Edit Bibliography, then Zotero → Refresh.

CITATION STYLES — ask the user which style they want before generating:

• apa (default): author-year — (Smith, 2023)

• harvard / chicago: author-date — (Smith, 2023) / (Smith 2023)

• ieee / vancouver: numbered — [1], [2] WARNING: for numbered styles every MUST include a num="N" attribute with the sequential citation number. Without num, citations render as [?].

ZCITE TAG FORMAT: Supported attributes (any order):

• keys (required): item key or comma-separated keys — "ABC12345" or "ABC12345,DEF67890"

• num: citation number for IEEE/Vancouver — "1" or "1,2" (required for numbered styles)

• locator: page reference — "12-15" (shown as "pp. 12–15"; other labels explicit, e.g. "chap. 3")

• prefix: text before citation — "see"

• suffix: text after citation — ", emphasis added"

OUTPUT: A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end. A cited key that is not in the library, or that is not a Zotero key (8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ), is an error and no file is written.

WHERE THE FILE LIVES: this tool reads and writes files on the machine where this MCP server runs. If you create the .docx in a sandbox or cloud workspace that the server cannot see (for example code execution in Claude.ai or Claude Desktop, paths like /mnt/user-data/...), do not call this tool: use the zotero-mcp-integrations skill, which injects the citations inside the sandbox with metadata from get_items_details. If that skill is not installed, recommend it to the user: zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.

Get the text of a Zotero item's stored PDF from Zotero's full-text index. Works for PDFs indexed by Zotero desktop and synced, or imported with import_pdf_to_zotero / find_and_attach_pdfs; not for linked URLs or web pages. Use this to read the full content of papers instead of relying on abstracts.

Returns the Zotero library configured in the server environment: user_id, library_type, library_id and library_path ("users/" or "groups/"). Pass library_path to the zotero-mcp-integrations skill script (inject.js) to generate Zotero field code URIs. Not needed when using the inject_citations MCP tool, which reads the library internally.

Attach a linked URL to an existing Zotero item, or create a standalone linked-URL attachment. Use this to link external PDFs, web pages, or other resources to items already in your library. If parent_item is provided, the attachment is added as a child; otherwise it is standalone. A linked URL stores no file and no full text (get_item_fulltext cannot read it): to store a PDF in Zotero use import_pdf_to_zotero.

Add items to Zotero by providing metadata directly. Supports ALL 37 Zotero item types.

WHEN TO USE:

• For items that do not have a DOI (books, theses, reports, etc.)

• When you need full control over metadata (e.g., override a title, set a specific itemType, add custom fields) — even if a DOI exists, use add_items when the auto-resolved metadata would be incorrect or incomplete

• Mixed batch: if some items have DOIs and others don't, call add_items_by_doi for the DOIs and add_items for the rest (two separate calls)

• Prefer add_items_by_doi when DOIs are available AND you don't need to override metadata (it auto-resolves everything and attaches OA PDFs)

BATCH: Pass multiple items in the 'items' array (one tool call).

COMMON FIELDS (available for most types): title, date, abstractNote, url, DOI, publisher, place, pages, volume, language, extra

ITEM TYPE QUICK REFERENCE:

• journalArticle: publicationTitle, volume, issue, pages, DOI, ISSN

• book: publisher, ISBN, edition, numPages, series, seriesNumber

• bookSection: bookTitle, publisher, pages, ISBN, edition

• conferencePaper: proceedingsTitle, conferenceName, publisher, DOI

• thesis: thesisType ("PhD thesis"|"Master's thesis"), university

• report: reportType, reportNumber, institution

• webpage: websiteTitle, websiteType, accessDate

• preprint: repository, archiveID, genre ("Preprint")

• patent: patentNumber, assignee, issuingAuthority, filingDate

• computerProgram: versionNumber, company, system, programmingLanguage

CREATORS: Array of {firstName, lastName, creatorType} or {name, creatorType} for institutional. Default creatorType is "author". Some types use different primary types (e.g., "director" for film, "inventor" for patent, "artist" for artwork).

Invalid fields or creatorTypes for a given type are rejected with helpful error messages listing the valid options.

Download a PDF from a URL and upload it to Zotero storage as an imported_url attachment. Unlike linked URL attachments, imported files are stored in Zotero's storage and become fulltext-indexed (searchable via get_item_fulltext). Use this when you need the PDF content to be indexed by Zotero. The URL must lead straight to the PDF file (no login, paywall or HTML landing page); files up to 100 MB, counted against the user's Zotero file storage. For items with a DOI, find_and_attach_pdfs finds open-access PDFs by itself.

For each Zotero item, check Unpaywall for open access PDFs and attach them. Items must have a DOI; needs UNPAYWALL_EMAIL in the server settings. Uploads use the user's Zotero file storage; dry_run only reports what is available. Uses the same source as Zotero Desktop's 'Find Available PDFs'.

Delete a collection (folder) from your Zotero library; confirm with the user first. Items inside the collection are NOT deleted — they remain in your library. Disabled unless the server setting UNSAFE_OPERATIONS is 'all'.

Delete one or more items from your Zotero library: they are permanently deleted (not moved to the Zotero trash), so confirm with the user first. Accepts up to 50 item keys per call. Disabled unless the server setting UNSAFE_OPERATIONS is 'items' or 'all'.