{
"markdown": "# zotero-native-mcp\n\n**An MCP server that reads *and writes* your Zotero 10+ library, entirely offline.**\n\n[](https://www.zotero.org/)\n[](https://www.npmjs.com/package/zotero-native-mcp)\n[](https://github.com/dvdsosa/zotero-native-mcp/actions/workflows/ci.yml)\n[](LICENSE)\n\nConnect Zotero to Claude, Claude Code, Cursor, or any [Model Context Protocol](https://modelcontextprotocol.io)\nclient. Your assistant can search your library, read PDF full text, create\ncollections, add references, and attach PDFs from your disk.\n\nEvery operation runs against the Zotero application on `127.0.0.1`. **No\nzotero.org account. No web API key. No Zotero plugin. No cloud round trip.**\n\n```text\nYou: \"File that arXiv paper under Thesis > Methods and attach the PDF\n I just downloaded.\"\n\nClaude: ✓ created collection \"Methods\" under \"Thesis\"\n ✓ added \"Attention Is All You Need\" (Vaswani et al., 2017)\n ✓ attached transformer.pdf … in 180 ms\n```\n\n## Why this exists\n\nZotero 10 added **write support to its built-in local API**. Before that, every\nZotero MCP server had to work around a read-only local endpoint, either by\nrouting writes through `api.zotero.org` (slow, needs an API key, needs your\nlibrary synced to the cloud) or by shipping a separate Zotero plugin you had to\ninstall and keep up to date.\n\nThis server uses the native capability directly. Nothing to install inside\nZotero, no credentials to manage, and reads land in **8–60 ms** because nothing\ntouches the network.\n\n| Criterion | Web API servers | Plugin-based servers | **zotero-native-mcp** |\n|---|:---:|:---:|:---:|\n| Works offline | ❌ | ✅ | **✅** |\n| Needs a zotero.org API key | ✅ required | ❌ | **❌** |\n| Needs a Zotero plugin (`.xpi`) | ❌ | ✅ required | **❌** |\n| Create collections | ✅ | ✅ | **✅** |\n| Attach local PDFs | ⚠️ via cloud | ✅ | **✅** |\n| Typical read latency | 500–1500 ms | <50 ms | **8–60 ms** |\n\n## Requirements\n\n- **Zotero 10 or newer**, running. This is a hard floor, not a preference:\n writing through the local API did not exist before Zotero 10. On Zotero 7–9\n the read tools work and every write fails.\n- Zotero → **Settings → Advanced** → enable\n **\"Allow other applications on this computer to communicate with Zotero\"**.\n- Node.js 22 or newer. Node 20 reached end of life in April 2026.\n\n## Tested on\n\nEverything below is a statement of *evidence*, not of intent. Other platforms\nand clients are expected to work. The server is portable TypeScript talking to\n`127.0.0.1`, with nothing platform-specific by design. But they have not been\nverified, and this table is the honest extent of it.\n\n| Component | Verified against |\n|---|---|\n| 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 |\n| Zotero | 10.0.1 |\n| Node.js | 26.8, 22.23 and 24.16 respectively; 22, 24 and 26 in CI |\n| MCP client | Claude Code 2.1, on macOS and Windows |\n| Libraries | Personal **and** group, all 28 tools exercised in both |\n\nCI runs the unit and mock-protocol suites across a matrix of **Linux, macOS and\nWindows × Node 22, 24 and 26**, so portability of the code itself is covered on\nall three platforms. What no runner can cover is the conversation with a real\nZotero, since none is installed there. That part was done by hand:\n`scripts/coverage.mjs` reaches **all 28 tools on all three operating systems**,\nagainst a live library.\n\n**Not yet verified.** Intel Macs; Claude Code on Linux, where only the scripts\nwere run; Claude Desktop, Cursor and other MCP clients anywhere.\n\nIf you run it somewhere not on this list, a report either way is welcome, those\nare the most useful issues this project can receive right now.\n\n## Back up your library first\n\n> [!WARNING]\n> **This server can modify and delete items in your Zotero library.** Back it up\n> before you start, and keep backing it up.\n>\n> Deleting is reversible by default: `zotero_delete_items` and\n> `zotero_delete_collection` move things to **Zotero's trash**, where you can\n> restore them from the Zotero window or with `zotero_restore_items`. But Zotero\n> empties that trash automatically after 30 days, and both tools take a\n> `permanent: true` that erases outright, no undo, attachment files removed from\n> disk, nothing in the API able to bring them back. `zotero_empty_trash` does the\n> same to everything already in the trash.\n>\n> These tools are driven by an assistant interpreting instructions in natural\n> language, which can misread which item you meant.\n>\n> **To back up:** quit Zotero, then copy your whole data directory, `~/Zotero`\n> on macOS and Linux, `%USERPROFILE%\\Zotero` on Windows, or whatever\n> **Settings → Advanced → Files and Folders** reports. It holds `zotero.sqlite`\n> and the `storage` folder with every attachment. Zotero's own guidance is at\n> [zotero.org/support/zotero_data](https://www.zotero.org/support/zotero_data).\n>\n> Syncing to zotero.org is **not** a backup: a deletion syncs too.\n>\n> This software is provided as is, without warranty of any kind, and its authors\n> accept no liability for data loss. See [LICENSE](LICENSE).\n\n## Quick start\n\n```bash\nclaude mcp add --scope user zotero-native-mcp -- npx -y zotero-native-mcp\n```\n\n\nOther clients (Claude Desktop, Cursor, …)
\n\n```json\n{\n \"mcpServers\": {\n \"zotero-native-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"zotero-native-mcp\"]\n }\n }\n}\n```\n \n\n`--scope user` registers it for every project. Without it, `claude mcp add`\ndefaults to the *local* scope, which ties the server to the one directory you\nran the command in, open anything else and the tools are simply absent.\n\nNo environment variables are needed. Start a new session, then ask your\nassistant to run `zotero_status` to confirm the connection.\n\nThe first time a tool **writes**, Zotero shows a dialog asking whether to allow\nit. Choose **\"Always Allow\"** so you are not asked again.\n\n## Documentation\n\n| Document | What it covers |\n|---|---|\n| 📚 **[Tutorial](docs/tutorial.md)** | New here? Ten minutes from install to filing a paper with its PDF. |\n| 🔧 **[How-to guides](docs/how-to/)** | [Attach PDFs](docs/how-to/attach-pdfs.md) · [Group libraries](docs/how-to/group-libraries.md) · [Migrate from another Zotero MCP](docs/how-to/migrating.md) · [Recover a deletion](docs/how-to/recover-deleted-items.md) · [Troubleshooting](docs/how-to/troubleshooting.md) |\n| 📖 **[Reference](docs/reference.md)** | All 28 tools, parameters, outputs, limits, environment variables. |\n| 💡 **[Explanation](docs/explanation/)** | [Architecture](docs/explanation/architecture.md) · [Linked vs imported attachments](docs/explanation/attachments.md) · [How authorization works](docs/explanation/authorization.md) |\n| 🛠 **[Contributing](docs/CONTRIBUTING.md)** | Development setup, the 73-test suite, and exercising every tool against a live Zotero. |\n\n## Tools at a glance\n\n**Collections**: `list_collections` `get_collection` `create_collection`\n`update_collection` `delete_collection` `restore_collection`\n\n**Items**: `search_items` `get_item` `get_item_children` `create_items`\n`update_item` `delete_items` `restore_items` `add_items_to_collection`\n`remove_items_from_collection` `get_item_fulltext` `export_items`\n\n**Trash**: `list_trash` `empty_trash` (and the `restore_*` tools above)\n\n**Attachments**: `attach_file` `get_attachment_path`\n\n**Discovery**: `list_tags` `list_saved_searches` `run_saved_search`\n\n**System**: `status` `authorize` `list_libraries` `get_item_type_fields`\n\nAll names are prefixed `zotero_`. See the **[reference](docs/reference.md)** for\nfull signatures.\n\n## Prior art\n\nThis project is not a fork. It was written from scratch once Zotero 10 made\nnative local writes possible, but it stands on the shoulders of earlier work\nthat solved the same problem under tighter constraints:\n\n- **[54yyyu/zotero-mcp](https://github.com/54yyyu/zotero-mcp)**: the most\n widely used Zotero MCP server. Rich feature set including semantic search;\n writes go through `api.zotero.org`.\n- **[cookjohn/zotero-mcp](https://github.com/cookjohn/zotero-mcp)**: a Zotero 7\n plugin exposing an MCP endpoint from inside Zotero, with vector search.\n- **[Ayanya-0628/zotero-mcp](https://github.com/Ayanya-0628/zotero-mcp)** and\n **[dzackgarza/zotero-local-write-api](https://github.com/dzackgarza/zotero-local-write-api)**: local-first writes via a companion `.xpi` write endpoint.\n- **[kujenga/zotero-mcp](https://github.com/kujenga/zotero-mcp)**: a lightweight\n Python server for the Zotero API.\n\nIf you need Zotero 7/8/9 support, semantic or vector search, or writes to a\nlibrary you only have cloud access to, then those projects remain the right\nchoice.\n\n## Contributing\n\nIssues and pull requests are welcome. CI must pass on Linux, macOS and Windows\nacross Node 22, 24 and 26.\n\nSee **[CONTRIBUTING](docs/CONTRIBUTING.md)** for the development setup, the test\nsuite, and the scripts that exercise every tool against a live Zotero.\n\n## License\n\nMIT © David Sosa\n\n---\n\nKeywords: Zotero MCP server · Model Context Protocol · Zotero Claude\nintegration · Zotero local API · offline reference manager automation ·\nZotero AI assistant · BibTeX export · academic research tooling · Claude Code\nZotero · Cursor Zotero\n",
"bytes": 9585,
"sha": "756e2aa4a5041cacdd2cbfcb09859c8b937916a0c5f7b9139368ae841caf6685",
"repo_slug": "dvdsosa/zotero-native-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_dvdsosa_zotero_native_mcp_f8f48045/readme"
}