zotero-native-mcp

An MCP server that reads and writes your Zotero 10+ library, entirely offline.

Connect Zotero to Claude, Claude Code, Cursor, or any Model Context Protocol client. Your assistant can search your library, read PDF full text, create collections, add references, and attach PDFs from your disk.

Every operation runs against the Zotero application on 127.0.0.1. No zotero.org account. No web API key. No Zotero plugin. No cloud round trip.

You:     "File that arXiv paper under Thesis > Methods and attach the PDF
          I just downloaded."

Claude:  ✓ created collection "Methods" under "Thesis"
         ✓ added "Attention Is All You Need" (Vaswani et al., 2017)
         ✓ attached transformer.pdf                          … in 180 ms

Why this exists

Zotero 10 added write support to its built-in local API. Before that, every Zotero MCP server had to work around a read-only local endpoint, either by routing writes through api.zotero.org (slow, needs an API key, needs your library synced to the cloud) or by shipping a separate Zotero plugin you had to install and keep up to date.

This server uses the native capability directly. Nothing to install inside Zotero, no credentials to manage, and reads land in 8–60 ms because nothing touches the network.

| Criterion | Web API servers | Plugin-based servers | zotero-native-mcp | |---|:---:|:---:|:---:| | Works offline | ❌ | ✅ | ✅ | | Needs a zotero.org API key | ✅ required | ❌ | ❌ | | Needs a Zotero plugin (.xpi) | ❌ | ✅ required | ❌ | | Create collections | ✅ | ✅ | ✅ | | Attach local PDFs | ⚠️ via cloud | ✅ | ✅ | | Typical read latency | 500–1500 ms | <50 ms | 8–60 ms |

Requirements

• Zotero 10 or newer, running. This is a hard floor, not a preference: writing through the local API did not exist before Zotero 10. On Zotero 7–9 the read tools work and every write fails.
• Zotero → Settings → Advanced → enable "Allow other applications on this computer to communicate with Zotero".
• Node.js 22 or newer. Node 20 reached end of life in April 2026.

Tested on

Everything below is a statement of evidence, not of intent. Other platforms and clients are expected to work. The server is portable TypeScript talking to 127.0.0.1, with nothing platform-specific by design. But they have not been verified, and this table is the honest extent of it.

| Component | Verified against | |---|---| | Operating system | macOS 26.6 (Apple Silicon), Windows 11 Pro build 26200 (x64) and Ubuntu 24.04 LTS (x86_64), all three against a real Zotero | | Zotero | 10.0.1 | | Node.js | 26.8, 22.23 and 24.16 respectively; 22, 24 and 26 in CI | | MCP client | Claude Code 2.1, on macOS and Windows | | Libraries | Personal and group, all 28 tools exercised in both |

CI runs the unit and mock-protocol suites across a matrix of Linux, macOS and Windows × Node 22, 24 and 26, so portability of the code itself is covered on all three platforms. What no runner can cover is the conversation with a real Zotero, since none is installed there. That part was done by hand: scripts/coverage.mjs reaches all 28 tools on all three operating systems, against a live library.

Not yet verified. Intel Macs; Claude Code on Linux, where only the scripts were run; Claude Desktop, Cursor and other MCP clients anywhere.

If you run it somewhere not on this list, a report either way is welcome, those are the most useful issues this project can receive right now.

Back up your library first

[!WARNING] This server can modify and delete items in your Zotero library. Back it up before you start, and keep backing it up.

Deleting is reversible by default: zotero_delete_items and zotero_delete_collection move things to Zotero's trash, where you can restore them from the Zotero window or with zotero_restore_items. But Zotero empties that trash automatically after 30 days, and both tools take a permanent: true that erases outright, no undo, attachment files removed from disk, nothing in the API able to bring them back. zotero_empty_trash does the same to everything already in the trash.

These tools are driven by an assistant interpreting instructions in natural language, which can misread which item you meant.

To back up: quit Zotero, then copy your whole data directory, ~/Zotero on macOS and Linux, %USERPROFILE%\Zotero on Windows, or whatever Settings → Advanced → Files and Folders reports. It holds zotero.sqlite and the storage folder with every attachment. Zotero's own guidance is at zotero.org/support/zotero_data.

Syncing to zotero.org is not a backup: a deletion syncs too.

This software is provided as is, without warranty of any kind, and its authors accept no liability for data loss. See LICENSE.

Quick start

claude mcp add --scope user zotero-native-mcp -- npx -y zotero-native-mcp

{
  "mcpServers": {
    "zotero-native-mcp": {
      "command": "npx",
      "args": ["-y", "zotero-native-mcp"]
    }
  }
}

--scope user registers it for every project. Without it, claude mcp add defaults to the local scope, which ties the server to the one directory you ran the command in, open anything else and the tools are simply absent.

No environment variables are needed. Start a new session, then ask your assistant to run zotero_status to confirm the connection.

The first time a tool writes, Zotero shows a dialog asking whether to allow it. Choose "Always Allow" so you are not asked again.

Documentation

| Document | What it covers | |---|---| | 📚 Tutorial | New here? Ten minutes from install to filing a paper with its PDF. | | 🔧 How-to guides | Attach PDFs · Group libraries · Migrate from another Zotero MCP · Recover a deletion · Troubleshooting | | 📖 Reference | All 28 tools, parameters, outputs, limits, environment variables. | | 💡 Explanation | Architecture · Linked vs imported attachments · How authorization works | | 🛠 Contributing | Development setup, the 73-test suite, and exercising every tool against a live Zotero. |

Tools at a glance

Collections: list_collections get_collection create_collection update_collection delete_collection restore_collection

Items: search_items get_item get_item_children create_items update_item delete_items restore_items add_items_to_collection remove_items_from_collection get_item_fulltext export_items

Trash: list_trash empty_trash (and the restore_* tools above)

Attachments: attach_file get_attachment_path

Discovery: list_tags list_saved_searches run_saved_search

System: status authorize list_libraries get_item_type_fields

All names are prefixed zotero_. See the reference for full signatures.

Prior art

This project is not a fork. It was written from scratch once Zotero 10 made native local writes possible, but it stands on the shoulders of earlier work that solved the same problem under tighter constraints:

• 54yyyu/zotero-mcp: the most widely used Zotero MCP server. Rich feature set including semantic search; writes go through api.zotero.org.
• cookjohn/zotero-mcp: a Zotero 7 plugin exposing an MCP endpoint from inside Zotero, with vector search.
• Ayanya-0628/zotero-mcp and dzackgarza/zotero-local-write-api: local-first writes via a companion .xpi write endpoint.
• kujenga/zotero-mcp: a lightweight Python server for the Zotero API.

If you need Zotero 7/8/9 support, semantic or vector search, or writes to a library you only have cloud access to, then those projects remain the right choice.

Contributing

Issues and pull requests are welcome. CI must pass on Linux, macOS and Windows across Node 22, 24 and 26.

See CONTRIBUTING for the development setup, the test suite, and the scripts that exercise every tool against a live Zotero.

License

MIT © David Sosa

Keywords: Zotero MCP server · Model Context Protocol · Zotero Claude integration · Zotero local API · offline reference manager automation · Zotero AI assistant · BibTeX export · academic research tooling · Claude Code Zotero · Cursor Zotero