Skip to content
Back to search

zotero-mcp

It's a plugin extension in Zotero. Zotero MCP Plugin enables integration between AI assistants and Zotero through MCP. Zotero MCP Plugin 是一个 Zotero 插件,通过 MCP协议实现 AI 助手与 Zotero深度集成。插件支持文献检索、元 数据管理、全文分析和智能问答等功能,让 Claude、ChatGPT 等 AI 工具能够直接访问和操作您的文献库。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/cookjohn/zotero-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/cookjohn/zotero-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cookjohn--zotero-mcp/badge.svg)](/listings/cookjohn--zotero-mcp)

HTML

<a href="/listings/cookjohn--zotero-mcp"><img src="/api/listings/cookjohn--zotero-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

This guide is intended to help general users quickly configure and use Zotero MCP, enabling your AI assistant to work seamlessly with your Zotero library.

1. Installation (For General Users)

**What is Zotero MCP?**

Simply put, Zotero MCP is a bridge connecting your AI client (like Cherry Studio, Gemini CLI, Claude Desktop, etc.) and your local Zotero reference management software. It allows your AI assistant to directly search, query, and cite references from your Zotero library, greatly enhancing academic research and writing efficiency.

**Two-Step Quick Start:**

1. **Install the Plugin**: * Go to the project's [Releases Page](https://github.com/cookjohn/zotero-mcp/releases) to download the latest `zotero-mcp-plugin-x.x.x.xpi` file. * In Zotero, install the `.xpi` file via `Tools -> Add-ons`. * Restart Zotero.

2. **Configure the Plugin**: * In Zotero's `Preferences -> Zotero MCP Plugin` tab, configure your connection settings: - **Enable Server**: Start the integrated MCP server - **Port**: Default is `23120` (you can change this if needed) - **Generate Client Configuration**: Click this button to get configuration for your AI client

---

2. Connect to AI Clients

**Important**: The Zotero plugin now includes an **integrated MCP server** that uses the Streamable HTTP protocol. No separate server installation is needed.

Streamable HTTP Connection

The plugin uses Streamable HTTP, which enables real-time bidirectional communication with AI clients:

1. **Enable Server** in the Zotero plugin preferences 2. **Generate Client Configuration** by clicking the button in plugin preferences 3. **Copy the generated configuration** to your AI client

Supported AI Clients

- **Claude Desktop**: Streamable HTTP MCP support - **Cherry Studio**: Streamable HTTP support - **Cursor IDE**: Streamable HTTP MCP support - **Custom implementations**: Streamable HTTP protocol

