Repository navigation
Releases
v0.10.2
- Install as a Claude Code plugin:
/plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp. - An empty
ZOTERO_LIBRARY_TYPEnow means the default (user), as plugin
installs pass unset optional settings as empty strings.
Claude Code: /plugin install zotero --marketplace RaulSimpetru/zotero-library-mcp. Other clients: uvx zotero-library-mcp or pip install zotero-library-mcp==0.10.2.
v0.10.1
- Attaching files to Zotero storage works again (group libraries and setups
without WebDAV): Zotero rejects the full local path Pyzotero sent as the
filename. Uploads are now confirmed, and a rate-limited or failed upload is
reported instead of leaving an empty attachment. list_tagsreturns every tag; Zotero's tag paging metadata is wrong past
200 tags, which made the old listing drop the rest.- Leftover query parameters no longer leak between calls (e.g. a duplicate
check after fetching an item template only searched items of that type). - Searches and tag renames containing the word "tags" no longer crash.
- Tagging, filing, and editing notes or annotations works on trashed items.
- Highlights land correctly on rotated pages with offset crop boxes, match
whole words, check for duplicates at the same location only, and report a
missingoccurrenceinstead of highlighting a different passage. - arXiv imports detect existing copies of any version of the paper.
- CrossRef imports keep organization authors and editors and map books,
edited books, chapters, and dissertations to the right item types; Open
Library books get their authors from the work record. verify_itemshandles DataCite DOIs (arXiv, Zenodo), HTML in CrossRef titles,
and subtitles;health_checkreports read-only keys aswrite_access: false.- BibTeX exports keep Zotero's order and unique citekeys across pages.
- Lists of child items (attachments, notes, annotations) are no longer capped at
100; linked PDFs are skipped, and standalone PDFs can be read. - Removing the last tag color works; deleting tags containing
||is refused. - Hardening for hosted HTTP deployments: downloads connect to the validated IP
(DNS rebinding), JWKS refetches are rate-limited, and file saves use
exclusive temporary files. - DOI imports no longer create duplicates. Zotero's search does not index
DOIs, so the old check never matched; imports now search the resolved title
and compare DOIs (includingDOI:lines in Extra). - ISBN imports no longer create duplicates of books stored with hyphenated
ISBNs; ISBN-10 and ISBN-13 forms now match each other. search_libraryreturns papers instead of matching attachments and notes.- Rate-limited writes are never retried (a retry could duplicate the item) and
now fail instead of reporting success. add_papers_by_dois(attach_pdfs=True)downloads PDFs in parallel.search_fulltextandsearchquery top-level items (about 20x faster).- Fuzzy search and
find_duplicatesreuse a library cache that is kept current
with Zotero's incremental sync (since=), so repeat calls take well under a second. - CrossRef requests use
UNPAYWALL_EMAILas the polite-pool contact when
CROSSREF_MAILTOis unset, and retry rate-limited requests. create_annotationhighlights quotes that wrap across lines in full, counts
occurrenceacross pages, and uses the PDF's own page labels.- PDFs attached during DOI/arXiv import are named after the item title, and the
result now says why a PDF was not attached. - List output shows the correct year for dates like
12/1/1993. health_checkreturnslibrary_typeasuser/groupand reports whether
open-access PDF lookup (UNPAYWALL_EMAIL) is configured.- New
list_trashtool for finding keys to pass torestore_item. - Faster
get_bibtexfor item keys,rename_tag,get_recent_items, fuzzy
searches, andfind_duplicates; Zotero API connections are reused across calls. - Full-library and collection
get_bibtexexports stop downloading once
max_charsis exceeded. get_item_fulltextprefers a PDF's index over a web snapshot's.find_duplicatesreportsitems_scannedandscan_capped.searchfalls back to the item's zotero.org link when it has no URL.- Shorter tool descriptions; library targeting is explained once in the server
instructions.
Install: uvx zotero-library-mcp or pip install zotero-library-mcp==0.10.1. Restart the MCP connection after upgrading.
v0.10.0 — Shared Zotero libraries
Personal and shared Zotero libraries can now be used through the same MCP connection.
- New
list_librariestool discovers the key owner's personal library and shared groups, including IDs and key permissions. - All existing tools accept
library_idandlibrary_typefor selecting a library per call. Omitting both preserves the configured default. - Concurrent requests and nested search, fetch, and export operations keep their selected library.
- Group attachments use Zotero storage; personal WebDAV remains scoped to the configured personal library.
- Current PyMuPDF imports and HTTP client logging preserve valid MCP stdio output and avoid logging credential-bearing URLs.
API key permissions and group membership still determine access. Restart the MCP connection after upgrading to load the new tools and schemas.
Validation: 79 tests passed; wheel and source distribution built; live stdio checks verified shared-library discovery and search, preservation of the personal default, and clean protocol output and logs.
Merged in #3.
v0.9.0
Migrates the server to the MCP 2.0 Python SDK. Follow-up to the 0.8.3 hotfix, which pinned the SDK to <2 to stop fresh installs from breaking.
Requires mcp[cli]>=2.0.0. Stay on 0.8.3 if you need the 1.x SDK.
Changes
FastMCP→MCPServer;Contextnow imported frommcp.server.mcpserver.- Transport options (host, port, HTTP path, stateless mode, DNS-rebinding protection) moved from server-level settings to
run()arguments in 2.0.configure_server()now returns them as a dict rather than mutatingmcp.settings— same CLI flags and environment variables, no user-facing change. - Protocol type fields are read back as snake_case (
isError→is_error,inputSchema→input_schema, and friends). Constructors still accept the camelCase aliases, but the codebase now uses one convention throughout.
Tool and resource definitions were untouched — the tool() and resource() decorators are identical between the two SDK versions.
Verification
60 tests pass on mcp 2.0.0. Both stdio and Streamable HTTP transports start and serve. A live run against a real Zotero library registers all 49 tools with working search, pagination, error handling, and PDF/image resource templates.
v0.8.3
Hotfix: pin the MCP Python SDK to <2.
The SDK's 2.0.0 release removed mcp.server.fastmcp (replaced by mcp.server.mcpserver). Because the dependency was declared as an unbounded mcp[cli]>=1.26.0, fresh installs resolved to 2.0.0 and the server crashed on import:
ModuleNotFoundError: No module named 'mcp.server.fastmcp'
MCP clients surfaced this as Connection closed / "failed to connect". Pinning to the 1.x line restores startup. A port to the 2.0 SDK API will follow in a later release.
v0.8.2
Pagination for large libraries (fixes #2):
get_collection_itemsandsearch_libraryaccept a newstartoffset parameter- Both tools report totals in a footer, e.g.
Showing items 101–200 of 566. Pass start=200 to get the next page. search_libraryresult cap raised from 50 to 100
Full Changelog: v0.8.1...v0.8.2
v0.8.1
v0.8.0
What's Changed
- Add Codex and ChatGPT MCP support by @RaulSimpetru in #1
New Contributors
- @RaulSimpetru made their first contribution in #1
Full Changelog: v0.7.4...v0.8.0