• Home
/
• LLM for Zotero Documentation
• Edit on GitHub

LLM-for-Zotero

📖 中文版使用手册

llm-for-zotero is a plugin for Zotero that integrates Large Language Models directly into the Zotero PDF reader. Unlike tools that require uploading PDFs to a web portal, this plugin lets you chat with your papers without leaving Zotero. It sits quietly in the reader sidebar, ready whenever you need it.

Recent Updates

• Skills: Customizable guidance files that shape how the agent handles different tasks. 9 built-in skills included, plus a portal for creating your own. See Skills.
• Standalone Window Mode: Open the LLM Assistant in its own dedicated window, separate from the reader sidebar. See Standalone Window Mode.
• Obsidian Integration: Write notes from Zotero papers directly to your Obsidian vault with customizable templates. See Obsidian Integration.
• Agent Mode (Beta): LLM-for-Zotero can now act as an autonomous agent inside your Zotero library.
• Terminal & File Access: The agent can execute shell commands and read/write files on your local machine — like a coding agent inside Zotero.
• MCP Server: External AI agents can connect to Zotero via the built-in Model Context Protocol server.
• Codex auth: ChatGPT Plus subscribers can use Codex models such as gpt-5.4 without a separate API key.
• MinerU PDF parsing: High-fidelity extraction now preserves tables, equations, and figures more accurately.

Installation

1. Download the latest .xpi release Go to the Releases Page and download the latest .xpi file.

2. Install the add-on in Zotero Open Zotero → Tools → Add-ons → click the gear icon → Install Add-on From File → select the .xpi file.

3. Restart Zotero Restart Zotero to complete the installation. The plugin automatically checks for future updates on startup.

Configuration

Open Preferences → navigate to the llm-for-zotero tab.

1. Select your Provider (e.g. OpenAI, Gemini, DeepSeek).
2. Paste your API Base URL, secret key, and model name.
3. Click Test Connection to verify.

The plugin natively supports multiple provider protocols: responses_api, openai_chat_compat, anthropic_messages, gemini_native, and more.

Supported Models (Examples)

You can also set up multiple providers, each with multiple models for different tasks, such as a multimodal model for figures and a text model for summaries. Cross-check answers across models when you want broader coverage.

Advanced: Reasoning Levels & Hyperparameters

You can set different reasoning levels per model in the conversation panel, such as default, low, medium, high, and xhigh, depending on model support. You can also adjust hyperparameters like temperature and max_tokens_output for more creative or more deterministic responses.

Usage Guide

1. Open any PDF in the Zotero reader.
2. Click the LLM Assistant icon in the right-hand toolbar to open the sidebar.
3. Type a question such as “What is the main conclusion of this paper?”

On the first message, the model loads the full paper content as context. Follow-up questions use focused retrieval from the same paper, keeping the conversation fast and relevant.

Conversation Modes

The plugin supports multiple conversation contexts:

Interface Controls

• Model selector — switch between configured models mid-conversation.
• Reasoning selector — choose the reasoning level for the current request.
• Font scaling — adjust sidebar font size from 80% to 180%.
• Auto-scroll — automatically scrolls to the latest message.
• Token usage — real-time display of input, output, and reasoning tokens consumed.

Grounded Answers with Citation Navigation

When you ask a question, the model generates answers grounded in the paper’s content. Click any citation to jump straight to the source passage in your Zotero library.

Paper Summarization

Get a concise summary of any paper in seconds. The summary is generated from the full text of the open PDF, and you can customize the prompt to focus on methodology, results, implications, or anything else.

Selected Text Explanation

Select any complex paragraph or technical term in the PDF and ask the model to explain it. You can add up to 5 pieces of context from the paper or previous answers to refine the explanation.

An optional pop-up automatically suggests adding selected text to the chat. This can be disabled in settings if you prefer manual control.

Figure Interpretation

