The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Zotero Library MCP listing page.
An MCP server that lets Claude, Codex, and ChatGPT add papers and books to your Zotero library by DOI, arXiv ID, or ISBN — and manage your collections, tags, and items.
The server supports both MCP transports used by these clients:
add_paper_by_doi — Resolve a DOI via CrossRef and add the paper to Zotero (with duplicate detection)add_papers_by_dois — Batch-add up to 50 papers at onceadd_paper_by_arxiv_id — Add a preprint by arXiv ID (uses DOI when available, falls back to arXiv metadata)add_item_from_metadata — Create any supported Zotero item type from validated manual metadataadd_book_by_isbn — Resolve an ISBN via Open Library and add the book to Zotero (with duplicate detection)list_libraries — Discover the API key owner's personal library and shared group libraries, with IDs and key permissionssearch_library — Search your Zotero library by title, author, tag, etc., paginated via start/limit (falls back to fuzzy matching when the exact search returns no results)get_item_details — View full metadata for any itemget_recent_items — List recently added itemsget_unfiled_items — Get items not in any collectionsearch_fulltext — Search Zotero metadata and indexed full textfind_duplicates — Find duplicate items by DOI, ISBN, or normalized titlelist_attachments — List every attachment and choose a specific PDF keyhealth_check — Verify library credentials, access, and storage configurationget_item_fulltext — Return bounded plain text from Zotero's index or a PDF, without leaking temporary pathsget_bibtex — Read-only BibTeX/BibLaTeX export for items, a collection, or the full librarysave_bibtex — Save an export to an authorized local pathget_annotations — List all highlights and annotations on a paper's PDFcreate_annotation — Highlight a text passage in a PDF (searches for the exact text, creates a visible highlight in Zotero's reader, and returns a preview image for verification). Smart overlap handling: exact duplicates update the existing comment; sub-passages get a contrasting highlight color automatically.add_note — Add a note to an itemlist_notes, update_note, delete_note — Manage existing notesupdate_annotation, delete_annotation — Edit or remove annotationsattach_file — Attach a local file over stdio or a ChatGPT file input over HTTPdownload_pdf — Return a remote-safe MCP file resourcesave_pdf — Save a PDF to an authorized local pathlist_collections — List all collections (with nesting)create_collection — Create a new collection (optionally nested under a parent)get_collection_items — Browse items in a collection, paginated via start/limitadd_to_collection — Add an existing item to a collectionremove_from_collection — Remove an item from a collection (keeps it in your library)rename_collection, move_collection — Reorganize collectionslist_tags — List all tags in your libraryadd_tags — Add one or more tags to an item (with optional color)remove_tags — Remove tags from an itemdelete_tags — Delete tags from the entire libraryset_tag_color — Assign a color to a tag (appears in Zotero's tag selector)rename_tag — Rename a tag across all items in your libraryunset_tag_color — Remove a tag color without deleting the tagverify_items — Re-check recent items against CrossRef to catch bad DOIs or title mismatchesdelete_item — Permanently delete an item from your librarydelete_collection — Permanently delete a collectiontrash_item, restore_item — Prefer reversible trash operations for ordinary cleanupThe server also exposes the standard read-only search and fetch tool shapes used by ChatGPT company knowledge and deep research.
Codex and the ChatGPT desktop app share MCP configuration on the same Codex host. Add the server once:
Then restart Codex or the ChatGPT desktop app. In Codex, use /mcp to confirm that zotero is connected. In ChatGPT desktop, open Settings → MCP servers to view the same server.
For WebDAV storage, add the three ZOTERO_WEBDAV_* values shown in the WebDAV example. If the desktop app cannot find uvx, replace it with the full path returned by which uvx.
You can also configure the server directly in ~/.codex/config.toml:
With env_vars, start Codex/ChatGPT from an environment that contains those variables. Use [mcp_servers.zotero.env] instead if you intentionally want to store their values in the config file.
To use WebDAV file storage (e.g. Synology, Nextcloud), include the WebDAV variables:
Add this to your claude_desktop_config.json:
Note: Claude Desktop doesn't inherit your shell's PATH, so you need the full path to
uvx. Find it withwhich uvxin your terminal.
ChatGPT web connects to an HTTPS Streamable HTTP endpoint. Start the server locally with the HTTP transport, then make it reachable through Secure MCP Tunnel or another authenticated HTTPS deployment:
The MCP endpoint is https://your-tunnel.example.com/mcp. Enable developer mode in ChatGPT, create a developer-mode app, and enter that URL as the MCP server URL. See OpenAI's Connect from ChatGPT guide for the current UI flow.
Security: The safest personal setup is OpenAI Secure MCP Tunnel with the MCP server bound to loopback. HTTP mode disables all server-path reads and writes by default.
attach_fileaccepts ChatGPT's authorized file object, whiledownload_pdfreturns an opaque MCP resource link. Safety annotations are approval hints, not an authorization boundary.
For a public deployment, configure an external OAuth 2.1 identity provider. The server validates JWT access tokens against its JWKS endpoint:
The authorization server must publish OAuth/OIDC discovery metadata, support the MCP OAuth 2.1 flow with PKCE, issue tokens for ZOTERO_MCP_OAUTH_RESOURCE, and include the configured scopes. See OpenAI's authentication guide. For testing behind an already authenticated gateway only, --allow-unauthenticated-http explicitly acknowledges an unauthenticated non-loopback listener.
This process still uses one server-side Zotero API key. Every authenticated MCP client can target libraries available to that key, including shared groups. Use a key scoped to the libraries intended for those clients. A true multi-user service must map the verified OAuth identity to separate Zotero credentials and enforce per-user authorization; that deployment architecture is intentionally outside this personal-server package.
If an HTTP deployment genuinely needs server paths, enable them only inside confined roots:
HTTP launch settings can also be supplied as environment variables:
| CLI option | Environment variable | Default |
|---|---|---|
--transport | ZOTERO_MCP_TRANSPORT | stdio |
--host | ZOTERO_MCP_HOST | 127.0.0.1 |
--port | ZOTERO_MCP_PORT or PORT | 8000 |
--http-path | ZOTERO_MCP_HTTP_PATH | /mcp |
--allowed-host | ZOTERO_MCP_ALLOWED_HOSTS (comma-separated) | local hosts |
--allowed-origin | ZOTERO_MCP_ALLOWED_ORIGINS (comma-separated) | local origins |
--stateless-http | ZOTERO_MCP_STATELESS_HTTP | false |
--allow-unauthenticated-http | ZOTERO_MCP_ALLOW_UNAUTHENTICATED_HTTP | false |
--allow-server-files | ZOTERO_MCP_ALLOW_SERVER_FILES | false in HTTP mode |
--file-root | ZOTERO_MCP_FILE_ROOTS (comma-separated) | none |
The environment variables select the default library. Existing calls that omit library arguments continue to use that default.
Call list_libraries() to discover the key owner's personal library and shared
groups. Results include name, library_id, library_type, is_default, and
key_permissions. Group results are paginated with limit and start; follow
next_start until it is null. Discovery also works when the default is a group.
Every other tool accepts optional library_id and library_type arguments:
Pass both arguments to select a library, or omit both. Use IDs returned by
list_libraries, rather than group names. Selection applies to one call and never
changes the environment or another client's target, including concurrent calls.
Item and collection keys must come from the selected library. Zotero enforces the
API key's permissions and the user's group rights; a denied group request fails
without falling back to the personal library. health_check accepts the same
arguments to verify a specific library without writing to it.
Group attachments use Zotero's built-in storage. WebDAV is used only for the configured personal library, even when the same server accesses shared groups.
| Variable | Required | Description |
|---|---|---|
ZOTERO_LIBRARY_ID | Yes | Default Zotero user or group library ID |
ZOTERO_API_KEY | Yes | API key with read/write permissions |
ZOTERO_LIBRARY_TYPE | No | Default library type: user (default) or group |
CROSSREF_MAILTO | No | Your email for CrossRef polite pool (faster API access) |
UNPAYWALL_EMAIL | No | Contact email for open-access PDF lookup (defaults to CROSSREF_MAILTO) |
ZOTERO_WEBDAV_URL | No | WebDAV URL for file storage (e.g. https://dav.example.com) |
ZOTERO_WEBDAV_USER | No | WebDAV username |
ZOTERO_WEBDAV_PASSWORD | No | WebDAV password |
ZOTERO_MCP_OAUTH_ISSUER | No | External OAuth/OIDC issuer URL for protected HTTP deployments |
ZOTERO_MCP_OAUTH_RESOURCE | No | Canonical HTTPS MCP resource/audience URL |
ZOTERO_MCP_OAUTH_JWKS_URL | No | JWKS URL used to verify JWT access tokens |
ZOTERO_MCP_OAUTH_SCOPES | No | Comma-separated required scopes (defaults to read and write) |
ZOTERO_MCP_FILE_ROOTS | No | Comma-separated allowed roots when HTTP server paths are enabled |
Note: If all three
ZOTERO_WEBDAV_*variables are set, attachments in the configured personal library use WebDAV instead of Zotero's built-in storage. Group attachments always use Zotero storage. The server automatically appends/zoteroto the WebDAV base URL, matching Zotero Desktop's behavior.
list_libraries.library_id and library_type;
existing calls keep the configured default.Restart the MCP connection after upgrading to load the new tool schemas.
Two path-writing operations were split from their read-only counterparts so remote clients can apply correct safety approvals:
get_bibtex(save_path=...) is now save_bibtex(save_path=...); get_bibtex only returns data.download_pdf(save_path=...) is now save_pdf(save_path=...); download_pdf returns an opaque MCP resource link.Existing read-only calls to get_bibtex and download_pdf continue to work.
health_check reports API-key write permission without modifying the library.MIT
mcp-name: io.github.RaulSimpetru/zotero-library-mcp