{"id":35094117,"url":"https://github.com/cookjohn/zotero-mcp","last_synced_at":"2026-06-11T02:01:44.949Z","repository":{"id":310223827,"uuid":"1037892603","full_name":"cookjohn/zotero-mcp","owner":"cookjohn","description":"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 工具能够直接访问和操作您的文献库。","archived":false,"fork":false,"pushed_at":"2026-06-10T17:09:06.000Z","size":10349,"stargazers_count":885,"open_issues_count":26,"forks_count":68,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-06-10T19:06:46.084Z","etag":null,"topics":["literature-review","mcp-server","zotero"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cookjohn.png","metadata":{"files":{"readme":"README-zh.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-14T09:31:55.000Z","updated_at":"2026-06-10T17:33:21.000Z","dependencies_parsed_at":"2025-08-16T16:43:08.057Z","dependency_job_id":"7217bdca-6201-486d-a194-532659e455f0","html_url":"https://github.com/cookjohn/zotero-mcp","commit_stats":null,"previous_names":["cookjohn/zotero-mcp"],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/cookjohn/zotero-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookjohn%2Fzotero-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookjohn%2Fzotero-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookjohn%2Fzotero-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookjohn%2Fzotero-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cookjohn","download_url":"https://codeload.github.com/cookjohn/zotero-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cookjohn%2Fzotero-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34178819,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["literature-review","mcp-server","zotero"],"created_at":"2025-12-27T15:04:24.311Z","updated_at":"2026-06-11T02:01:44.936Z","avatar_url":"https://github.com/cookjohn.png","language":"TypeScript","funding_links":[],"categories":["📚 Projects (1974 total)","カテゴリ","Browser-extensions"],"sub_categories":["MCP Servers","🔍 \u003ca name=\"search--knowledge\"\u003e\u003c/a\u003e検索・ナレッジ"],"readme":"# Zotero MCP - Model Context Protocol Integration for Zotero\n\nZotero MCP 是一个开源项目，旨在通过模型上下文协议（Model Context Protocol, MCP）将强大的 AI 功能与领先的文献管理工具 Zotero 无缝集成，为 AI 助手（如 Claude）提供与您本地 Zotero 文献库交互的能力。\n_This README is also available in: [:gb: English](./README.md) | :cn: 简体中文._\n[![GitHub](https://img.shields.io/badge/GitHub-zotero--mcp-blue?logo=github)](https://github.com/cookjohn/zotero-mcp)\n[![zotero target version](https://img.shields.io/badge/Zotero-7-green?style=flat-square\u0026logo=zotero\u0026logoColor=CC2936)](https://www.zotero.org)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.4-blue)](https://www.typescriptlang.org)\n[![Version](https://img.shields.io/badge/Version-1.5.0-brightgreen)]()\n[![EN doc](https://img.shields.io/badge/Document-English-blue.svg)](README.md)\n[![中文文档](https://img.shields.io/badge/文档-中文-blue.svg)](README-zh.md)\n\n---\n## 关注我们\n \n | 公众号 | 加入群聊 |\n| :--- | :---: |\n| ![Reading PDF](./IMG/MP.jpg) | 扫左侧公众号二维码，关注后私信「入群」即可（群二维码有时效且群已满 200 人，无法直接扫码加入） |\n## 📚 项目概述\n\nZotero MCP 服务器是一个基于 Model Context Protocol 的工具服务器，它为 Claude Desktop 等 AI 应用提供了与 Zotero 文献管理系统的无缝集成。通过此服务器，AI 助手可以：\n\n- 🔍 **智能搜索**：多维度搜索文献库（标题/作者/年份/标签/全文/语义），支持布尔运算和相关性评分\n- 📖 **内容提取**：获取 PDF 全文、笔记、摘要、网页快照等多种内容，支持精细的模式控制\n- 📝 **批注分析**：按颜色、标签、关键词检索和分析 PDF 高亮与注释\n- 📂 **分类浏览**：浏览和搜索分类层级结构，获取分类下的条目\n- 🧠 **语义搜索**：基于 AI 向量嵌入的概念匹配，发现跨语言的相关文献\n- ✏️ **写入操作**：创建笔记、管理标签、更新元数据、创建新条目并关联附件\n- 💾 **全文数据库**：访问和搜索缓存的 PDF 全文内容\n\n这使得 AI 助手能够帮助您进行文献综述、引用管理、内容分析、批注整理、知识库管理等学术工作。\n\n## 🚀 项目结构\n\n本项目采用了**统一架构**，将 MCP 服务器集成在插件内：\n\n- **`zotero-mcp-plugin/`**: 一个集成了 **MCP 服务器功能**的 Zotero 插件，使用 Streamable HTTP 协议直接与 AI 客户端通信\n- **`IMG/`**: 截图和说明文档图片\n- **`README.md`** / **`README-zh.md`**: 项目说明文档\n\n**统一架构：**\n```\nAI 客户端 ↔ Streamable HTTP ↔ Zotero 插件（集成 MCP 服务器）\n```\n\n这种设计消除了对单独 MCP 服务器进程的需求，提供了更加简化和高效的集成方式。\n\n---\n\n## 🚀 快速上手指南\n\n本指南旨在帮助普通用户快速配置和使用 Zotero MCP，让您的 AI 助手能够与 Zotero 文献库无缝协作。\n\n### 1. 快速使用教程（面向普通用户）\n\n**Zotero MCP 是什么？**\n\n简单来说，Zotero MCP 是一座桥梁，它连接了您的 AI 客户端（如 Cherry Studio, Gemini CLI, Claude Desktop 等）和本地的 Zotero 文献管理软件。通过它，AI 助手可以直接搜索、查询和引用您 Zotero 库中的文献，极大地提升学术研究和写作效率。\n\n**两步快速开始：**\n\n1.  **安装插件**：\n    *   前往项目的 [Releases 页面](https://github.com/cookjohn/zotero-mcp/releases) 下载最新的 `zotero-mcp-plugin-x.x.x.xpi` 文件。\n    *   在 Zotero 中，通过 `工具 -\u003e 附加组件` 安装该 `.xpi` 文件。\n    *   重启 Zotero。\n\n2.  **配置插件**：\n    *   在 Zotero 的 `首选项 -\u003e Zotero MCP Plugin` 标签页中：\n        - **启用服务器**：勾选此选项启动集成的 MCP 服务器\n        - **端口设置**：默认为 `23120`（可根据需要修改）\n        - **生成客户端配置**：点击此按钮获取适用于您 AI 客户端的配置代码\n    *   将生成的配置代码复制到您的 AI 客户端配置文件中\n\n配置完成后，您就可以在 AI 助手中通过自然语言与您的 Zotero 文献库进行交互了。\n\n**配置示例（Claude Desktop）：**\n```json\n{\n  \"mcpServers\": {\n    \"zotero\": {\n      \"transport\": \"streamable_http\",\n      \"url\": \"http://127.0.0.1:23120/mcp\"\n    }\n  }\n}\n```\n\n**使用示例:**\n\n-   `\"帮我查找一下我的 Zotero 库里所有关于\"人工智能\"的文献\"`\n-   `\"获取去年由 Hinton 发表的关于 transformer 的期刊文章\"`\n-   `\"查找 DOI 为 10.1038/nature14539 的文献\"`\n\n---\n\n### 2. 连接 AI 客户端\n\n**重要**：Zotero 插件现在包含了**集成的 MCP 服务器**，使用 Streamable HTTP 协议。无需安装单独的服务器。\n\n#### Streamable HTTP 连接\n\n插件使用 Streamable HTTP 协议，支持与 AI 客户端的实时双向通信：\n\n1. 在 Zotero 插件设置中**启用服务器**\n2. 点击**生成客户端配置**按钮\n3. 将生成的配置**复制到您的 AI 客户端**\n\n#### 支持的 AI 客户端\n\n- **Claude Desktop**: Streamable HTTP MCP 支持\n- **Cherry Studio**: Streamable HTTP 支持\n- **Cursor IDE**: Streamable HTTP MCP 支持\n- **自定义实现**: Streamable HTTP 协议\n\n### 验证与故障排查\n\n配置完成后，如何确认一切正常工作？\n\n**1. 验证连接**\n\n*   **查看客户端状态**：大多数 AI 客户端（如 ChatBox, Cherry Studio）的 MCP 配置界面会显示服务器的连接状态。如果显示为 \"Connected\" 或绿色指示灯，说明连接已成功建立。\n*   **使用测试命令**：在 AI 助手的聊天框中，发送一个简单的测试命令，例如：\n    `\"使用 zotero 工具查找任何文献，返回一条即可\"`\n    如果 AI 能够调用 `zotero.search_library` 并返回结果，说明整个链路已通。\n\n**2. 故障排查指南**\n\n如果连接失败或工具不工作，请按以下步骤排查：\n\n| 步骤 | 检查项 | 解决方案 |\n| :--- | :--- | :--- |\n| **1** | **Zotero 插件服务** | 确保 Zotero 正在运行，并且在 `首选项 -\u003e Zotero MCP Plugin` 中，\"Enable Server\" 已被勾选。 |\n| **2** | **路径配置** | 确认 AI 客户端中的 `command` 设置为 `node`，并且作为参数的 `index.js` **绝对路径**完全正确。路径错误是导致失败的最常见原因。 |\n| **3** | **端口冲突** | 如果 Zotero 插件端口 `23119` 被占用，请在插件设置中更换端口，并在 `zotero-mcp-server` 目录下创建 `.env` 文件，内容为 `ZOTERO_API_PORT=新端口号`。 |\n| **4** | **查看日志** | 大多数客户端都提供 MCP 服务器的日志输出功能。在 MCP 配置界面寻找 \"Show Logs\" 或类似的按钮。日志是定位问题的最有效工具，通常会明确指出是路径错误、命令失败还是其他问题。 |\n| **5** | **防火墙/安全软件** | 确认您的防火墙或安全软件没有阻止 `node.exe` (Windows) 或 `node` (macOS/Linux) 的网络通信。 |\n| **6** | **环境依赖** | 确保您的系统中已安装 Node.js (版本 18+)。您可以在终端中运行 `node -v` 来检查版本。 |\n\n**3. 常见错误信息**\n\n*   **`command not found` 或 `spawn ENOENT`**: 通常表示 `node` 命令不存在或路径错误。请检查 Node.js 是否已正确安装并加入了系统环境变量，或者检查客户端配置中的命令是否正确。\n*   **`Error: connect ECONNREFUSED 127.0.0.1:23119`**: 表示 MCP 服务器无法连接到 Zotero 插件。请执行上述排查指南的第 1 步和第 3 步。\n*   **JSON 格式错误**: 在手动编辑配置文件时，请确保您的 JSON 语法正确，没有遗漏逗号或括号。\n\n如果以上步骤均无法解决问题，请前往 [GitHub Issues](https://github.com/cookjohn/zotero-mcp/issues) 页面，并附上您的操作系统、客户端版本和相关的日志信息，以便我们更好地帮助您。\n\n---\n\n## 🧩 插件功能特性\n\n`zotero-mcp-plugin` 是一个集成了 MCP 服务器功能的 Zotero 插件，直接与 AI 客户端通信。\n\n### 主要功能\n\n-   **集成 MCP 服务器**: 内置 MCP 服务器，使用 Streamable HTTP 协议，无需额外进程\n-   **高级搜索引擎**: 支持全文搜索、布尔运算、相关性评分，按标题、作者、年份、标签、文献类型等多维度筛选\n-   **统一内容提取**: 从 PDF、附件、笔记、摘要、网页快照中提取内容，支持四种模式（minimal/preview/standard/complete）\n-   **智能批注系统**: 按颜色、标签、关键词搜索和检索 PDF 高亮、注释和笔记，支持智能排序\n-   **分类管理**: 浏览、搜索分类层级结构，获取分类详情、子分类和条目列表\n-   **语义搜索**: 基于 AI 向量嵌入的语义搜索，支持 OpenAI/Ollama API，发现概念相关的文献\n-   **写入功能**: 创建/修改笔记、管理标签、更新元数据字段、创建新条目并关联独立 PDF\n-   **全文数据库**: 缓存的 PDF 全文数据库，支持列表、搜索、获取和统计操作\n-   **独立附件管理**: 搜索和管理只有 PDF 没有元数据信息的独立条目\n-   **客户端配置生成器**: 自动为各种 AI 客户端生成配置\n-   **安全性**: 仅本地操作，确保数据完全隐私\n-   **用户友好**: 通过 Zotero 首选项界面轻松配置\n\n---\n\n## 效果展示\n\n这里是一些展示 Zotero MCP 功能的截图：\n\n| 功能 | 截图 |\n| :--- | :---: |\n| **功能说明** | ![功能说明](./IMG/功能说明.png) |\n| **文献检索** | ![文献检索](./IMG/文献检索.png) |\n| **元数据查看** | ![元数据查看](./IMG/元数据查看.png) |\n| **全文读取 1** | ![全文读取 1](./IMG/全文读取1.png) |\n| **全文读取 2** | ![全文读取 2](./IMG/全文读取2.png) |\n| **附件检索 (Gemini CLI)** | ![附件检索](./IMG/geminicli-附件检索.png) |\n| **PDF 读取 (Gemini CLI)** | ![PDF 读取](./IMG/geminicli-pdf读取.png) |\n\n---\n\n## 👨‍💻 开发者安装指南\n\n### 前置要求\n\n- **Zotero** 7.0 或更高版本\n- **Node.js** 18.0 或更高版本（仅用于开发）\n- **npm** 或 **yarn** 包管理器（仅用于开发）\n- **Git**（仅用于开发）\n\n### 步骤 1: 安装和配置 Zotero 插件\n\n1. 前往项目的 [Releases 页面](https://github.com/cookjohn/zotero-mcp/releases) 下载最新的 `zotero-mcp-plugin-x.x.x.xpi` 文件\n2. 在 Zotero 中，通过 `工具 -\u003e 附加组件` 安装该 `.xpi` 文件\n3. 在 Zotero 的 `首选项 -\u003e Zotero MCP Plugin` 标签页中，配置服务器设置：\n   - **启用服务器**：启动集成的 MCP 服务器\n   - **端口设置**：默认为 `23120`\n   - **生成客户端配置**：点击按钮获取适用于您 AI 客户端的配置\n\n### 步骤 2: 开发环境设置（可选）\n\n如果您想要修改或开发插件，可以按照以下步骤设置开发环境：\n\n1. 克隆本仓库到本地：\n   ```bash\n   git clone https://github.com/cookjohn/zotero-mcp.git\n   cd zotero-mcp\n   ```\n\n2. 设置插件开发环境：\n   ```bash\n   cd zotero-mcp-plugin\n   npm install\n   npm run build\n   ```\n\n3. 在 Zotero 中加载插件：\n   ```bash\n   # 开发模式（自动重载）\n   npm run start\n   \n   # 或手动安装构建后的 .xpi 文件\n   npm run build\n   ```\n\n### 步骤 3: 连接 AI 客户端\n\n插件包含了集成的 MCP 服务器，使用 Streamable HTTP 协议：\n\n**Streamable HTTP 连接示例（Claude Desktop）：**\n\n1. 找到 Claude Desktop 配置文件：\n   - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n2. 编辑配置文件：\n   ```json\n   {\n     \"mcpServers\": {\n       \"zotero\": {\n         \"transport\": \"streamable_http\",\n         \"url\": \"http://127.0.0.1:23120/mcp\"\n       }\n     }\n   }\n   ```\n\n3. 重启 Claude Desktop 应用\n\n### 步骤 4: 开始使用\n\n配置完成后，您就可以在 AI 助手中通过自然语言与您的 Zotero 文献库进行交互了。\n\n**示例:**\n\n-   `\"帮我查找一下我的 Zotero 库里所有关于“人工智能”的文献\"`\n-   `\"获取去年由 Hinton 发表的关于 transformer 的期刊文章\"`\n-   `\"查找 DOI 为 10.1038/nature14539 的文献\"`\n\n---\n\n## 👨‍💻 开发者文档\n\n### 技术架构\n\n```\n┌─────────────┐  Streamable HTTP  ┌──────────────────────────────┐\n│ AI 客户端    │ \u003c--------------\u003e │ Zotero 插件（集成 MCP 服务器） │\n│ (Claude, etc) │                   │ + 内置API + 数据访问        │\n└─────────────┘                   └──────────────────────────────┘\n```\n\n1. **AI 客户端** 通过 Streamable HTTP 协议直接与插件通信\n2. **Zotero 插件** 内置 MCP 服务器，处理 MCP 请求并调用 Zotero API\n3. **数据处理** 在插件内部完成，无需额外进程\n4. **响应返回** 直接发送给 AI 客户端\n\n### 插件开发\n\n1. 进入插件目录并安装依赖：\n   ```bash\n   cd zotero-mcp-plugin\n   npm install\n   ```\n   \n2. 启动开发模式：\n   ```bash\n   npm start\n   ```\n   这将启动 Zotero 并自动加载插件。代码更改时会自动重载。\n\n3. 构建插件 `.xpi` 文件：\n   ```bash\n   npm run build\n   ```\n\n### MCP 服务器开发\n\nMCP 服务器已集成在插件内，位于 `src/modules/streamableMCPServer.ts`。主要功能：\n\n- Streamable HTTP 连接管理\n- MCP 协议处理\n- 工具调用路由\n- 错误处理和日志记录\n\n---\n\n## 🔧 API 参考（MCP 工具列表）\n\n插件集成的 MCP 服务器提供以下 **20 个工具**，分为 5 大类：\n\n### 一、搜索与查询（7 个）\n\n#### `search_library`\n高级文献库搜索，支持多维度筛选、布尔运算、相关性评分和智能模式控制。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `q` | string | 通用搜索关键词 |\n| `title` | string | 标题搜索（支持 `titleOperator`: contains/exact/startsWith/endsWith/regex） |\n| `yearRange` | string | 年份范围（如 \"2020-2023\"） |\n| `fulltext` | string | 全文搜索（附件/笔记内容），支持 `fulltextMode`: attachment/note/both |\n| `itemType` | string | 文献类型筛选（journalArticle/book/attachment 等） |\n| `includeAttachments` | string | 设为 \"true\" 可搜索独立 PDF 条目 |\n| `mode` | string | 处理模式：minimal(30)/preview(100)/standard(自适应)/complete(500+) |\n| `relevanceScoring` | boolean | 启用相关性评分 |\n| `sort` | string | 排序：relevance/date/title/year |\n| `limit` / `offset` | number | 分页控制 |\n\n#### `search_annotations`\n按关键词、颜色或标签搜索批注，支持智能排序和相关性过滤。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `q` | string | 搜索关键词（与 colors/tags 至少提供一个） |\n| `itemKeys` | string[] | 限定搜索范围到指定条目 |\n| `types` | string[] | 批注类型：note/highlight/annotation/ink/text/image |\n| `colors` | string[] | 按颜色过滤（支持色名或 hex：yellow/red/green/blue/purple/orange） |\n| `tags` | string[] | 按标签过滤 |\n| `mode` | string | 内容处理模式 |\n\n#### `search_fulltext`\n在所有文档全文中搜索，返回上下文片段和相关性评分。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `q` | string | **必需**，搜索关键词 |\n| `itemKeys` | string[] | 限定搜索范围 |\n| `mode` | string | 处理模式 |\n| `contextLength` | number | 匹配上下文长度 |\n| `caseSensitive` | boolean | 区分大小写 |\n\n#### `search_collections`\n按名称搜索分类。参数：`q`（搜索词）、`limit`（最大结果数）。\n\n#### `get_item_details`\n获取单个文献的完整元数据（作者、日期、DOI、标签、附件、笔记等）。参数：`itemKey`（必需）、`mode`。\n\n#### `get_item_abstract`\n获取条目的摘要/简介。参数：`itemKey`（必需）、`format`（json/text）。\n\n#### `get_content`\n统一内容提取工具：从条目或附件中获取 PDF 全文、笔记、摘要、网页快照等。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `itemKey` | string | 条目 Key（获取该条目下所有内容） |\n| `attachmentKey` | string | 附件 Key（获取特定附件内容） |\n| `mode` | string | minimal(500字符)/preview(1.5K)/standard(3K)/complete(无限制) |\n| `include` | object | 控制包含哪些内容：pdf/attachments/notes/abstract/webpage |\n| `contentControl` | object | 高级内容控制（preserveOriginal/allowExtended/maxContentLength 等） |\n| `format` | string | 输出格式：json（结构化）或 text（纯文本） |\n\n### 二、分类管理（4 个）\n\n#### `get_collections`\n获取文献库中所有分类列表。参数：`mode`、`limit`、`offset`。\n\n#### `get_collection_details`\n获取特定分类的详细信息。参数：`collectionKey`（必需）。\n\n#### `get_collection_items`\n获取指定分类中的条目列表。参数：`collectionKey`（必需）、`limit`、`offset`。\n\n#### `get_subcollections`\n获取子分类列表。参数：`collectionKey`（必需）、`limit`、`offset`、`recursive`（是否递归）。\n\n### 三、语义搜索（3 个，可在偏好设置中禁用）\n\n#### `semantic_search`\n基于 AI 向量嵌入的语义搜索，即使没有精确关键词匹配也能找到概念相关的内容。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `query` | string | **必需**，自然语言查询（如 \"机器学习在医疗中的应用\"） |\n| `topK` | number | 返回结果数量（默认 10） |\n| `minScore` | number | 最低相似度（0-1，默认 0.3） |\n| `language` | string | 语言过滤：zh/en/all |\n\n#### `find_similar`\n基于指定条目发现语义相似的文献。参数：`itemKey`（必需）、`topK`、`minScore`。\n\n#### `semantic_status`\n查看语义搜索服务的状态、索引统计和覆盖率。无需参数。\n\n### 四、全文数据库（1 个）\n\n#### `fulltext_database`\n访问缓存的全文内容数据库（只读）。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `action` | string | **必需**：list（列表）/search（搜索）/get（获取）/stats（统计） |\n| `query` | string | 搜索关键词（search 操作必需） |\n| `itemKeys` | string[] | 指定条目（get 操作） |\n| `limit` | number | 最大结果数 |\n\n### 五、写入操作（4 个，可在偏好设置中禁用）\n\n#### `write_note`\n创建或修改 Zotero 笔记，支持 Markdown 自动转换为 HTML。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `action` | string | **必需**：create/update/append |\n| `parentKey` | string | 关联到指定条目（create 时可选，省略则创建独立笔记） |\n| `noteKey` | string | 已有笔记 Key（update/append 必需） |\n| `content` | string | **必需**，笔记内容（Markdown 或 HTML） |\n| `tags` | string[] | 添加标签 |\n\n#### `write_tag`\n添加、移除或替换条目上的标签。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `action` | string | **必需**：add（追加）/remove（移除）/set（替换全部） |\n| `itemKey` | string | **必需**，条目 Key |\n| `tags` | string[] | **必需**，标签列表 |\n\n#### `write_metadata`\n更新条目的元数据字段（标题、摘要、日期、DOI、作者等）。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `itemKey` | string | **必需**，条目 Key |\n| `fields` | object | 要更新的字段（title/abstractNote/date/url/DOI/language 等） |\n| `creators` | array | 替换作者列表，每项包含 creatorType/firstName/lastName 或 name |\n\n#### `write_item`\n创建新的文献条目或重新关联附件。\n\n| 参数 | 类型 | 描述 |\n|---|---|---|\n| `action` | string | **必需**：create（创建条目）/reparent（移动附件） |\n| `itemType` | string | 条目类型（journalArticle/book/conferencePaper/thesis 等） |\n| `fields` | object | 元数据字段 |\n| `creators` | array | 作者列表 |\n| `tags` | string[] | 标签 |\n| `attachmentKeys` | string[] | 要关联的独立附件 Key 列表 |\n| `parentKey` | string | reparent 操作的目标父条目 Key |\n\n---\n\n## 🐛 常见问题 (FAQ)\n\n#### 1. 连接被拒绝错误\n\n**问题**: `Error: connect ECONNREFUSED 127.0.0.1:PORT`\n**解决方案**:\n- 确保 Zotero 正在运行\n- 检查 Zotero 插件是否已启用\n- 在插件设置中检查服务器是否已启用\n- 确认端口号（默认 23120）与 AI 客户端配置一致\n\n#### 2. Streamable HTTP 连接失败\n\n**问题**: `Streamable HTTP connection failed`\n**解决方案**:\n- 确保在插件设置中启用了服务器\n- 检查防火墙设置，允许 Zotero 进行网络通信\n- 确认 URL 格式正确：`http://127.0.0.1:23120/mcp`\n\n#### 3. Claude Desktop 无法识别工具\n\n**问题**: Claude 不显示 Zotero 相关工具\n**解决方案**:\n- 检查 `claude_desktop_config.json` 中的配置是否正确\n- 确保使用了 `\"transport\": \"streamable_http\"` 配置\n- 确保 JSON 格式正确\n- 重启 Claude Desktop 应用\n\n#### 4. 插件服务器无法启动\n\n**问题**: 插件设置显示服务器启动失败\n**解决方案**:\n- 检查端口是否被占用，尝试更换端口\n- 重启 Zotero 应用\n- 查看 Zotero 错误控制台（`工具 -\u003e 开发者 -\u003e 错误控制台`）\n\n---\n\n## 🤝 贡献指南\n\n欢迎贡献代码、报告问题或提出建议！\n\n1.  Fork 本仓库。\n2.  创建您的功能分支 (`git checkout -b feature/AmazingFeature`)。\n3.  提交您的更改 (`git commit -m 'Add some AmazingFeature'`)。\n4.  推送到分支 (`git push origin feature/AmazingFeature`)。\n5.  开启一个 Pull Request。\n\n## 📄 许可证\n\n本项目采用 [MIT License](./LICENSE) 授权。\n\n## 🙏 致谢\n\n- [Zotero](https://www.zotero.org/) - 优秀的开源文献管理工具。\n- [Model Context Protocol](https://modelcontextprotocol.org/) - 实现 AI 工具集成的协议。\n- [![Using Zotero Plugin Template](https://img.shields.io/badge/Using-Zotero%20Plugin%20Template-blue?style=flat-square\u0026logo=github)](https://github.com/windingwind/zotero-plugin-template)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookjohn%2Fzotero-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcookjohn%2Fzotero-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcookjohn%2Fzotero-mcp/lists"}