zotero-mcp

Antigravity plugin that adds an MCP server connected to your local Zotero library 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-mcp

What 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_cite and the document's references section regenerates with zotero_bibliography.
• Verify sources: never invents references; every item is validated against Zotero before citing.
• Diagnostics: zotero_status tells you whether Zotero is available.

Limits (v1): read-only access to the Zotero library (cannot add/edit/delete items).

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-mcp

If 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.sh

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_API_URL	http://127.0.0.1:23119/api	Zotero local API URL
ZOTERO_DEFAULT_STYLE	apa	Default CSL style
ZOTERO_LOCALE	es-ES	Default style locale

MCP Tools

Tool	Description
zotero_status	Check connection to the local API.
zotero_search	Search items (query, qmode, itemType, collectionKey, limit, sort, direction).
zotero_get_item	Full item details by key.
zotero_list_collections	List collections.
zotero_cite	Textual citation (key, style, locale, locator, label, prefix, suffix, register).
zotero_bibliography	Bibliography from registered citations or explicit keys; with filePath + apply: true updates the references section of a .md file.
zotero_read_docx	Read paragraphs from a .docx (index, text, whether it already has Zotero fields).
zotero_insert_citation_docx	Insert an ADDIN ZOTERO_ITEM CSL_CITATION field at the end of a paragraph in a .docx.
zotero_update_bibliography_docx	Insert or update the ADDIN ZOTERO_BIBL field in a .docx.

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 (with diff preview):

{ "tool": "zotero_bibliography", "args": { "filePath": "C:/docs/paper.md", "dryRun": true } }

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 ## Bibliography). Output formats: plaintext, markdown (default), html.

Complete typical flow

1. zotero_search { "query": "artificial intelligence" } → get the item's key.
2. zotero_cite { "key": "ABC12345", "style": "apa" } → insert (Author, 2020) in the text.
3. zotero_bibliography { "filePath": "C:/docs/paper.md", "apply": true } → regenerate the ## Bibliography (or References, 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 (dryRun mode returns 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", "paragraphIndex": 0, "style": "apa", "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. When the .docx is opened in Word with the Zotero plugin, the citation renders correctly and the bibliography updates automatically.

Typical Word flow

1. zotero_read_docx → learn the structure (paragraphs and their indices).
2. For each citation: zotero_insert_citation_docx at the correct paragraph.
3. zotero_update_bibliography_docx → adds/updates the BIBL field at the end.

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 styles or locales, place the file in src/csl/ or src/locales/ with the correct name.

Security

• Read-only access to the Zotero library: the MCP does not add, edit or delete items.
• 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.
• Parameter validation, connection timeout (8 s) and file size limit (2 MB).

Troubleshooting

Symptom	Cause	Solution
zotero_status → ok: false	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.
zotero_cite → "Item not found with key..."	Wrong key or deleted item	Search again with zotero_search and copy the exact key.
zotero_bibliography → "Unsupported style"	Style not included	Use one of: apa, mla, chicago-author-date, harvard-cite-them-right, ieee, vancouver (or add the .csl file to src/csl/).
"No references section found"	Document has no bibliography heading	Pass createSection: true to create it at the end.
"filePath must be a .md file..."	.docx or other extension was passed	v1 only updates Markdown (.md/.markdown).
Numeric citations "reset"	Style changed mid-document	Use the same style/locale throughout the document (changing style resets numbering).

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 Zotero

The structure follows the complete Antigravity plugin pattern (plugin.json, mcp_config.json, server/ → src/, skills/, scripts/).

License

MIT — see LICENSE. CSL styles and locales are CC-BY-SA 3.0 (see "Included styles and locales").