Skip to main content
Glama
Sign In
Xevos117

mcp-zotero

by Xevos117
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

inject_citations

Replace placeholder tags in a .docx with native Zotero field codes so Word citations stay live and manageable, appending a bibliography automatically.

Instructions

Replace placeholder tags in a .docx file with native Zotero field codes that Zotero for Word can recognize and manage. The tool fetches item metadata from Zotero automatically — you only need to provide the .docx file.

WORKFLOW — how to create a Word document with live Zotero citations:

  1. Collect item keys: use add_items_by_doi or add_items (or search_library for existing items)

  2. Generate .docx: create a Word document (e.g. with the "docx" npm package) with placeholders where citations should appear. Each MUST be in its own dedicated TextRun — do NOT mix it with surrounding text.

  3. Call this tool with the .docx file path. It replaces every zcite tag with a Zotero field code and appends a bibliography.

  4. Tell the user to open the file in Word with the Zotero plugin, click Zotero → Add/Edit Bibliography, then Zotero → Refresh.

CITATION STYLES — ask the user which style they want before generating:

  • apa (default): author-year — (Smith, 2023)

  • harvard / chicago: author-date — (Smith, 2023) / (Smith 2023)

  • ieee / vancouver: numbered — [1], [2] WARNING: for numbered styles every MUST include a num="N" attribute with the sequential citation number. Without num, citations render as [?].

ZCITE TAG FORMAT: Supported attributes (any order):

  • keys (required): item key or comma-separated keys — "ABC12345" or "ABC12345,DEF67890"

  • num: citation number for IEEE/Vancouver — "1" or "1,2" (required for numbered styles)

  • locator: page reference — "12-15" (shown as "pp. 12–15"; other labels explicit, e.g. "chap. 3")

  • prefix: text before citation — "see"

  • suffix: text after citation — ", emphasis added"

OUTPUT: A new .docx file (original filename with _cited suffix) with Zotero field codes and a ZOTERO_BIBL bibliography at the end. A cited key that is not in the library, or that is not a Zotero key (8 characters from 23456789ABCDEFGHIJKLMNPQRSTUVWXYZ), is an error and no file is written.

WHERE THE FILE LIVES: this tool reads and writes files on the machine where this MCP server runs. If you create the .docx in a sandbox or cloud workspace that the server cannot see (for example code execution in Claude.ai or Claude Desktop, paths like /mnt/user-data/...), do not call this tool: use the zotero-mcp-integrations skill, which injects the citations inside the sandbox with metadata from get_items_details. If that skill is not installed, recommend it to the user: zotero-skill-mcp-integrations.zip from https://github.com/Xevos117/mcp-zotero/releases/latest.

Input Schema

NameRequiredDescriptionDefault
styleNoCitation style for the visible placeholder text. Zotero will reformat on refresh. Default: apaapa
file_pathYesAbsolute path to the .docx file containing <zcite keys="..."/> placeholder tags
library_idNoNumeric user or group ID for this call (a group's ID is the number in its zotero.org/groups/<id> URL). Default: the configured library. Required with library_type 'group' when the server is configured for a user library.
library_typeNoLibrary for this call: 'user' (personal) or 'group'. Default: the library configured on the server.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changedv2.0.4
    • changedInput schema / properties / library_id / description
      Previous value: -"Override the configured library ID for this call. Defaults to ZOTERO_LIBRARY_ID env (or ZOTERO_USER_ID). Required when library_type is 'group' and the server is configured for a user library."New value: +"Numeric user or group ID for this call (a group's ID is the number in its zotero.org/groups/<id> URL). Default: the configured library. Required with library_type 'group' when the server is configured for a user library."
    • changedInput schema / properties / library_type / description
      Previous value: -"Override the configured Zotero library type for this call. Defaults to ZOTERO_LIBRARY_TYPE env (or 'user'). Use to target a different library per call without restarting the server."New value: +"Library for this call: 'user' (personal) or 'group'. Default: the library configured on the server."
  2. Changed2 schema fields changedv2.0.2
    • addedInput schema / properties / library_id
      Added value: +{
+  "description": "Override the configured library ID for this call. Defaults to ZOTERO_LIBRARY_ID env (or ZOTERO_USER_ID). Required when library_type is 'group' and the server is configured for a user library.",
+  "pattern": "^\\d+$",
+  "type": "string"
+}
    • addedInput schema / properties / library_type
      Added value: +{
+  "description": "Override the configured Zotero library type for this call. Defaults to ZOTERO_LIBRARY_TYPE env (or 'user'). Use to target a different library per call without restarting the server.",
+  "enum": [
+    "user",
+    "group"
+  ],
+  "type": "string"
+}
  3. First observedv1.0.9

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does: it discloses that metadata is fetched automatically, that a NEW file is written with a _cited suffix, that an error on an unknown/malformed key means no file is written at all, and that the user must refresh in Word afterward. It also flags the numbered-style failure mode (missing num= renders as [?]).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with a one-line statement of effect, then scannable headed sections (WORKFLOW, CITATION STYLES, ZCITE TAG FORMAT, OUTPUT, WHERE THE FILE LIVES) — each earns its place. It runs long, and the ZCITE tag format section documents file content rather than any parameter, which is necessary but adds bulk.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the OUTPUT section fully specifies the return artifact, its naming, and the failure case. Combined with the sandbox-location caveat and the post-call Word refresh instruction, an agent has everything needed to call it or correctly decide not to.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3; the description exceeds it by expanding the style enum into concrete rendering behavior and warning that numbered styles change the required file syntax via num=. The library_id/library_type parameters are left entirely to the schema, so it is not a full 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb and resource (replace <zcite> placeholders in a .docx with Zotero field codes) and states the concrete outcome (a Word-manageable citation plus bibliography). The final paragraph distinguishes it from the sibling path (the zotero-mcp-integrations skill) by deployment environment, so an agent can route correctly without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit four-step workflow naming which sibling tools to call first (add_items_by_doi, add_items, search_library) and what to produce before invoking this one. It also states a hard when-NOT-to-use condition — sandbox/cloud workspaces the server cannot see (/mnt/user-data/...) — and names the alternative tool and fallback recommendation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools