Zotero MCP

Move a Zotero item to the Trash. Works for any item type (book, journalArticle, webpage, attachment, etc.). For notes, use zotero_manage_note(action='delete') — identical mechanism, constrained to notes for safety. Trashed items are recoverable from Zotero's Trash — empty the Trash in the Zotero UI for permanent deletion. By default refuses to trash notes; set allow_note=True to override.

Render a formatted bibliography or in-text citations for a set of Zotero items using Zotero's own CSL citation engine, so you can drop references straight into a manuscript. item_keys: optional list of 8-character item keys (also accepts a JSON list string); takes precedence over collection_key. collection_key: optional collection to export instead; if neither is given, the active library is exported. style: CSL style short name (default 'apa'); e.g. 'modern-language-association', 'chicago-note-bibliography', 'ieee'. Ignored for bibtex. export_format: 'bib' (formatted reference-list entries, d…

Scan the active library (or a single collection) for duplicate items and return candidate groups for review. This tool only IDENTIFIES duplicates — it doesn't merge them. Call zotero_merge_duplicates to merge one group, or zotero_merge_duplicates(auto=True) to merge every high-confidence group in one pass. method: 'both' (default) — match on title OR DOI; 'title' — normalized-title match only (lowercase, punctuation-stripped); 'doi' — exact DOI match only (safest for automation). Prefer 'doi' when the user intends to run merge_duplicates unattended. collection_key: optional 8-character key to …

Discover papers related to a known work by following its citation graph via OpenAlex (a free scholarly index). Use this to expand a literature review: find what a paper CITES (its references) and what CITES it (newer follow-up work). Each related paper is flagged as already in your Zotero library or not, so you can quickly spot gaps to fetch (e.g. via zotero_add_item). identifier: either an 8-char Zotero item key (its DOI is looked up) or a DOI / DOI-URL directly (e.g. '10.1038/nature12373' or 'https://doi.org/10.1038/nature12373'). direction: 'references' (works this paper cites), 'citations'…

Get annotations (highlights and attached notes on PDF/EPUB attachments) for a specific item or across the active Zotero library. item_key: pass the parent item key OR an attachment key — both work; attachment-to-parent resolution is automatic. ALWAYS pass item_key when you know which item you want; calling without it returns every annotation in the library (potentially thousands). use_pdf_extraction=True falls back to direct PDF parsing when the Zotero API has no stored annotation record — useful for annotations made outside Zotero desktop. limit: cap on annotations returned; None (default) re…

Return the local filesystem path(s) of a Zotero item's attachments. Local mode only. Useful when you want to read a large PDF directly (e.g., a book) instead of going through zotero_get_item_fulltext, which is page-limited.

