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).

Related MCP server: zotero-grounded-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-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}):

MCP Tools

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

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").