Take a screenshot of any figure, chart, or diagram and ask the model to interpret it. The plugin supports up to 10 screenshots at a time.

Cross-Paper Comparison

Open multiple papers in different tabs and compare them side by side. Type / in the chat input to cite another open paper as additional context. You can reference up to 10 papers in a single conversation, enabling rich cross-paper analysis.

External Document Upload

Upload documents from your local drive as additional context. Supported formats include PDF, DOCX, PPTX, TXT, and Markdown.

Save to Notes

Save any answer or selected text directly to your Zotero notes with one click. This integrates seamlessly with your existing note-taking workflow — no copy-pasting required.

Conversation History & Export

Conversations are automatically saved locally and associated with the paper you’re reading. You can:

• Browse past conversations from the history panel.
• Export entire conversations to Zotero notes in Markdown format.
• Exported notes include selected text, screenshots, and properly rendered LaTeX equations.

Custom Quick-Action Presets

Customize quick-action presets to match your research workflow. Built-in presets include:

• Summarize — generate a concise summary
• Key Points — extract main findings
• Methodology — describe the research methods
• Limitations — identify weaknesses or gaps

Standalone Window Mode

Open the LLM Assistant in its own dedicated window, separate from the Zotero reader sidebar. The standalone window provides a full-sized chat interface with a collapsible conversation history panel on the left.

How to open

Features

• Paper chat & Library chat — Switch between paper-specific and library-wide conversations using the tabs at the top.
• Conversation history — Browse past conversations organized by date (Today, Yesterday, Last 7/30 days, Older) in the collapsible left sidebar.
• Full feature parity — Everything available in the reader sidebar — screenshots, file uploads, agent mode, quick-action presets, reference picker — works identically in the standalone window.
• Search — Search through your conversation history using the search overlay.

While the standalone window is open, the reader sidebar panels show a placeholder with options to Focus Window (bring the standalone window to the foreground) or Close Window & Return Here (close standalone and restore the sidebar).

Obsidian Integration

The agent can write notes from your Zotero papers directly into your Obsidian vault — with full metadata, citations, and optionally extracted figures.

Configuration

Open Preferences → llm-for-zotero and scroll to the Obsidian Integration section.

Click Test Write Access to verify the plugin can write to your vault.

How it works

Ask the agent to write a note to Obsidian (e.g. “Summarize this paper and save it to Obsidian”). The agent will:

1. Gather content from the paper (metadata, summary, key points, etc.).
2. Compose a Markdown note using your configured template.
3. Add YAML frontmatter with title, date, tags, authors, year, and citation key.
4. Copy figures (optional) from MinerU-parsed PDFs into the attachments folder.
5. Write the note to {vault_path}/{default_folder}/{title}.md.

Notes use Pandoc citation syntax ([@citekey]), compatible with Obsidian’s Zotero Integration and Pandoc plugins.

Agent Mode (Beta)

When enabled, the LLM becomes an autonomous agent that can read, search, and write within your Zotero library — and beyond. In addition to library operations, the agent can execute terminal commands and access files on your local machine, functioning like a coding agent inside Zotero. All write operations require your explicit approval before execution.

Read Tools

These tools let the agent explore your library and the scholarly web without modifying anything.

Write Tools

All write tools require human confirmation before changes take effect.

Terminal & File System Access

The agent includes two system-level tools that turn it into a coding agent capable of running scripts and processing data — all from within Zotero.

Example use cases:

• Run a Python or R script to analyze data extracted from your library.
• Export metadata as CSV/JSON for external processing.
• Invoke CLI tools (e.g. pandoc, ffmpeg, pdftotext) as part of an agent workflow.
• Write and execute scripts dynamically to transform or visualize your research data.
• Read local data files and incorporate results back into Zotero notes.

Built-in Actions

The agent provides high-level actions for common library workflows. These chain multiple tools together automatically.

MCP Server

