zotero-mcp
Provides tools to search a local Zotero library, retrieve item details, generate citations in multiple CSL styles and locales, and maintain bibliographies in Markdown or Word documents.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zotero-mcp
MCP server connected to your local Zotero library, packaged as an Antigravity plugin and usable from any MCP client (other clients), to:
Search items in your library (by text, type and collection).
Cite with CSL styles: APA, MLA, Chicago (author-date), Harvard, IEEE and Vancouver.
Auto-update bibliographies: add a new citation and the document's references section regenerates automatically.
Installable from GitHub with:
agy plugin install https://github.com/Robernetes/zotero-mcpWhat can the AI do with this MCP?
Answer questions about your library: search for sources on a topic, filter by type (articles, books, theses) or collection, and get full details of any item (abstract, authors, year, URL, DOI).
Cite correctly: generate in-text citations with the right style (APA, MLA, Chicago, Harvard, IEEE, Vancouver) and language (es-ES, en-US), with page locators (
(Author, 2020, p. 15)), prefixes and suffixes.Write academic documents with real references: the AI inserts citations and keeps the bibliography synced: add citations with
zotero_citeand the document's references section regenerates withzotero_bibliography.Find new sources: search outside your library (OpenAlex and Crossref) by topic, title, author or DOI, see which results are already in your library, and save the ones you choose (by DOI) into a collection.
Verify sources: never invents references; every item is validated against Zotero before citing.
Diagnostics:
zotero_statustells you whether Zotero is available.
Limits: the MCP can only add new items (zotero_add_item, Zotero must be open); it never edits or deletes existing items. It saves metadata only (no PDFs).
Related MCP server: zotero-mcp
Requirements
Zotero installed and open, with the setting "Allow other applications on this computer to communicate with Zotero" enabled (Edit → Settings → Advanced). The server uses the local API (port 23119), no API key needed.
Node.js ≥ 18 (tested with Node 24).
Installation
agy plugin install https://github.com/Robernetes/zotero-mcpIf the plugin doesn't run dependency installation automatically:
git clone https://github.com/Robernetes/zotero-mcp
cd zotero-mcp
npm install # or: powershell -File scripts/setup.ps1 / sh scripts/setup.shUse with other MCP clients
The server is a standard MCP server (stdio), so it works with any MCP client, not only Antigravity: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI… Only plugin.json and mcp_config.json are specific to the Antigravity plugin.
Clone the repository and install the dependencies (see Installation).
Register the server in your client with
nodeand the absolute path tosrc/server.js. On Windows you can write the path with/to avoid escaping\\in JSON.Pass the variables you need in
env(see Configuration). Write real values:${VAR}placeholders like the ones inmcp_config.jsononly work in clients that expand environment variables (if one arrives unexpanded, the server ignores it and uses the default).Restart the client and run
zotero_status:ok: trueconfirms the connection with Zotero, andworkspaceshows the folders where documents can be read and written. Ifsourceis the server start folder, the client does not report its working folders (roots): setZOTERO_MCP_ALLOWED_DIRSwith the folders of your documents.
Claude Code (--scope user makes it available in all your projects):
claude mcp add zotero --scope user -e ZOTERO_LOCALE=es-ES -- node C:/path/to/zotero-mcp/src/server.jsTo also use the zotero-research skill, copy the skills/zotero-research folder to ~/.claude/skills/ (or to .claude/skills/ in a project).
Claude Desktop, Cursor, Windsurf, Gemini CLI and most clients use an mcpServers block:
{
"mcpServers": {
"zotero": {
"command": "node",
"args": ["C:/path/to/zotero-mcp/src/server.js"],
"env": {
"ZOTERO_DEFAULT_STYLE": "apa",
"ZOTERO_LOCALE": "es-ES",
"ZOTERO_MCP_ALLOWED_DIRS": "C:/Users/you/Documents/Thesis"
}
}
}
}Client | Configuration file |
Claude Desktop |
|
Cursor |
|
Windsurf |
|
Gemini CLI |
|
ZOTERO_MCP_ALLOWED_DIRS is especially useful in clients without a project folder, such as Claude Desktop.
VS Code (.vscode/mcp.json in the project) uses the servers key and the stdio type:
{
"servers": {
"zotero": {
"type": "stdio",
"command": "node",
"args": ["C:/path/to/zotero-mcp/src/server.js"],
"env": { "ZOTERO_LOCALE": "es-ES" }
}
}
}Configuration
The server works out of the box (default values). Optional variables
(defined in .env.example; passed to the server via mcp_config.json with ${VAR}):
Variable | Default | Description |
|
| Zotero local API URL |
|
| Default CSL style |
|
| Default style locale |
|
| Copy the document to |
| (empty) | Free OpenAlex API key for |
| (empty) | Contact email sent to OpenAlex and Crossref (their "polite pool": faster, more stable responses). Nothing is sent if empty |
| (empty) | Folders where |
Writes to .md/.docx files are atomic (temporary file in the same folder + rename), are refused if the file changed on disk since it was read, and are serialized per file, so parallel calls do not overwrite each other. The .bak keeps only the previous version.
Documents are only read and written inside the allowed folders: those in ZOTERO_MCP_ALLOWED_DIRS; if it is not set, the working folders the MCP client reports (roots, usually the open project); and if the client reports none, the folder the server was started from. Relative paths are resolved from the first allowed folder, and links (symlinks/junctions) pointing outside are rejected. zotero_status shows the allowed folders in workspace; if source is the server start folder, your client does not report roots and you need ZOTERO_MCP_ALLOWED_DIRS to work with documents elsewhere.
MCP Tools
Tool | Description |
| Check connection to the local API. |
| Search items ( |
| Full item details by |
| List collections ( |
| Textual citation ( |
| Bibliography from registered citations or explicit |
| Read paragraphs from a |
| Insert an |
| Remove Zotero citations from a |
| Insert or update the |
| Search publications outside the library in OpenAlex/Crossref ( |
| Save a publication to the library by |
Usage examples (JSON)
Examples use placeholder Zotero keys (ABC12345, DEF67890); replace with real keys
from zotero_search output.
1. Check connection
{ "tool": "zotero_status" }{ "ok": true, "baseUrl": "http://127.0.0.1:23119/api", "library": "local (users/0)" }2. Search items
{ "tool": "zotero_search", "args": { "query": "artificial intelligence", "limit": 10 } }Additional filters: itemType (journalArticle, book, thesis, conferencePaper…),
collectionKey (from zotero_list_collections), sort/direction. Empty query = list all.
3. Item details
{ "tool": "zotero_get_item", "args": { "key": "ABC12345" } }4. List collections
{ "tool": "zotero_list_collections" }5. Cite
{ "tool": "zotero_cite", "args": { "key": "ABC12345", "style": "apa", "locale": "en-US" } }→ (Author, 2020)
With exact page:
{ "tool": "zotero_cite", "args": { "key": "ABC12345", "style": "apa", "locator": "15", "label": "page" } }→ (Author, 2020, p. 15)
With prefix/suffix:
{ "tool": "zotero_cite", "args": { "key": "ABC12345", "style": "apa", "prefix": "see ", "suffix": ", for a full analysis" } }With register: false the citation is generated but not added to the bibliography.
6. Bibliography (auto-updating)
From registered citations (recommended):
{ "tool": "zotero_bibliography", "args": { "style": "apa", "locale": "en-US" } }From explicit keys (without affecting the register):
{ "tool": "zotero_bibliography", "args": { "keys": ["ABC12345", "DEF67890"], "style": "ieee" } }Update the references section of a Markdown document (without apply it only returns the diff preview):
{ "tool": "zotero_bibliography", "args": { "filePath": "C:/docs/paper.md" } }Write the file:
{ "tool": "zotero_bibliography", "args": { "filePath": "C:/docs/paper.md", "apply": true } }If the document has no references section, create it at the end with createSection: true
(uses the heading ## Bibliografía). Output formats: plaintext, markdown (default), html.
Complete typical flow
zotero_search { "query": "artificial intelligence" }→ get the item'skey.zotero_cite { "key": "ABC12345", "style": "apa" }→ insert(Author, 2020)in the text.zotero_bibliography { "filePath": "C:/docs/paper.md", "apply": true }→ regenerate the## Bibliography(orReferences,Works Cited, etc.) section with all registered citations.
The bibliography stays updated automatically: just add a citation with zotero_cite and call
zotero_bibliography again. To review before writing, omit apply: the response has dryRun: true and the diff.
7. Read a Word document structure
{ "tool": "zotero_read_docx", "args": { "filePath": "C:/docs/paper.docx" } }→ { paragraphs: [{ index: 0, text: "Lorem ipsum...", hasZoteroField: false }, ...] }
8. Insert a citation in Word (dynamic Zotero field)
{ "tool": "zotero_insert_citation_docx", "args": { "filePath": "C:/docs/paper.docx", "key": "ABC12345", "afterText": "the process of analyzing a subject system", "style": "apa", "apply": true } }afterText is an exact fragment of the text returned by zotero_read_docx (repeated spaces, typographic quotes and dashes are ignored); it must appear only once, and paragraphIndex narrows the search. Without afterText the citation goes at the end of paragraphIndex. Either way it is placed before the punctuation that closes the sentence and separated by a space, as in academic writing: …a subject system (Chikofsky & Cross, 1990). The response includes preview with the surrounding text, so you can check it before writing with apply: true.
Several sources supporting the same statement, in a single grouped citation (Costin et al., 2016; Pang et al., 2021):
{ "tool": "zotero_insert_citation_docx", "args": { "filePath": "C:/docs/paper.docx", "keys": ["ABC12345", "DEF67890"], "afterText": "binaries and embedded firmware", "apply": true } }With locator:
{ "tool": "zotero_insert_citation_docx", "args": { "filePath": "C:/docs/paper.docx", "key": "ABC12345", "paragraphIndex": 2, "locator": "15", "label": "page", "apply": true } }9. Update bibliography in Word
{ "tool": "zotero_update_bibliography_docx", "args": { "filePath": "C:/docs/paper.docx", "style": "apa", "apply": true } }The citation is inserted as an ADDIN ZOTERO_ITEM CSL_CITATION field with the item's CSL JSON, in the same format the Zotero Word plugin writes (the item's real library URI, random citationID, noteIndex 0), so pressing Refresh in Word links it to the item in your library.
style and locale are optional: if the document already has Zotero document preferences, its style and locale are used. If it has none, they are created (docProps/custom.xml, ZOTERO_PREF_n) with the style and locale used, so Word does not ask for a style on Refresh. Existing preferences are never modified; if you pass a different style, the response includes a warning because Zotero will use the document's style when refreshing.
Typical Word flow
zotero_read_docx→ learn the structure (paragraphs and their indices).For each statement that needs a source:
zotero_insert_citation_docxwithafterText(andkeyswhen several sources support it).zotero_update_bibliography_docx→ adds/updates the BIBL field at the end.
To redo citations, remove them with zotero_remove_citations_docx instead of editing or regenerating the file: text, formatting and styles stay as they were, and the space before each citation is removed too.
{ "tool": "zotero_remove_citations_docx", "args": { "filePath": "C:/docs/paper.docx", "keys": ["ABC12345"], "apply": true } }With keys only those sources are removed (in a grouped citation, the other sources stay and its text is recalculated); without keys every citation and the bibliography are removed. Without apply it shows how the paragraphs would look.
10. Search outside your library
{ "tool": "zotero_find_external", "args": { "query": "older adults technology adoption", "yearFrom": 2018, "limit": 5 } }
{ "tool": "zotero_find_external", "args": { "doi": "10.1017/S0144686X19000230", "includeAbstract": true } }Each result includes title, authors, year, type, venue, publisher, doi, url, openAccessUrl, citedBy and inLibrary ({ key, title, collections } if the item is already in Zotero, matched by DOI or exact title; null otherwise). With source: "auto" (default) it uses OpenAlex and falls back to Crossref if OpenAlex fails; a DOI is looked up in Crossref and then OpenAlex. Nothing is saved to Zotero.
11. Save to your library
{ "tool": "zotero_add_item", "args": { "doi": "10.1017/S0144686X19000230", "collectionKey": "2HTJ2CWF", "tags": ["thesis"] } }
{ "tool": "zotero_add_item", "args": { "doi": "10.1017/S0144686X19000230", "collectionKey": "2HTJ2CWF", "tags": ["thesis"], "apply": true } }Without apply: true it returns a preview: the metadata that will be saved, the destination collection and whether the item is already in the library. With apply: true it saves it and returns its key, ready for zotero_cite. Metadata comes from Crossref (or OpenAlex for DOIs Crossref does not have, and for openAlexId) and is imported by Zotero's own CSL JSON translator through the connector server (/connector/import, the same local server the browser extension uses). Without collectionKey the item goes to the collection currently selected in Zotero. Saving selects the destination collection and the new item in the Zotero window. If the item already exists (same DOI or title) nothing is saved and its key is returned. The connector is an internal Zotero interface, tested with Zotero 9.
Included skill
zotero-research teaches the agent when and how to use each tool (search, citation and
bibliography maintenance). It activates automatically when the user asks to search, cite or update bibliographies.
Included styles and locales
CSL styles (CC-BY-SA 3.0 from the citation-style-language/styles project):
apa,mla,chicago-author-date,harvard-cite-them-right,ieee,vancouver.Locales (CC-BY-SA 3.0 from citation-style-language/locales):
es-ES,en-US.
To add a style, copy its .csl file to src/csl/ (the file name, without .csl, is the style name); to add a locale, copy locales-<code>.xml to src/locales/. Restart the MCP client to load them. If the requested locale is not available, one of the same language is used (es-MX → es-ES) and, failing that, en-US.
Security
The only change to the Zotero library is adding new items with
zotero_add_itemand explicitapply: true; existing items are never edited or deleted.zotero_find_externalonly sends the search text or DOI to OpenAlex/Crossref (plusOPENALEX_API_KEYandZOTERO_MCP_CONTACT_EMAILif you set them); never the content of your documents or library.The only write operations are the references section of Markdown files and Zotero fields in Word files (.docx), and only with explicit
apply: true.No secrets in the repository; credentials (if any) go through environment variables.
Documents are only read and written inside the allowed folders (
ZOTERO_MCP_ALLOWED_DIRS, the client's roots or the server start folder).Parameter validation, timeouts (8 s for the local API, 15 s for OpenAlex/Crossref, 20 s for saving) and file size limit (2 MB).
Troubleshooting
Symptom | Cause | Solution |
| Zotero closed or local API disabled | Open Zotero and enable "Allow other applications on this computer to communicate with Zotero" (Edit → Settings → Advanced). No restart required. |
| Wrong key or deleted item | Search again with |
| Style not included | Use one of: |
"No references section found" | Document has no bibliography heading | Pass |
"filePath must be a .md file..." |
|
|
"Could not write/read ...: the file is open or locked by another application" | The document is open in Word (or locked by another program) | Close it and run the tool again; the original is not modified. |
"The file changed since it was read" | The document was edited or saved while the tool was running | Run the tool again so it works on the latest version. |
"No references to write: the citation registry is empty" | The in-memory registry was lost (server restart or style/locale change) | Cite again with |
"The new bibliography has N references and the current section M" | The new list is shorter than the existing one (partial registry) | Review the |
| The shared OpenAlex quota for your IP ran out | With |
"... is outside the allowed folders" | The document is not in the working folder (or your client does not report roots) | Check |
| Zotero is closed | Open Zotero: saving requires the desktop app. |
| Two collections with the same name and parent | Rename one in Zotero, or save without |
Numeric citations "reset" | Style changed mid-document | Use the same |
Development
npm test # test suite (node --test)
npm start # start the MCP server via stdio
node scripts/smoke.mjs # MCP handshake + list registered tools
node scripts/e2e.mjs '{"tool":"zotero_status"}' '{"tool":"zotero_search","args":{"query":"x"}}' # test tools against your ZoteroRun e2e.mjs from Git Bash or PowerShell 7 (pwsh): Windows PowerShell 5.1 strips the quotes from the JSON. Calls with apply: true are rejected unless you add --allow-write, because they write to your library or your documents.
CI (GitHub Actions, .github/workflows/ci.yml) runs on every push to main and every pull request: the test suite and the MCP smoke test on Node 18, 20, 22 and 24 (Linux) and Node 22 (Windows), plus npm audit, which fails on high or critical vulnerabilities. Tests do not need Zotero: they use mocked responses.
The structure follows the complete Antigravity plugin pattern
(plugin.json, mcp_config.json, server/ → src/, skills/, scripts/).
In src/: server.js is the entry point (stdio), app.js builds the MCP server, context.js reads the configuration and creates the clients, and tools/ registers the tools by area: library.js (search and collections), citations.js (citations and Markdown), word.js (.docx) and external.js (external search and saving to the library). The Zotero clients (zotero-client.js, zotero-connector.js, external-search.js) and the document logic (cite.js, docx.js, bib-section.js, file-io.js) do not depend on MCP. tests/server.test.js tests the full server in memory with mocked clients.
License
MIT — see LICENSE. CSL styles and locales are CC-BY-SA 3.0 (see "Included styles and locales").
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
KnowMan MCP server: search, ask, save and read your Knowledge Base from any MCP client.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that gives any MCP-compatible assistant access to your Zotero reference library, enabling search, citation, bibliography generation, and .docx processing while keeping Zotero as the ground truth for references.91MIT
- AlicenseAqualityBmaintenanceMCP server that lets AI assistants search, create, organize, and cite from a Zotero library.394MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that connects AI assistants to your Zotero library, enabling full-text PDF extraction and metadata search.MIT
- FlicenseNot gradedqualityCmaintenanceMCP server for interacting with a Zotero library via the local API. Enables searching, retrieving, creating, updating, and deleting Zotero items, managing collections and tags, and generating citations.-