zotero-research
Use when the user wants to search, browse, read, summarize, cite, annotate, or manage their Zotero library through Zotero MCP. Triggers include Zotero, 文献库, 查文献, 读论文, PDF 注释, citation key, BibTeX, 标签, 集合, and adding or updating Zotero items.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- zotero-research
- metadata
- { "short-description": "Search and manage Zotero via MCP" }
- description
- Use when the user wants to search, browse, read, summarize, cite, annotate, or manage their Zotero library through Zotero MCP. Triggers include Zotero, 文献库, 查文献, 读论文, PDF 注释, citation key, BibTeX, 标签, 集合, and adding or updating Zotero items.
03 SKILL.md 正文
Zotero Research
Use this skill when working with the user's Zotero library through the zotero MCP server.
Defaults
- Use local Zotero first. If a database path is needed, read it from
ZOTERO_DB_PATH; do not assume a hard-coded machine path. - Semantic search uses the default local embedding model from
zotero-mcp(all-MiniLM-L6-v2) unless the current MCP configuration explicitly exposes OpenAI or Gemini embeddings. - Prefer read-only exploration unless the user explicitly asks to add, update, tag, create collections, or merge items.
- Write operations are allowed when requested clearly. For destructive or hard-to-reverse operations, especially duplicate merging, show a dry-run/preview first.
llm-for-zotero Compatibility
- The user's Zotero desktop may have
llm-for-zoteroinstalled: https://github.com/yilewang/llm-for-zotero. - Treat
llm-for-zoteroas a Zotero-side PDF reader and library assistant. It is not exposed as a Codex marketplace plugin or as thezoteroMCP server. - Treat this personal
zotero-research-toolsplugin as the Codex-facing layer: it exposes thezoteroMCP server, reads Zotero metadata/full text/notes/annotations/tags/collections, and routes research tasks. - Use
llm-for-zoterooutput only after it is saved into Zotero notes/annotations, the MinerU Markdown cache, file-based notes, or pasted by the user. Do not assume Codex can operate the add-on UI directly through MCP. - As of
llm-for-zoterov3.8.13, the add-on advertises stronger chat-history search, source-grounded citation rendering, Codex trace display, Markdown/Mermaid/SVG rendering, and smarter MinerU cloud polling. Treat these as Zotero-side UI/output helpers; they do not make the add-on UI directly callable from thezoteroMCP server. - Keep data paths distinct:
ZOTERO_DB_PATHis only the optional Zotero MCP database path and should point tozotero.sqlite.- The MinerU cache belongs under Zotero's data directory as
llm-for-zotero-mineru, not underZOTERO_DB_PATHand not necessarily under the user's Obsidian folder.
- Main conflict checks:
- If
ZOTERO_DB_PATHpoints outside the resolved Zotero data directory, Codex andllm-for-zoteromay be reading different libraries. - If MinerU cache files are absent, prefer Zotero MCP full text/notes first and do not report stale cache counts.
- Do not add a separate marketplace entry for
llm-for-zotero; this repo should expose onlyzotero-research-toolsfor Codex-side work.
- If
- Quick local status entry from this repo root:
.\plugins\zotero-research-tools\scripts\start-zotero-mcp.ps1 -Status
Official Zotero Plugin Routing
- The user has installed the official Codex Zotero plugin. Treat it as a separate managed plugin, not as code to merge into this personal plugin.
- If official Zotero app tools are available in the current session, prefer them for broad paper discovery, citation lookup, citation insertion, and simple bibliography workflows.
- Prefer this personal
zotero-research-toolsplugin for local Zotero MCP operations, local library metadata, notes, annotations, tags, collections, write operations, and any workflow that depends on the user's local Zotero database. - Prefer the MinerU
full.mdcache for deep paper reading, evidence extraction, methods/results checking, and figure/table-aware summaries. - If both official Zotero and this personal plugin can answer a request, use official Zotero for citation-facing output and this personal plugin for local evidence reading and synthesis.
- If the user says the official Zotero plugin is installed but its tools are not exposed in the current session, say so clearly and fall back to this personal plugin.
- Do not combine the official plugin and this plugin into one local bundle. Keep this plugin as a local augmentation and routing layer around Zotero MCP,
llm-for-zotero, and MinerU output.
MinerU Markdown Cache
llm-for-zoterocan parse PDFs with MinerU and save enhanced Markdown plus extracted images in Zotero's data directory.- Do not assume the cache is in the Obsidian notes folder. The configured Obsidian folder may be empty even when MinerU output exists.
- Resolve Zotero's actual data directory first:
- Inspect Zotero
prefs.jsunder the active profile, usually%APPDATA%\Zotero\Zotero\Profiles\*\prefs.js. - If
extensions.zotero.useDataDiristrue, useextensions.zotero.dataDir. - Otherwise fall back to Zotero's default data directory.
- Inspect Zotero
- MinerU cache layout:
<Zotero data directory>\llm-for-zotero-mineru\<numeric item or attachment id>\full.md<Zotero data directory>\llm-for-zotero-mineru\<numeric item or attachment id>\manifest.json<Zotero data directory>\llm-for-zotero-mineru\<numeric item or attachment id>\images\
- Prefer
full.mdfor paper-content questions when it exists; it is usually richer than generic PDF text extraction and keeps figure/table references. - Use
manifest.json, the first Markdown heading, or Zotero MCP metadata to map numeric cache folders back to human-readable paper titles. - Legacy cache names may exist as
_content.mdinside the numeric folder or<id>.mddirectly under the MinerU cache directory, butfull.mdis the current primary file. - Current machine snapshot from 2026-04-23: 57
full.mdfiles were found under the MinerU cache. Treat this as a stale-prone snapshot and verify live before reporting counts.
Search Flow
- Start broad with recent items, collections, tags, or keyword search:
zotero_get_recentzotero_get_collectionszotero_get_tagszotero_search_itemszotero_advanced_search
- Use
zotero_semantic_searchfor concept-level questions, literature discovery, or when the user's query is a topic rather than an exact title/author. - After identifying candidates, read details with:
zotero_get_item_metadatazotero_get_item_fulltextzotero_get_item_childrenzotero_get_annotationszotero_get_notes
- When the user references a citation key, use
zotero_search_by_citation_keybefore fuzzy search.
Zotero MCP v0.4.1 Notes
Recent zotero-mcp-server releases are published on PyPI even when GitHub release pages lag. v0.4.x keeps the zotero-mcp serve command, adds a standalone zotero-cli, optional install extras (semantic, pdf, scite, all), relation tools, Scite citation/retraction tools, configurable transports, and database maintenance commands such as zotero-mcp update-db and zotero-mcp db-status.
Recent MCP tools may include collection-scoped search, item relationship lookup, note create/update/delete, PDF area annotation support, local image/PDF attachment support, PDF outline extraction, Scite enrichment, and direct relation add/remove. Use these capabilities only when the exposed MCP tool list in the current Codex session actually includes them; otherwise fall back to metadata/full-text/annotation reads and report the limitation.
Current upstream checked: zotero-mcp-server v0.4.1. Useful compatibility fixes include local fulltext extraction from .zotero-ft-cache and Zotero storage when filenames drift, UTF-8 handling for Windows PDF extraction, annotation text extraction, Better BibTeX citation-key lookup, group-library URL normalization, HTTP/1.1 local API transport for Zotero 7+, and non-PDF fulltext extraction from text-like attachments.
Be careful with write semantics in v0.4.1 and newer: zotero_update_item.collections replaces collection membership instead of adding to it. Preview the target collection keys before using it on existing items.
For note edits, prefer an explicit preview first and keep item keys or collection keys in the response so changes are traceable.
Answering Style
- Answer in Chinese unless the user asks otherwise.
- Cite the Zotero item key, title, authors, and year/date when reporting findings.
- Distinguish metadata, full text, notes, and annotations when conclusions depend on them.
- If full text or annotations are unavailable, say that clearly and fall back to metadata/abstract.
- For multi-paper comparisons, keep a compact table first, then a short synthesis.
Write Operations
Allowed when the user clearly requests them:
- Add items:
zotero_add_by_doi,zotero_add_by_url,zotero_add_from_file - Organize items:
zotero_create_collection,zotero_manage_collections,zotero_batch_update_tags - Edit metadata:
zotero_update_item - Related items:
zotero_add_item_relation,zotero_remove_item_relation - Duplicates: run
zotero_find_duplicatesfirst; only callzotero_merge_duplicatesafter the user confirms the preview.
Maintenance
- If semantic search returns no results, check
zotero_get_search_database_statusand considerzotero_update_search_database. - If shell access is more efficient than MCP schemas, use
zotero-clifor quick search/get/tag/database checks after confirming it is installed on PATH. - If local connection fails, ask the user to open Zotero and enable local API communication in Zotero preferences.
- If search quality is weak, rebuild the semantic database with full-text indexing (
zotero-mcp update-db --fulltext, or--force-rebuildafter changing embedding models) before changing embedding providers.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.