Building a Zotero AI plugin with a built-in Zotero MCP server — and making every LLM citation clickable back to the exact PDF passage

Rui Bai — Sat, 31 Oct 2026 14:57:03 +0000

Disclosure: we're the team of researchers behind BibGenie, the Zotero plugin described here. This post is about the engineering, not a product tour — including the parts that don't work as well as we'd like.

We built BibGenie because we kept hitting the same wall with the new wave of Zotero AI tools: the answer reads fine, but checking it costs more time than reading the paper would have. Two design problems came out of that frustration, and they turned out to be the same problem — an AI that works on your library should be inspectable:

Its claims should be one click away from the evidence.
Its access to your library should be a protocol you control, not a black box.

The first led us to text-block citations. The second led us to ship an MCP server inside the plugin. Here's how both work.

Part 1: A Zotero MCP server that lives inside the plugin

Most Zotero MCP setups you'll find are separate Python services that talk to Zotero's local API. That works, but it means users install and babysit a second runtime, keep it version-matched, and debug two programs when something breaks. We wanted the server to be a feature of the plugin, not a sidecar.

BibGenie's MCP server runs inside the Zotero plugin, on top of Zotero's own local HTTP server, using Streamable HTTP:

http://127.0.0.1:23119/bibgenie/mcp

(The port follows your Zotero HTTP server config — the settings panel shows the exact URL to copy, and there's a built-in Test Connection button, because opening the URL in a browser sends a GET and tells you nothing. MCP clients speak POST + JSON-RPC.)

Clients that support Streamable HTTP connect directly. Cursor:

{
  "mcpServers": {
    "ZoteroBibGenie": {
      "url": "http://127.0.0.1:23119/bibgenie/mcp"
    }
  }
}

Claude Code:

claude mcp add ZoteroBibGenie --transport http http://127.0.0.1:23119/bibgenie/mcp

One wrinkle worth knowing: some Claude Desktop builds are happier with stdio servers than local HTTP endpoints, so for Claude Desktop we point users at mcp-remote as a small bridge. Not elegant, but honest — and it works today.

The tool surface

We kept the tools close to what researchers actually do in Zotero, rather than exposing a generic database API:

Item search by title, author, publication, keyword, or topic
Semantic search over the library (more on what that index contains below)
PDF reading — text extraction from attachments, plus visual reading that renders pages as images when figures, tables, or scanned pages need eyes, not a text layer
Notes and snapshots — read Zotero notes and saved web snapshots
Tags and collections — list, create, and manage
Metadata access and review — including a read-only review_metadata tool that aggregates facts from arXiv, Semantic Scholar, OpenAlex, DBLP, and OpenReview with rule-based diagnostics, so an external agent can audit a record before touching it
Controlled writes — create notes, and validate/apply metadata edits through edit_metadata

The uncomfortable part: write access

Read tools are easy to feel good about. Write tools are where we spent the arguments.

Inside BibGenie's own chat, any proposed library change is shown as a preview/diff first and only written after the user approves. External MCP clients, however, have their own permission models — and they don't necessarily show the same approval cards before writing to your library. We can't fix another client's UX from inside our server, so the documentation is blunt about it: check your client's approval settings before letting it edit your library, only share the server URL with clients you trust, and turn the server off when you're not using it (it's off by default; you enable it explicitly in settings).

There's a second leak to be honest about: the MCP connection is local, but the client may send whatever it retrieved to its own model provider. "Local server" does not mean "nothing leaves the machine" once an external agent is in the loop. We say this in the docs, in roughly these words, because users consistently assume otherwise.

Part 2: Citations that carry their own coordinates

The second half of "inspectable" is the citation itself. A citation that names a paper is almost useless for verification — the paper is 14 pages. A citation that names a page is better. What you actually want is: click, land on the passage, see it highlighted, read the surrounding paragraph.

So in BibGenie, a citation isn't a string. It's a reference plus location information, and we think in three levels:

Level	What it identifies
Work	Which paper or source was used
Page	Which page the evidence is on
Passage / text block	The relevant part of the source, with a jump and highlight when its position resolves

The source type determines what "location" can mean:

PDF text — opens the cited page; when valid text-position data exists, it also locates and highlights the relevant text block
PDF page image — returns to the source page (an exact figure or table region is not necessarily highlighted — anyone who tells you otherwise hasn't shipped this)
EPUB — returns to the relevant section or text location, with a temporary highlight when the passage resolves
Web snapshot — opens the saved snapshot and locates/highlights the passage
Existing annotation — navigates to the annotation you already made
Note — opens the source note

The highlight is temporary, by design: following a citation is a reading act, not an editing act. It doesn't silently create annotations in your library.

Design for degradation, not for the demo

The most important engineering decision here was what to do when the coordinates don't resolve — because with real-world PDFs, they often don't. Scanned PDFs, poor text extraction, unusual EPUB structures, and messy snapshot markup all limit positioning.

Our rule: fall back a level, never fake precision. If the text block can't be resolved, the citation opens the document at the page or section. If that fails, it opens the document. A citation that confidently jumps to the wrong paragraph is worse than one that honestly opens the right paper, because the wrong jump manufactures trust.

The same honesty applies one level up. A real source does not guarantee a correct interpretation — a model can cite a genuine passage and still summarize it wrong, merge two findings, or drop the qualification that came one sentence later. Traceable citations don't solve that. What they change is the cost of catching it: verification goes from "re-read the paper" to "read the paragraph and its neighbours," which is the difference between checking every claim and checking none. We're also careful to keep the author's statements, an annotator's comments, and the AI's interpretation distinguishable — a comment attached to a passage is not part of the paper.

One more boundary we keep: chat citations are for reading and research notes. For a manuscript, you cite the original work through Zotero's normal citation workflow in your required style. A highlighted text block is evidence, not a bibliography entry.

Part 3: What "local-first" actually commits you to

Both features above only make sense because of where the data lives:

Chat history is stored in the user's local Zotero database.
The semantic index is built locally, over titles, abstracts, and metadata — notably not a cloud index of your PDF full text.
Bring-your-own-key requests go from the user's machine directly to their chosen provider.
With local chat and embedding models (Ollama / LM Studio), the whole loop can run without leaving the machine.

The hosted route exists too (that's how most users start), but the architecture treats it as the exception, not the default — and the MCP/citation design doesn't change depending on which route you use, because both run against the same local library.

What we'd tell another team building this

Ship the server inside the host app if you can. Every external runtime you ask researchers to install halves your audience and doubles your support matrix.
Make citations data, not decoration. If the location isn't captured when the answer is generated, you can't retrofit it.
Degrade honestly. Fall back a level instead of pretending precision you don't have — in tooling for researchers, manufactured confidence is the one unforgivable bug.
Treat write access as a separate product decision. Read tools, review tools, and write tools deserve different defaults, different warnings, and different levels of user friction.
Say the quiet part in the docs. Local server ≠ nothing leaves the machine; real source ≠ correct interpretation. Users forgive limitations. They don't forgive discovering them.

If you're building MCP tooling for reference managers — or for any personal knowledge base, really — we'd genuinely like to compare notes. The interesting problems (position resolution across formats, write-safety for external agents, what an index should and shouldn't contain) are nowhere near solved.

BibGenie works with Zotero 7–10 on macOS, Windows, and Linux. Docs: MCP server · Traceable citations

DEV Community: Rui Bai