For detailed client-specific configuration instructions, see the [Chinese README](./README-zh.md).

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 406 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Zotero MCP - Model Context Protocol Integration for Zotero
  2. Zotero MCP is an open-source project designed to seamlessly integrate powerful AI capabilities with the leading reference management tool, Zotero, through the Model Context Protocol (MCP). This project consists of two core components: a Zotero plugin and an MCP server, which work together to provide AI assistants (like Claude) with the ability to interact with your local Zotero library.
  3. _This README is also available in: [:cn: 简体中文](./README-zh.md) | :gb: English._
  4. [![GitHub](https://img.shields.io/badge/GitHub-zotero--mcp-blue?logo=github)](https://github.com/cookjohn/zotero-mcp)
  5. [![zotero target version](https://img.shields.io/badge/Zotero-7-green?style=flat-square&logo=zotero&logoColor=CC2936)](https://www.zotero.org)
  6. [![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)
  7. [![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org)
  8. [![Version](https://img.shields.io/badge/Version-1.7.0-brightgreen)]()
  9. [![EN doc](https://img.shields.io/badge/Document-English-blue.svg)](README.md)
  10. [![中文文档](https://img.shields.io/badge/文档-中文-blue.svg)](README-zh.md)
  11. ---
  12. ## Fork us on Wechat
  13. | MP | Forum |
  14. | :--- | :---: |
  15. | ![Reading PDF](./IMG/MP.jpg) | ![Contact us](./IMG/0320.jpg) |
  16. ## 📚 Project Overview
  17. The Zotero MCP server is a tool server based on the Model Context Protocol that provides seamless integration with the Zotero reference management system for AI applications like Claude Desktop. Through this server, AI assistants can:
  18. - 🔍 **Smart Search**: Multi-dimensional library search (title/creator/year/tags/fulltext/semantic) with boolean operators and relevance scoring
  19. - 📖 **Content Extraction**: Extract PDF full-text, notes, abstracts, webpage snapshots with fine-grained mode control
  20. - 📝 **Annotation Analysis**: Search and analyze PDF highlights and annotations by color, tags, and keywords
  21. - 📂 **Collection Browsing**: Browse and search collection hierarchies, retrieve items within collections
  22. - 🧠 **Semantic Search**: AI-powered concept matching via embedding vectors, discover related literature across languages
  23. - ✏️ **Write Operations**: Create notes, manage tags, update metadata, create new items and attach PDFs
  24. - 💾 **Full-text Database**: Access and search cached PDF full-text content
  25. This enables AI assistants to help you with literature reviews, citation management, content analysis, annotation organization, knowledge base management, and more.
  26. ## 🚀 Project Structure
  27. This project now features a **unified architecture** with an integrated MCP server:
  28. - **`zotero-mcp-plugin/`**: A Zotero plugin with **integrated MCP server** that communicates directly with AI clients via Streamable HTTP protocol
  29. - **`IMG/`**: Screenshots and documentation images
  30. - **`README.md`** / **`README-zh.md`**: Documentation files
  31. **Unified Architecture:**
  32. ```
  33. AI Client ↔ Streamable HTTP ↔ Zotero Plugin (with integrated MCP server)
  34. ```
  35. This eliminates the need for a separate MCP server process, providing a more streamlined and efficient integration.
  36. ---
  37. ## 🚀 Quick Start Guide
  38. This guide is intended to help general users quickly configure and use Zotero MCP, enabling your AI assistant to work seamlessly with your Zotero library.
  39. ### 1. Installation (For General Users)
  40. **What is Zotero MCP?**
  41. Simply put, Zotero MCP is a bridge connecting your AI client (like Cherry Studio, Gemini CLI, Claude Desktop, etc.) and your local Zotero reference management software. It allows your AI assistant to directly search, query, and cite references from your Zotero library, greatly enhancing academic research and writing efficiency.
  42. **Two-Step Quick Start:**
  43. 1. **Install the Plugin**:
  44. * Go to the project's [Releases Page](https://github.com/cookjohn/zotero-mcp/releases) to download the latest `zotero-mcp-plugin-x.x.x.xpi` file.
  45. * In Zotero, install the `.xpi` file via `Tools -> Add-ons`.
  46. * Restart Zotero.
  47. 2. **Configure the Plugin**:
  48. * In Zotero's `Preferences -> Zotero MCP Plugin` tab, configure your connection settings:
  49. - **Enable Server**: Start the integrated MCP server
  50. - **Port**: Default is `23120` (you can change this if needed)
  51. - **Generate Client Configuration**: Click this button to get configuration for your AI client
  52. ---
  53. ### 2. Connect to AI Clients
  54. **Important**: The Zotero plugin now includes an **integrated MCP server** that uses the Streamable HTTP protocol. No separate server installation is needed.
  55. #### Streamable HTTP Connection
  56. The plugin uses Streamable HTTP, which enables real-time bidirectional communication with AI clients:
  57. 1. **Enable Server** in the Zotero plugin preferences
  58. 2. **Generate Client Configuration** by clicking the button in plugin preferences
  59. 3. **Copy the generated configuration** to your AI client
  60. #### Supported AI Clients
  61. - **Claude Desktop**: Streamable HTTP MCP support
  62. - **Cherry Studio**: Streamable HTTP support
  63. - **Cursor IDE**: Streamable HTTP MCP support
  64. - **Custom implementations**: Streamable HTTP protocol
  65. For detailed client-specific configuration instructions, see the [Chinese README](./README-zh.md).
  66. ---
  67. ## 👨‍💻 Developer Guide
  68. ### Prerequisites
  69. - **Zotero** 7.0 or higher
  70. - **Node.js** 18.0 or higher
  71. - **npm** or **yarn**
  72. - **Git**
  73. ### Step 1: Install and Configure the Zotero Plugin
  74. 1. Download the latest `zotero-mcp-plugin.xpi` from the [Releases Page](https://github.com/cookjohn/zotero-mcp/releases).
  75. 2. Install it in Zotero via `Tools -> Add-ons`.
  76. 3. Enable the server in `Preferences -> Zotero MCP Plugin`.
  77. ### Step 2: Development Setup
  78. 1. Clone the repository:
  79. ```bash
  80. git clone https://github.com/cookjohn/zotero-mcp.git
  81. cd zotero-mcp
  82. ```
  83. 2. Set up the plugin development environment:
  84. ```bash
  85. cd zotero-mcp-plugin
  86. npm install
  87. npm run build
  88. ```
  89. 3. Load the plugin in Zotero:
  90. ```bash
  91. # For development with auto-reload
  92. npm run start
  93. # Or install the built .xpi file manually
  94. npm run build
  95. ```
  96. ### Step 3: Connect AI Clients (Development)
  97. The plugin includes an integrated MCP server that uses Streamable HTTP:
  98. 1. **Enable the server** in Zotero plugin preferences
  99. 2. **Generate client configuration** using the plugin's built-in generator
  100. 3. **Configure your AI client** with the generated Streamable HTTP configuration
  101. Example configuration for Claude Desktop:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "zotero": {
  106. "transport": "streamable_http",
  107. "url": "http://127.0.0.1:23120/mcp"
  108. }
  109. }
  110. }
  111. ```
  112. ---
  113. ## 🧩 Features
  114. ### `zotero-mcp-plugin` Features
  115. - **Integrated MCP Server**: Built-in MCP server using Streamable HTTP protocol, no separate process needed
  116. - **Advanced Search Engine**: Full-text search with boolean operators, relevance scoring, filtering by title, creator, year, tags, item type, and more
  117. - **Unified Content Extraction**: Extract content from PDFs, attachments, notes, abstracts, webpage snapshots with four modes (minimal/preview/standard/complete)
  118. - **Smart Annotation System**: Search and retrieve PDF highlights, annotations, and notes by color, tags, and keywords with intelligent ranking
  119. - **Collection Management**: Browse, search collection hierarchies, get collection details, subcollections, and item lists
  120. - **Semantic Search**: AI-powered semantic search using embedding vectors
  121. - Supports OpenAI and Ollama embedding APIs (auto-detection)
  122. - Vector indexing with SQLite-vec storage
  123. - Index status column in main library view
  124. - Collection/item context menu for index management
  125. - **Write Operations**: Create/modify notes, manage tags, update metadata fields, create new items and reparent standalone PDFs
  126. - **Full-text Database**: Cached PDF full-text database with list, search, get, and stats operations
  127. - **Standalone Attachment Management**: Search and manage standalone PDF items without parent metadata
  128. - **Client Configuration Generator**: Automatically generates configuration for various AI clients
  129. - **Security**: Local-only operation ensuring complete data privacy
  130. - **User-Friendly**: Easy configuration through Zotero preferences interface
  131. ---
  132. ## 📸 Screenshots
  133. Here are some screenshots demonstrating the functionality of Zotero MCP:
  134. | Feature | Screenshot |
  135. | :--- | :---: |
  136. | **Feature Demonstration** | ![Feature Demonstration](./IMG/功能说明.png) |
  137. | **Literature Search** | ![Literature Search](./IMG/文献检索.png) |
  138. | **Viewing Metadata** | ![Viewing Metadata](./IMG/元数据查看.png) |
  139. | **Full-text Reading 1** | ![Full-text Reading 1](./IMG/全文读取1.png) |
  140. | **Full-text Reading 2** | ![Full-text Reading 2](./IMG/全文读取2.png) |
  141. | **Searching Attachments (Gemini CLI)** | ![Searching Attachments](./IMG/geminicli-附件检索.png) |
  142. | **Reading PDF (Gemini CLI)** | ![Reading PDF](./IMG/geminicli-pdf读取.png) |
  143. ---
  144. ## 🔧 API Reference (MCP Tools)
  145. The integrated MCP server provides **32 tools** in 6 categories:
  146. ### 1. Search & Query (7 tools)
  147. #### `search_library`
  148. Advanced library search with multi-dimensional filtering, boolean operators, relevance scoring, and intelligent mode control.
  149. - `q`, `title`, `titleOperator`, `yearRange`, `fulltext`, `fulltextMode`, `itemType`, `includeAttachments`, `mode` (minimal/preview/standard/complete), `relevanceScoring`, `sort`, `limit`, `offset`
  150. #### `search_annotations`
  151. Search annotations by query, colors, or tags with intelligent ranking.
  152. - `q`, `itemKeys`, `types` (note/highlight/annotation/ink/text/image), `colors`, `tags`, `mode`, `limit`, `offset`
  153. #### `search_fulltext`
  154. Full-text search across all document content with context snippets.
  155. - `q` (required), `itemKeys`, `mode`, `contextLength`, `caseSensitive`
  156. #### `search_collections`
  157. Search collections by name. Params: `q`, `limit`.
  158. #### `get_item_details`
  159. Get complete metadata for a single item. Params: `itemKey` (required), `mode`.
  160. #### `get_item_abstract`
  161. Get item abstract/summary. Params: `itemKey` (required), `format` (json/text).
  162. #### `get_content`
  163. Unified content extraction: PDF full-text, notes, abstracts, webpage snapshots from items or specific attachments.
  164. - `itemKey`, `attachmentKey`, `mode`, `include` (pdf/attachments/notes/abstract/webpage), `contentControl`, `format` (json/text)
  165. ### 2. Collection Management (4 tools)
  166. #### `get_collections`
  167. Get all collections. Params: `mode`, `limit`, `offset`.
  168. #### `get_collection_details`
  169. Get details of a specific collection. Params: `collectionKey` (required).
  170. #### `get_collection_items`
  171. Get items in a collection. Params: `collectionKey` (required), `limit`, `offset`.
  172. #### `get_subcollections`
  173. Get subcollections. Params: `collectionKey` (required), `limit`, `offset`, `recursive`.
  174. ### 3. Semantic Search (3 tools, can be disabled in preferences)
  175. #### `semantic_search`
  176. AI-powered semantic search using embedding vectors. Finds conceptually related content even without exact keyword matches.
  177. - `query` (required), `topK`, `minScore`, `language` (zh/en/all)
  178. #### `find_similar`
  179. Find items semantically similar to a given item.
  180. - `itemKey` (required), `topK`, `minScore`
  181. #### `semantic_status`
  182. Get semantic search service status and index statistics. No parameters required.
  183. ### 4. Full-text Database (1 tool)
  184. #### `fulltext_database`
  185. Access cached full-text content database (read-only).
  186. - `action` (required: list/search/get/stats), `query`, `itemKeys`, `limit`
  187. ### 5. Write Operations (6 tools, can be disabled in preferences)
  188. #### `write_note`
  189. Create or modify Zotero notes. Supports Markdown auto-conversion to HTML.
  190. - `action` (required: create/update/append), `parentKey`, `noteKey`, `content` (required), `tags`
  191. #### `write_tag`
  192. Add, remove, or replace tags on items.
  193. - `action` (required: add/remove/set), `itemKey` (required), `tags` (required)
  194. #### `write_metadata`
  195. Update metadata fields on items (title, abstract, date, DOI, creators, etc.).
  196. - `itemKey` (required), `fields`, `creators`
  197. #### `write_item`
  198. Create new items, reparent existing attachments, or import local files as attachments.
  199. - `action` (required: create/reparent/import), `itemType`, `fields`, `creators`, `tags`, `attachmentKeys`, `parentKey`, `filePath`, `parentItemKey`, `title`, `linkMode` (import: `imported_file` copies into Zotero storage, `linked_file` links in place — personal library only), `libraryID`
  200. #### `add_by_identifier`
  201. Import items by identifier (DOI, arXiv, ISBN, PMID, ADS bibcode) using Zotero's native resolvers — the same pipeline as the desktop "magic wand", including translator metadata and automatic attachment fetching.
  202. - `identifiers` (required), `libraryID`, `collectionKey`, `saveAttachments`, `duplicates`, `titleDuplicates`, `dryRun`, `async`, `jobID`
  203. #### `trash_item`
  204. Move one or more items to Zotero Trash. Items stay recoverable until the user empties Trash; permanent deletion is not supported (`permanent` is rejected).
  205. - `itemKeys` (required, array of item keys; deduplicated), `libraryID`
  206. ### 6. Citation & Bibliography (3 tools)
  207. #### `export_bibliography`
  208. Export one or more Zotero items as BibLaTeX/BibTeX (or CSL-JSON/CSL-YAML) entries powered by the zotero-better-bibtex (BBT) plugin. Requires Better BibTeX to be installed and running in Zotero.
  209. - `itemKeys` (required), `format` (biblatex/bibtex/csljson/cslyaml), `libraryID`
  210. #### `get_citation`
  211. Generate a formatted reference (bibliography entry) or in-text citation for one or more items using a CSL citation style. If no style is specified, uses the Zotero default Quick Copy style. Works without Better BibTeX.
  212. - `itemKeys` (required), `style`, `contentType` (html/text), `mode` (bibliography/citation), `libraryID`
  213. #### `list_citation_styles`
  214. List CSL citation styles available in Zotero (for use with `get_citation`).
  215. - `filter`
  216. ---
  217. ## 🔌 External Tool Registration API
  218. Other Zotero plugins can register custom MCP tools that are exposed through this plugin's MCP server. This allows third-party plugins to extend the AI-accessible toolset without running their own HTTP server.
  219. ### How It Works
  220. 1. Your plugin calls `Zotero.ZoteroMCP.api.registerTool(...)` to register a tool.
  221. 2. The tool appears in `tools/list` alongside built-in tools.
  222. 3. When an AI client calls the tool, the MCP server dispatches the call to your handler.
  223. 4. On disable/uninstall, call `Zotero.ZoteroMCP.api.unregisterTool(...)` or `unregisterAllTools(pluginID)`.
  224. ### API Methods
  225. | Method | Description |
  226. |---|---|
  227. | `registerTool(def)` | Register a custom MCP tool. Throws on invalid input or name collision. |
  228. | `unregisterTool(name)` | Unregister a tool by name. Returns `true` if removed. |
  229. | `unregisterAllTools(pluginID)` | Unregister all tools from a specific plugin. Returns count removed. |
  230. | `getRegisteredTools()` | List registered tools (readonly, handler excluded). |
  231. | `isToolRegistered(name)` | Check if a tool name is already registered. |
  232. | `onToolListChanged(cb)` | Subscribe to tool list changes. Returns an unsubscribe function. |
  233. ### Tool Definition
  234. ```typescript
  235. {
  236. name: string; // Unique, matches /^[a-z][a-z0-9_]*$/, must not collide with built-in tools
  237. description: string; // Shown to AI clients
  238. inputSchema: object; // JSON Schema for input parameters
  239. handler: (args: any) => Promise<any> | any; // Called when AI invokes the tool
  240. pluginID?: string; // Optional: your plugin ID (for bulk cleanup)
  241. enabled?: boolean; // Optional: visibility toggle (default: true)
  242. }
  243. ```
  244. ### Example (from another plugin)
  245. ```javascript
  246. // Register a custom MCP tool from your Zotero plugin
  247. const mcp = Zotero.ZoteroMCP;
  248. if (mcp && mcp.api && mcp.api.registerTool) {
  249. mcp.api.registerTool({
  250. name: 'my_plugin_count_items',
  251. description: 'Count items in the Zotero library by type',
  252. inputSchema: {
  253. type: 'object',
  254. properties: {
  255. itemType: { type: 'string', description: 'Filter by item type (e.g. journalArticle)' }
  256. }
  257. },
  258. handler: async (args) => {
  259. const items = await Zotero.Items.getAll(Zotero.Libraries.userLibraryID);
  260. const filtered = args.itemType
  261. ? items.filter(i => i.itemType === args.itemType)
  262. : items;
  263. return { total: filtered.length, itemType: args.itemType || 'all' };
  264. },
  265. pluginID: 'my-plugin@example.com'
  266. });
  267. }
  268. ```
  269. ### Cleanup on Uninstall
  270. ```javascript
  271. // In your plugin's shutdown hook:
  272. const mcp = Zotero.ZoteroMCP;
  273. if (mcp && mcp.api && mcp.api.unregisterAllTools) {
  274. mcp.api.unregisterAllTools('my-plugin@example.com');
  275. }
  276. ```
  277. ### Notes
  278. - Tool names must not collide with built-in tools (see list above). Use a prefix like `my_plugin_*`.
  279. - The registry survives MCP server restarts (e.g. port changes). Tools registered before the server starts will appear once it does.
  280. - Handler errors are caught and returned as MCP error responses — no need to wrap in try/catch.
  281. - Results are JSON-serialised and wrapped in MCP `text` content automatically.
  282. - External tools are **not** covered by this plugin's "Enable write operations" switch. If your tool modifies the library, gate it in your own plugin.
  283. - Registrations live in this plugin's memory. They are dropped when Zotero MCP is disabled, updated or reloaded, so register again whenever `Zotero.ZoteroMCP.api` becomes available.
  284. ---
  285. ## 🤝 Contributing
  286. Contributions are welcome! Please feel free to submit pull requests, report issues, or suggest enhancements.
  287. 1. Fork the repository.
  288. 2. Create your feature branch (`git checkout -b feature/AmazingFeature`).
  289. 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
  290. 4. Push to the branch (`git push origin feature/AmazingFeature`).
  291. 5. Open a Pull Request.
  292. ## 📄 License
  293. This project is licensed under the [MIT License](./LICENSE).
  294. ## 🙏 Acknowledgements
  295. - [Zotero](https://www.zotero.org/) - An excellent open-source reference management tool.
  296. - [Model Context Protocol](https://modelcontextprotocol.org/) - The protocol for AI tool integration.
  297. - [![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square&logo=github)](https://github.com/windingwind/zotero-plugin-template)
  298. Contact us
  299. ![Contact us](./IMG/0320.jpg)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.