Zotero Native MCP

File existing items into a collection, keeping every collection they already belong to. An item in Zotero can sit in any number of collections, so this adds rather than moves. Items already in the collection are reported as unchanged and cost no write.

Attach a file from disk to a Zotero item, or add it as a standalone attachment. mode="linked" (default) records the path only: instant for any file size, but the file must stay put and the attachment does not sync to zotero.org. mode="imported" copies the file into Zotero's storage, so it syncs and survives the original being moved. Group libraries accept only "imported", since a local path means nothing to other members. filePath must be absolute. Pass parentItemKey to hang the file off an existing reference; omit it for a standalone attachment, optionally filed into collections.

Request a local API key so write tools (creating collections, items, and attachments) can run. This raises a modal dialog inside Zotero on the user's screen with three choices: "Allow" issues a single-use key, "Always Allow" issues a persistent one, and "Deny" refuses. Tell the user to expect the dialog, and to pick "Always Allow" for a session that will perform several writes. The key is stored locally and reused; write tools also re-authorize on their own when a single-use key is spent, so calling this manually is only needed to grant access up front. Calling it when a key is already stored reuses that key and shows no dialog.

Create one or more collections, optionally nested under an existing collection. Up to 50 per call. Creating a nested tree takes one call per level, since a child needs its parent's key. Requires write access; zotero_authorize runs automatically if none has been granted.

Create up to 50 items in one call. Set `collections` on an item to file it into collections as it is created, which is cheaper than creating it and moving it afterwards. Notes and attachments are created by setting parentItem. To attach a file from disk use zotero_attach_file instead, which handles the whole attachment protocol. Check the returned `failures` array: Zotero validates each item independently, so some can succeed while others fail.

Move collections to Zotero's trash, which is reversible and the default. The items inside are never deleted either way: they stay in the library and in any other collection they belong to. Subcollections follow their parent. Pass permanent: true only on an explicit request from the user, to erase the collections outright with no way back. Note that a trashed collection cannot be listed through the local API, so record the key returned here if it may need restoring.

Move up to 50 items to Zotero's trash, where the user can restore them from the Zotero window or with zotero_restore_items. This is the default and it is reversible. Trashed items keep their attachments and files; Zotero empties the trash automatically after 30 days by default. Pass permanent: true only when the user has explicitly asked for an irreversible delete: that erases the items outright, takes their child notes and attachments with them, removes attachment files from disk, and cannot be undone by anything.

Permanently erase every item in the trash. This is irreversible and removes attachment files from disk. As an interlock against emptying a trash the caller has not looked at, expectedCount must equal the number of items actually in it: call zotero_list_trash first and pass its totalResults. If the two disagree the call is refused and nothing is deleted. Only use this when the user has explicitly asked to empty the trash.

Export items in a citation format. Use format "bibtex", "biblatex", "ris", "csljson", "csv" or "tei" for a machine-readable export, or "bib" to render a formatted bibliography in a citation style (set `style`, e.g. "apa", "chicago-note-bibliography", "ieee"). Returns the export as text.

Resolve an attachment to its absolute path on this machine, so the file can be opened and read directly. Works for both linked and imported attachments. Passing a regular item key returns the paths of all of its file attachments. Use this to read a PDF whose text Zotero has not indexed.

Fetch one collection by key, including its name, parent collection, item count and current version. The version is what zotero_update_collection and zotero_delete_collection use for conflict detection.

Fetch one item by key with all of its metadata. Set includeChildren to also return its notes and attachments, which is the quickest way to find the attachment key needed to read a PDF or its full text.

List the child notes, attachments and annotations of an item. Attachment children carry the linkMode and filename needed by zotero_get_attachment_path and zotero_get_item_fulltext.

Return the indexed full text of an attachment. Passing a regular item key works too: its attachments are searched and the first one with indexed text is used. Text comes from Zotero's own index, so it is available only for attachments Zotero has indexed. Long documents can be truncated with maxCharacters.

List the valid field names and creator types for a Zotero item type, or list every item type when itemType is omitted. Call this before zotero_create_items with an unfamiliar item type: Zotero rejects a write outright if it carries a field the type does not define.

List collections in a library. scope="all" returns every collection flat (each carrying its parentCollection key, so the full tree can be reconstructed in one call), "top" returns only root-level collections, and "children" returns the direct subcollections of parentKey. Collection keys returned here are what zotero_create_items, zotero_add_items_to_collection and zotero_search_items take.

List the personal library and every group library available locally. Use this to get the groupId that other tools take when the target is a group library rather than "My Library".

List the saved searches defined in the library, with their conditions. Run one with zotero_run_saved_search. Note that the local API can actually execute saved searches, which the zotero.org web API cannot.

List tags in the library, optionally only those used within one collection or matching a search. Useful for discovering how a library is organized before filtering zotero_search_items by tag.

List the items currently in Zotero's trash, which are the ones zotero_restore_items can bring back. Note that trashed *collections* do not appear here: Zotero's local API offers no way to enumerate them, so a trashed collection can only be restored by key or from the Zotero window.

Remove items from one collection. The items stay in the library and in any other collection they belong to; nothing is deleted. Items that were not in the collection are reported as unchanged.

Bring collections back out of Zotero's trash, undoing a non-permanent zotero_delete_collection. You must know the key: Zotero's local API cannot list trashed collections, so there is no way to discover them from here, the user can see them in the Zotero window's trash. A collection erased permanently cannot be restored at all.

Bring items back out of Zotero's trash, undoing a non-permanent zotero_delete_items. The items return to the collections they were in. Only works while they are still in the trash: nothing can recover an item that was erased permanently or that Zotero has already purged after its 30-day retention.

Execute a saved search and return the matching items. The search runs against the local database using Zotero's own engine, so the results match what the saved search shows in the Zotero UI.

Search the local Zotero library. `q` runs Zotero's quicksearch: qmode "titleCreatorYear" (default) matches titles, creators and years, while "everything" also matches attachment full text and notes. Filters combine: pass collectionKey to search inside one collection, itemType to restrict by type ("-attachment" excludes a type), tag to filter by tag. Omit `q` to browse. Returns flattened item metadata; use zotero_get_item for one item in full.

Check that the local Zotero instance is running and reachable, and report its version, schema version, instance ID, and whether write access has been granted yet. Call this first when any other tool reports a connection or authorization problem.

Rename a collection and/or move it under a different parent. Pass parentCollectionKey=null to move a collection to the root of the library. The current version is fetched automatically unless expectedVersion is given, in which case the write fails with a conflict if the collection changed in the meantime.

Patch fields on an existing item. Only the fields passed in `fields` change; everything else is left alone. Array fields are replaced wholesale, so to change collection membership prefer zotero_add_items_to_collection / zotero_remove_items_from_collection, which merge instead of overwriting. The current version is read automatically unless expectedVersion is supplied.