Get all items in a specific Zotero collection. Supports detail='keys_only' (minimal), 'summary' (default, no abstracts), or 'full' (with abstracts). Includes PDF/notes indicators. include_subcollections=True also returns items filed in collections nested beneath this one (default False, matching Zotero's own 'Search subcollections' checkbox). For a collection larger than limit, page through it with offset (the response names the next offset to pass). TIP: To find papers on a specific topic, use zotero_semantic_search instead — it's faster and returns only relevant results.

List all collections in the currently active Zotero library as a hierarchical tree (parents and nested subcollections, each with its 8-character key). Use this when the user wants to see the full library structure. If you already know a name and just need the key, prefer zotero_search_collections — it returns only matches. Scope is limited to the active library — switch libraries with zotero_switch_library before listing. Deep hierarchies render inline without truncation, so very deep trees can be long. limit: cap on collections returned; pass None (default) to use 100, or raise to 5000 for li…

Fetch recent items from a SPECIFIC Zotero RSS feed by its local library ID. Returns titles, authors, dates, and URLs as a markdown list. Find the right library_id first with zotero_list_feeds — guessing feed IDs never works. library_id: INTEGER library ID of the feed (as shown by zotero_list_feeds, NOT the feed's name or URL). limit: max feed items to return (default 20). LOCAL MODE ONLY — feeds aren't exposed by the Zotero web API. Calls in web mode return a clear error. Read-only; does not trigger a new RSS fetch (Zotero desktop refreshes on its own schedule). Example: zotero_get_feed_items(…

List the child items (attachments, notes, annotations under an attachment) of one OR MANY parent Zotero items. Use it to find an item's PDF/EPUB attachment key before zotero_create_annotation or zotero_get_pdf_outline — those take an attachment key, NOT the parent item key. item_key: one 8-character parent key, or an ARRAY of keys (a JSON-encoded list string also works). Pass every key you have in ONE call: a batch is one API round trip instead of N, and a bad key is reported in its own section instead of aborting. Returns markdown — one key: attachments (content type, filename) and notes in f…

Return the extracted text of a Zotero item's primary attachment (PDF or EPUB). WARNING: returns most or all of the paper (often 10K+ tokens). Use ONLY when the user explicitly wants to READ the paper — not for searching or browsing. For topic search use zotero_semantic_search; for metadata only use zotero_get_item_metadata. PDFs are read up to fulltext_display_max_pages (10 by default); when that cuts a document short the heading names the page range and TRUNCATED — read on with zotero_read_pdf_pages. Avoid calling this on multiple papers in one conversation unless the user specifically asked …

Fetch detailed metadata (title, creators, date, DOI, publisher, tags, abstract, URL, etc.) for ONE Zotero item by key. If the metadata and abstract don't contain what you need, call zotero_get_item_fulltext to read the paper — but that is resource-intensive (10K+ tokens) and should NEVER be used for searching; use zotero_search_items or zotero_semantic_search instead. item_key: the 8-character Zotero item key (NOT a DOI or title). include_abstract=True (default) includes the abstractNote in markdown output; pass False to trim tokens when you don't need it. (Ignored in bibtex/json formats.) for…

Get all related items for a specific Zotero item. Returns items that are linked via the relations field.

Read notes from the active Zotero library. Omit query to LIST notes: with item_key, that item's child notes; without it, notes library-wide (capped by limit). Pass query to SEARCH note and annotation text instead — case-insensitive substring over the stripped-text body, library-wide, so query and item_key cannot be combined. limit: max results (default 20). truncate=True (default) shortens long bodies for display; pass False for complete content (list mode only). raw_html=True returns a note's original HTML instead of stripped text — use it when you intend to edit and round-trip via zotero_man…

Detect candidate figure/table regions on a PDF page and return their normalized bounding boxes, so area annotations can be placed on detected content instead of guessed positions. ALWAYS call this before zotero_create_annotation's area mode unless exact coordinates are already known. Returns each region's bounding box (x, y, width, height in [0, 1]), source (image/drawing/table/merged), associated caption (e.g. 'Figure 3: ...'), confidence level, and a ready-to-paste zotero_create_annotation call. Note: detection is geometric — boxes cover the graphical core of a figure/table; text labels insi…

Extract the table of contents (outline/bookmarks) from a PDF attachment, returned as a hierarchical markdown list with each entry's page number. Use this to orient in a paper before calling zotero_get_item_fulltext — the outline is typically < 200 tokens versus 10K+ for the full text. If the PDF has no embedded outline, returns a short 'no outline' message rather than failing. item_key: the PDF ATTACHMENT key OR the parent item key — both are accepted; attachment-to-parent resolution is automatic. Find the right key with zotero_get_item_children if unsure. Scope: PDFs only (EPUBs have no outli…

List the most recently ADDED items (by dateAdded) in the active library, optionally scoped to a single collection. Use this for 'what did I add recently?' questions — NOT for general topic search (use zotero_semantic_search) or for a collection's full contents (use zotero_get_collection_items). limit: how many recent items to return (default 10). collection_key: optional 8-character collection key to restrict results to that collection; when omitted, returns the N most recent items across the whole library. Ordering is dateAdded DESC. All item types are returned, INCLUDING standalone notes and…

Report the semantic search database's readiness and stats: item count, last update time, embedding provider / model, and whether the [semantic] optional dependency is installed. Use this to decide whether zotero_semantic_search will return useful results, or whether the user should run zotero_update_search_database first. Takes no parameters; no side effects. Returns a human-readable status block. If the [semantic] extras are not installed, returns an install hint instead of stats. Example: zotero_get_search_database_status() → count, last sync, provider summary.

List all tags used in the currently active Zotero library, as a flat markdown list (one tag per line). Use this for tag discovery before filtering with zotero_search_by_tag or batch-editing with zotero_batch_update. Scope is the active library only — switch with zotero_switch_library before listing. The list is flat: tags have no parent/child structure in Zotero, only a colon convention ("area/subtag") that this tool preserves verbatim. limit: cap on tags returned; None (default) returns all. Example output: - to-read - methods/qualitative - AI agents

Audit PDF coverage across your Zotero library (or one collection): which items have a downloaded PDF attachment and which are missing one. Use this to find papers you can still fetch full text for — the missing list includes each item's DOI so you can pass it to zotero_add_item's open-access download cascade. collection_key: optional 8-char key to scope the audit to one collection; omit to scan the whole library. limit: max top-level items to scan (default 200). Attachments, notes, and annotations are skipped as scan targets; an item counts as covered if it (or any child) is a PDF attachment. …

List all RSS feed subscriptions configured in the local Zotero desktop install. Each entry includes the feed's library ID, display name, source URL, item count, and last-checked timestamp. Use this to discover a feed's library_id before calling zotero_get_feed_items; the two form a list-then-fetch workflow analogous to list_libraries + switch_library. No parameters. LOCAL MODE ONLY — RSS feeds live in the local SQLite database and are not exposed by the Zotero web API. Running this in web mode returns a clear error. Read-only; no side effects. Example: zotero_list_feeds() → all subscribed feed…

List every Zotero library this MCP can address: the user's personal library (switch to it with library_type='user'), all group libraries the user is a member of (with groupID), and (in local mode) RSS feed libraries. Each entry shows the library/group ID, display name, and item count. Use this to discover a library ID before calling zotero_switch_library — the two form a read-then-switch workflow. If the user only wants to see Zotero collections inside the CURRENT library, use zotero_get_collections instead. No parameters. In local mode: reads the local Zotero SQLite DB (fast, includes RSS fee…

Create, update, or trash a Zotero note. item_key: the PARENT item's key for action='create', the NOTE's own key for 'update' and 'delete' (zotero_get_notes finds it). create: needs note_text — Markdown with $math$, plus <u> <s> <sub> <sup> <mark> <span style="color:red"> (or background-color), converted to note HTML; HTML input is sanitized. note_title becomes a heading; tags optional. update: needs note_text (Markdown or HTML, as for create). append=False (default) REPLACES the whole body, append=True adds to the end. To keep existing formatting, fetch with zotero_get_notes(raw_html=True), ed…

Description is built at runtime.

Read specific page range(s) from a PDF attachment of a Zotero item. Use this when you know which pages to read — for example after getting the PDF outline via zotero_get_pdf_outline. Pages are 1-indexed. format='text' (default) returns Markdown with the heading structure preserved and flags pages whose equations, figures or tables the text garbles. format='image' returns the pages as PNG images (up to 10) so those can be read exactly; rect=[x, y, width, height] (normalized 0-1, e.g. from zotero_get_page_layout) returns just that region of start_page, zoomed in.

Remove a related item relationship from a Zotero item.

Look up a single Zotero item by its BetterBibTeX citation key (e.g. 'Smith2024' or 'cladderMicus2018'). Returns that one item's metadata, or a not-found message if no item has that key. citekey: the citation key exactly as assigned by BetterBibTeX (case-sensitive). In local mode: queries the running Better BibTeX plugin via its HTTP API (Zotero desktop must be running and have BBT installed). In web mode: scans the 'Extra' field of items for 'Citation Key:' lines — slower, and may miss items whose keys aren't persisted to Extra. Requires the Better BibTeX plugin in the user's Zotero install. F…

Find items carrying one or more tags, with boolean syntax support. tag: list of tag strings; each entry is a condition ANDed with the others, and within an entry you can use ' OR ' for disjunction and a leading '-' for exclusion. Example: tag=['methods OR methodology', '-draft'] matches items tagged 'methods' OR 'methodology' AND NOT tagged 'draft'. item_type: '-attachment' (default) excludes attachments; pass 'journalArticle', 'book', etc. to filter. limit: max results (default 10). collection_key: optional 8-char key to scope to a collection. include_subcollections: also search collections n…

Search collections by name in the active library and return their 8-character keys. Matching is case-insensitive substring and applies ONLY to the collection's own name — not to parent names, descriptions, or items inside the collection. Multi-word queries are ANDed across words (NOT OR-ed): query 'reading list' matches only collections whose name contains both 'reading' AND 'list'. To match either word, issue two separate searches. Leading/trailing whitespace is ignored and empty words are dropped. Returns the collection's key plus its parent (if any). include_trashed: when True, also match c…

Search Zotero items by substring match against metadata (title, creators, year, and — in 'everything' mode — abstract). Returns metadata + abstracts as markdown. IMPORTANT: keep queries SHORT and SIMPLE — 'Author Year' (e.g. 'Brewer 2011') or just an author name ('Cladder-Micus'). This is substring matching, not web search: each extra word NARROWS the match, so adding topic words usually returns fewer results, not more. For topic discovery, use zotero_semantic_search instead; for tag filtering use zotero_search_by_tag. If a query finds nothing, this tool automatically falls back to simplified …

Prioritized topic-search tool. Find papers by semantic similarity to a query using AI embeddings — the BEST tool for finding papers on a topic (e.g. 'papers about mindfulness-based therapy'), far more efficient than scanning collection items or reading abstracts. Searches the ACTIVE library by default; pass search_all_libraries=True to cover every indexed library. query: the topic or concept; natural-language phrases work well. limit: max results (default 10). filters: optional ChromaDB metadata filter, one key per dict (e.g. {'item_type': 'journalArticle'}); also accepts a JSON string. Keys: …

Change which collections existing items belong to — an incremental add/remove of item membership, NOT collection creation (use zotero_create_collection / zotero_delete_collection for that). item_keys must be an ARRAY of item keys, e.g. ["KEY1", "KEY2"] — not a single string. add_to and remove_from accept arrays of collection keys, names, or '/'-separated paths (resolved and validated automatically; unknown, trashed, or ambiguous specs fail before anything is changed). Existing memberships not named in remove_from are left alone; to replace an item's memberships wholesale use zotero_update_item…

Set or clear the parent of a Zotero item. Pass a parent item key to assign or change the parent, or null to make the item top-level. Zotero validates whether the requested parent-child relationship is allowed.

Switch the active library context. EVERY subsequent read/write tool call (collections, items, annotations, search — all of them) operates on the library set here. Changes persist for the rest of the session or until the next switch. Discover valid library IDs/types via zotero_list_libraries first; don't guess. library_id: library ID string as returned by zotero_list_libraries (numeric for user/group, numeric for feeds); for the personal library 'user' or '0' also work. library_type: 'user' — the personal library; 'group' (default) — a group library; 'feeds' — a local RSS feed library; 'default…

Collect every highlight, annotation comment, and child note across a scope and organize them into a structured, per-paper digest that YOU (the agent) can then synthesize into a literature summary. This tool does NOT call an LLM — it only gathers and groups the raw material, so the synthesis step is yours. collection_key: optional 8-character collection key; when given, only annotations/notes whose resolved paper is a member of that collection are included. When omitted, the whole active library is scanned (capped by limit). tag: optional tag or list of tags to filter items by (accepts a string…

Update an existing Zotero annotation. Editable fields: text (highlight text), comment, color (hex like '#ffd400'), and tags. Tags can be replaced wholesale via `tags`, or edited incrementally via `add_tags`/`remove_tags` (mutually exclusive with `tags`). Position/page/sortIndex are anchored to the PDF/EPUB geometry and are not editable.

Rename a collection or move it under a different parent, keeping its key, subcollections and item membership (#517). collection_key: the 8-character key of the collection to change. name: the new name, or omit to keep it. parent_collection: key, name or 'Parent/Child' path of the new parent; a collection cannot be moved under itself or one of its own subcollections. to_top_level=True moves it out of any parent. Pass at least one change. Use zotero_search_collections to find keys. Example: zotero_update_collection(collection_key="KMMQDFQ4", name="AI & ML").

Update metadata on an existing Zotero item by key. Only what you pass is changed. fields: {name: value} of metadata to set (a JSON object string is accepted). Names may be snake_case (title, date, doi, url, abstract, publication_title, access_date, short_title, book_title, citation_key, item_type, place, extra, volume, issue, pages, publisher, issn, isbn, edition, language) or any raw Zotero API field name. An unknown name fails the call and lists the valid ones; a name that is not valid for this item's type is reported as skipped. item_type migrates the item (overlapping fields kept, type-spe…

Build or refresh the semantic search embedding database from Zotero items. Run this: (a) after first install, (b) after adding items via zotero_add_item, or (c) when the user has added items directly in Zotero desktop since the last update. By default the update is INCREMENTAL — only new or changed items are re-embedded, so repeated calls are cheap. force_rebuild=True re-embeds ALL items from scratch (slow; use when changing the embedding model or recovering from corruption). limit: optional cap on items processed (useful for smoke-testing). Progress is reported via the MCP context; on large l…

Report whether and how this server can write to Zotero: local API, web API, hybrid (local reads + cloud writes), or nothing. Read-only and instant — it never opens a dialog. Call it when a write tool reports that no writable backend is configured, to find out which fix applies before asking the user for anything: if the local server supports writes but no key is held, call zotero_authorize_local_writes; otherwise web API credentials are needed. Takes no arguments. Example: zotero_write_capabilities().