The plugin runs a built-in Model Context Protocol (MCP) server, allowing external AI agents and tools to interact with your Zotero library programmatically.

• Endpoint: http://localhost:23119/llm-for-zotero/mcp
• Protocol: JSON-RPC 2.0 (MCP v2024-11-05)
• Methods: initialize, tools/list, tools/call

This means you can connect any MCP-compatible AI agent (e.g. Claude Desktop, Cursor, custom agents) to your Zotero library and use all the tools listed above.

Agent Demos

Multi-step workflow

The agent can chain multiple tools together to accomplish complex tasks, such as finding a paper, reading its metadata, searching for related work, and writing a summary note.

Read a figure directly

Read multiple pages

Find related papers

Apply tags automatically

Write a note

Safety & Confirmation

All write operations go through a human-in-the-loop confirmation workflow:

• The agent proposes a batch of changes (e.g. add tags, edit metadata).
• You review the proposed changes in a rich approval form.
• You can approve, reject, or modify before any changes are applied.
• If something goes wrong, use undo_last_action to revert.
• Terminal commands and file operations also require explicit approval before execution.

Skills

Skills are customizable guidance files that shape how the agent approaches different types of requests. Each skill is a Markdown file with regex trigger patterns: when your message matches a skill’s patterns, its instructions are automatically injected into the agent’s system prompt, guiding it to use the most efficient tools and workflows for the task at hand.

Built-in Skills

The plugin ships with 9 built-in skills covering common research workflows. They are automatically copied to your skills folder on first run.

How Skills Work

1. When you send a message in Agent Mode, the plugin tests your text against every skill’s match patterns.
2. If any pattern in a skill matches (OR semantics), that skill’s instruction is injected into the agent’s system prompt for that request.
3. Multiple skills can activate simultaneously if your message matches more than one.
4. The agent uses these instructions as guidance for tool selection and workflow — they teach the agent how to approach a task, not what tasks it can do.

Creating Custom Skills

1. Open the Standalone Window (Ctrl+Shift+L / macOS: Cmd+Shift+L).
2. Click the Skills icon in the top toolbar to open the Skills portal.
3. Click the ”+ New skill” button to create a template file.
4. The template opens in your default text editor. Edit the three key parts:

---
id: my-custom-skill
match: /your regex pattern here/i
match: /another trigger pattern/i
---

Instructions for the agent when this skill matches.
Describe the workflow, which tools to prefer, and any constraints.

5. Save the file. The skill is loaded immediately — no restart needed.

Skill file format:

Managing Skills

• Left-click a skill in the portal to open it in your default text editor.
• Right-click a skill for a context menu with Show in file system and Delete options.
• Skills are stored in {ZoteroDataDir}/llm-for-zotero/skills/ as .md files.
• If you delete a built-in skill, it stays deleted across restarts — the plugin respects your choice. New built-in skills added in plugin updates are seeded automatically without restoring skills you removed.

WebChat Setup (ChatGPT Web Sync)

WebChat mode sends your questions directly to chatgpt.com through a browser extension — no API key needed. Queries are relayed from Zotero to the ChatGPT web interface, and responses stream back into the plugin.

Prerequisites

• A ChatGPT account (Free, Plus, or Team)
• A Chromium-based browser (Chrome, Edge, Brave, Arc, etc.)

Step-by-step setup

1. Download the browser extension:

Go to github.com/yilewang/sync-for-zotero → Releases, download the latest sync-for-zotero-extension.zip, and unzip it to a folder on your computer.

2. Install the extension (sideload):

• Open your browser and navigate to chrome://extensions
• Enable Developer Mode (toggle in the top-right corner)
• Click Load unpacked and select the unzipped extension folder
• The “Sync for Zotero” extension should now appear in your extensions list

3. Configure the plugin:

In Zotero → Preferences → llm-for-zotero:

4. Start chatting:

Open a ChatGPT tab in your browser and keep it open. In Zotero, the plugin panel shows a “chatgpt.com” indicator with a connection dot (green = connected, red = not detected). Type a question and send.

WebChat features

• PDF attachment — Right-click the paper chip to toggle PDF sending (purple = send, grey = skip).
• Screenshots — Use the camera button to attach figure screenshots to your message.
• Conversation history — Click the clock icon to browse and load past ChatGPT conversations.
• Exit — Click the “Exit” button to return to regular API mode.

Technical Notes

• The plugin embeds a lightweight HTTP relay server on Zotero’s built-in port (23119). The browser extension polls this relay to exchange queries and responses.
• Agent mode, slash commands (/), and the reference picker (@) are disabled in WebChat mode.
• Reasoning/thinking mode is controlled on the ChatGPT side, not through the plugin’s reasoning toggle.

Codex Auth Setup

If you have a ChatGPT Plus subscription, you can use Codex auth to access models like gpt-5.4 without a separate API key. The plugin reuses your ChatGPT login via the Codex CLI.

Special thanks to @jianghao-zhang for contributions to this feature.

Step-by-step setup

1. Install the Codex CLI (one-time):

# macOS / Linux (requires Node.js 18+)
npm install -g @openai/codex

# macOS alternative (no Node.js needed)
brew install --cask codex

2. Log in with your ChatGPT account:

codex login

A browser window opens — sign in with your ChatGPT Plus account. Credentials are saved to ~/.codex/auth.json.

3. Configure the plugin:

In Zotero → Preferences → llm-for-zotero:

Click Test Connection to verify.

Technical Notes

• Reads local credentials from ~/.codex/auth.json (or $CODEX_HOME/auth.json).
• Automatically attempts token refresh on 401 responses.
• Embeddings are not supported in codex auth mode yet.
• Local PDF/reference text grounding and screenshot/image inputs are supported.
• The Responses /files upload + file_id attachment flow is not supported yet.

MinerU PDF Parsing

MinerU is an advanced PDF parsing engine that extracts high-fidelity Markdown from PDFs while preserving tables, equations, figures, and complex layouts that standard text extraction often mangles.

When enabled, the plugin sends your PDF to the MinerU API for parsing and caches the result locally. All later interactions with that paper reuse the MinerU-parsed content, giving the model richer and more accurate context.

How to Enable MinerU

1. Open Zotero → Preferences → llm-for-zotero.
2. Find the MinerU section and check Enable MinerU.
3. Optionally enter your own MinerU API key.
4. Open any PDF and start chatting. The plugin will parse the PDF on first use and cache the result for later conversations.

Using Your Own API Key

The plugin provides a shared community proxy so MinerU works out of the box without an API key, but the shared quota is limited. For heavier usage:

1. Go to mineru.net and create an account.
2. Generate an API key in your account settings.
3. Paste the key into Zotero → Preferences → llm-for-zotero → MinerU.
4. Click Test Connection to verify.

When a personal API key is provided, the plugin calls the MinerU API directly at https://mineru.net/api/v4. Without a key, it uses the community proxy.

Frequently Asked Questions

Is it free to use?

Yes, the plugin is completely free and open source (AGPL v3). You only pay for API calls to your chosen provider. With Codex auth, ChatGPT Plus subscribers can use their existing subscription without a separate API key.

Does it work with local models?

Yes. As long as the local model provides an OpenAI-compatible HTTP API, you can connect it by entering the appropriate API Base URL and key in settings.

Is my data used to train models?

No. You use your own API key, so data privacy is governed by the terms of your chosen provider.

How do I report a bug or request a feature?

Please open an issue on GitHub.

Contributing & Support

Contributions are welcome! Whether it’s bug reports, feature requests, or pull requests — feel free to open an issue or submit a PR on GitHub.

If you find this plugin helpful, consider:

• Leaving a star on GitHub
• Buying me a coffee
• Donating via Alipay QR code below:

Star History