最近我干了一件挺折腾的事——把 Zotero 直接接进了 Claude Code。现在我在终端里问一句“我最近三个月加过哪些讲大模型的文献”Claude 会自己去我的文献库里查按时间把条目列成表还能顺手提炼摘要。这篇文章是把整个配置过程完整记录下来Windows 和 Mac 两套流程分开写每个关键步骤后面都带踩坑备注。适合谁看三类人一是手头 Zotero 里攒了几百上千条文献、想让 AI 帮忙整理的人二是已经在用 Claude Code、想把它变成“了解自己知识库”的助手的人三是不想被各种报错劝退的新手。我会尽量少说废话直接给你能抄的配置也把那些文档里不会写的坑提前替你踩一遍。1. 内容整体设计与思路拆解1.1 需求拆解把“人工搬运”变成“按需查询”先说说我最初遇到的问题。做文献综述的时候我经常需要一次性整理几十篇论文的作者、年份、期刊、DOI、摘要。Zotero 本身管理这些信息很顺手但要把它们喂给 AI传统路径是打开 Zotero选中条目导出 CSV 或 BibTeX。把导出文件拖进 Claude 的对话框或者贴给代码编辑器。让 AI 去解析、总结、归类。这套流程最大的问题是每加一篇文献你都得重新导出一次。而且对于动辄上千条的文献库导出的 CSV 文件好几 MB塞给 AI 的 Token 消耗高得离谱AI 还没开始分析光读文件就花掉一大截上下文窗口。所以我当时给自己定的目标是让 Claude 像人一样需要哪条查哪条。我提问“这个作者最近发了几篇论文”“这个标签下有哪几篇”“这篇论文的 DOI 是什么”它都能自己去 Zotero 里查出来而不是让我手动整理好再投喂给它。这个目标一旦实现等于给 Claude 开了个“数据库后门”交互方式从我单向搬运变成了它主动查询。1.2 三条技术路线横向对比要实现“AI 自己查 Zotero”我当时想了三套方案方案实现难度实时性缺点手动导出 BibTeX/CSV 再喂给 AI最低无数据陈旧、Token 消耗大、每次都要重复操作写脚本调用 Zotero 本地 API 生成快照中等准实时只能做一次性快照AI 无法在对话中按条件筛选通过 MCP server 让 Claude Code 直接访问 Zotero较高实时需要配一次环境初学有门槛第一方案我用了很久后期明显扛不住。第二方案我试过用 Python 脚本拉数据本质上等于把 Zotero 的数据库导出成一个 Markdown 文件再用 Claude Code 去读文件。这种方式比手动导出好一点但依然很死板你想查“去年发的、标题里带 transformer 的、且打过潜在综述标签的文献”脚本不知道你要查什么它只能把整库倒给你筛选还是得靠后续对话完成。第三方案就是我最终选定的 MCP。它在 Claude Code 和 Zotero 之间建立了一条标准化的工具调用通道Claude 自己决定什么时候调、调哪个工具、传什么参数。这才是真正意义上把“数据入口”交到了 AI 手里。1.3 为什么 MCP 值得折腾MCP全称 Model Context Protocol是 Anthropic 带起来的一套模型上下文协议。说白了一点以前你让 AI 干活它只有眼睛和嘴没有手MCP 就是给它安了一双手而且是标准接口的手。Claude Code 是这套协议的客户端Zotero MCP server 是服务端两端通过 stdio 或 HTTP 通信AI 在对话中按需调用工具。打个比方。以前你是开了一家餐厅的老板你想让助理帮你点货得把整本库存表打印出来塞给他现在你直接把收银系统连上助理的电脑他需要看库存就自己查库存需要查价格就自己查价格你只需要回答“查什么”和“干什么用”。MCP 干的就是这个事。当时有人问我直接用 Zotero 的 Web API让 Claude 写代码去 request 不行吗行但问题在于 Claude 每次都要现场生成 HTTP 请求代码而且它对 Zotero 的数据模型不熟容易写错。MCP server 把这些请求封装成一个个语义明确的工具Claude 不用关心底层接口细节它只需要说“我要用 search_items 这个工具搜‘diffusion’”。整个调用链是稳定的、可复现的。用 MCP 连 Zotero 的 MCP server会暴露几类能力按条件搜索条目、按分类拉取文献、获取条目的完整元数据和摘要、部分实现还能读取附件 PDF 的正文文本。这些工具足够支撑日常文献工作流了。2. 环境准备双平台的共同地基2.1 Zotero 7 和它的本地 API先检查你手上的 Zotero 版本。我强烈建议直接上 Zotero 7原因很简单新版对本地 API 的支持更稳定而且社区里多数 Zotero 相关的 MCP server 都在 7 上测试过。打开 Zotero 的帮助菜单里面可以看版本号如果还是 6.x先去官网下载最新版记得先把旧插件和数据库备份一下Zotero 6 升级到 7 之后有些老旧插件是会失效的。Zotero 桌面版安装完并启动之后其实它默认就在本机开了一个 HTTP 服务监听 23119 端口。这个服务原本是用来跟浏览器插件通信的但你不一定要手动开启什么开关装上就有。验证方法是在终端里执行curl http://127.0.0.1:23119/api/users/0/items?limit3如果返回一串 JSON说明本地 API 已经可用。如果连接被拒绝先确认 Zotero 进程是不是真的在运行有些精简安装包会默认关闭后台驻留你需要把它打开。这里有个容易绕晕的细节/api/users/0/里的0表示“本机当前用户”这是本地 API 的特殊写法。后续配置 MCP server 时如果走本地模式也经常会用到这个 ID如果走 Web API则要换成你的真实用户 ID。这两个 ID 完全不是一回事我后面踩坑部分会专门再说。2.2 Claude Code 安装与登录Claude Code 本质是一个 npm 包官方名字叫anthropic-ai/claude-code。装它之前需要 Node.js 环境我建议至少 Node 18版本太低有些 MCP server 跑不起来。Windows 下安装 Node 最简单的方式winget install OpenJS.NodeJS.LTSMac 下用 Homebrewbrew install node装完验证一下node -v npm -v然后全局安装 Claude Codenpm install -g anthropic-ai/claude-code安装完成后在终端输claude --version能输出版本号就说明装好了。第一次运行claude会进入登录流程按它提示在浏览器里完成 OAuth 授权即可。需要说明的是Claude Code 需要有对应的 Claude 账号权限订阅用户或者 API 用户都能跑但用 API 时需要先确认一下你的账号模型访问权限否则对话时会提示没有可用模型。这一步我在 Windows 和 Mac 上都没有遇到加分项登录流程基本一致。2.3 拿一个 Zotero Web API Key虽然 Zotero 有本地 API但我最终还是选择了配 Web API Key 的方式原因稍后解释。获取过程很快浏览器打开 zotero.org登录你的账号。进入 Settings找到 Keys 一栏。点击 Create new private key。权限那里至少勾选对所有库的读权限read-only别勾写权限。保存后页面会显示一个 24 位左右的 key同时页面上方能看到你的用户 ID。那个用户 ID 是一串数字跟本地 API 里的0完全是两码事别搞混。这个 key 就是你账号在 Zotero 云端数据库的“通行证”MCP server 会用这个 key 去查你的在线文献库。有人可能问为什么不直接用本地 API还要去申请云端的 Key原因有两层。第一大部分 MCP server 实现默认走 Web API文档和社区例子都是这套配起来标准统一。第二Web API 不依赖 Zotero 桌面版是否在运行偶尔你只想跟 Claude 聊文献不想启动那个笨重的桌面程序Web API 也能工作。缺点是云端数据有同步延迟所以第一次用之前最好先在 Zotero 客户端里点一下“同步”把最新条目传到云端。3. 核心实操MCP 接入与验证3.1 MCP server 怎么选、装什么Zotero 的 MCP server 社区里已经有好几个实现有的是 Python 写的有的是 Node.js 写的。我当时选了一个基于 Python 的zotero-mcp因为它的工具覆盖比较全能按关键词搜条目、按分类拉文献、获取附件信息甚至尝试读取 PDF 文本。这类 server 的安装方式一般有两种用 pip/pipx 安装或者用 npx 直接拉一个 Node 包。配置方法大差不差本质都是把它以 MCP server 的形式注册到 Claude Code。先说一个概念Claude Code 的 MCP 支持分“项目级”和“用户级”。项目级配置写在每个项目根目录的.mcp.json里好处是可以跟着项目走团队里其他人 clone 下来也能看到用户级配置则存在当前用户的配置文件里只对你自己的环境生效。我个人更推荐用claude mcp add命令来管理因为它会自动处理配置文件的写入和路径问题少了很多手动编辑 JSON 的麻烦。3.2 Windows 完整配置流程我在 Windows 上用的环境是 Windows Terminal PowerShell 7整个过程分四步。第一步打开 PowerShell进到你要用 Claude Code 的项目目录。第二步把 Zotero MCP server 注册进去claude mcp add zotero --env ZOTERO_API_KEY你申请的Key --env ZOTERO_USER_ID你的用户ID -- npx -y zotero-mcp这里的--env就是把 Key 和用户 ID 作为环境变量传给 MCP servernpx -y zotero-mcp表示用 npx 直接运行这个包省去手动安装依赖的步骤。如果你的 MCP server 是 Python 版命令会变成uvx zotero-mcp或python -m zotero_mcp看你自己选哪个实现。第三步验证是否注册成功claude mcp list这时应该能看到名为zotero的 server状态是connected。如果显示failed或missing多半是 Key 填错了或者 npx 找不到包。第四步启动 Claude Code直接测试。在终端里跑claude进入交互后输入请帮我列出文献库里最近添加的 5 条文献。如果配置成功Claude 会调用 Zotero MCP 的搜索工具然后返回条目列表。这一步能看到效果非常重要能确认整条链路是通的。Windows 上最常踩的坑有三个。第一个是 PowerShell 的执行策略。如果你第一次运行 npx 报错提示“因为在此系统上禁止运行脚本”那是因为系统的 ExecutionPolicy 太严临时放开当前用户就行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned第二个坑是 npx 在 CMD 和 PowerShell 下的表现略有差异有时候 PowerShell 找不到 npx 命令但新开一个窗口又好了。如果一直提示找不到改成绝对路径C:\Program Files\nodejs\npx.cmd后面跟同样的参数。第三个是本地防火墙弹窗有些机器会拦截 Node 进程连接本机端口弹窗出现时记得勾选“允许在专用网络上访问”。3.3 Mac 完整配置流程Mac 上的配置跟 Windows 几乎一样的命令行但有几处细节不一样。我用的终端是 zsh安装完 Node 和 Claude Code 之后npm 的全局 bin 目录通常在/opt/homebrew/binApple Silicon或/usr/local/binIntel这两个目录默认已经在 PATH 里不太需要手动配。配置命令claude mcp add zotero --env ZOTERO_API_KEY你申请的Key --env ZOTERO_USER_ID你的用户ID -- npx -y zotero-mcp同样用claude mcp list验证。如果 MCP 启动失败先检查一个很隐蔽的问题macOS 的防火墙/隐私设置。第一次运行第三方 Node 或 Python 进程时系统会弹出“是否允许其接受传入连接”此时必须点“允许”否则 MCP server 无法通过 stdio 与 Claude Code 正常通信表现就是claude mcp list状态为connected但真正调用工具时一直超时。还有一个 Mac 特有的坑如果你系统里同时有系统自带的 Python 3 和 Homebrew 装的 Pythonpip install可能把包装到了不同环境。装任何 Python 类 MCP 依赖时先确认which python3 python3 -m pip --version确保你要用的那个 Python 解释器和 pip 是同一个。用pipx或uv可以完美规避这个问题我后来直接把 MCP server 改用 uv 启动claude mcp add zotero --env ZOTERO_API_KEY... --env ZOTERO_USER_ID... -- uvx zotero-mcp这样依赖隔离更干净不污染系统环境。3.4 项目级与用户级配置怎么选虽然推荐用claude mcp add但为了让读者对配置结构有直观理解我也把项目级.mcp.json放这里说明。在项目根目录新建一个.mcp.json内容如下{ mcpServers: { zotero: { command: npx, args: [-y, zotero-mcp], env: { ZOTERO_API_KEY: 你的Key, ZOTERO_USER_ID: 你的用户ID } } } }启动 Claude Code 后它会自动读取这个文件并尝试连接。这种方式的好处是配置随项目走换台电脑 clone 项目就能复用坏处是如果你的 Key 明文写在里面又把这个文件提交到了 Git 仓库等于把数据库权限公开了。所以我现在的习惯是项目级.mcp.json里不放真实 Key而是用${ZOTERO_API_KEY}之类的环境变量引用Key 单独放在.env或系统的环境变量里。如果只是自己用最省心的是直接走claude mcp add它默认把配置写到当前用户的配置里不会污染项目仓库。3.5 验证 Claude 能查到文献配置完成之后先别急着做复杂的综述任务用最简单的方式验证一遍。我建议按顺序试三条测试指令列出文献库里最近添加的 3 条文献。搜索 2024 年标题包含 diffusion 的文献。列出标签为“综述候选”的所有条目。当你发出第一条指令Claude 如果成功调用了 MCP 工具它会先展示工具调用的过程比如“正在调用 search_items参数 limit3”然后返回结果。如果这几条都能正常处理说明链路已经通了。接下来你就可以让它干更复杂的事总结这十篇文献的共性问题、按期刊分组统计数量、找出某篇文献的 DOI 和附件路径。这些操作以前需要人工导出再投喂现在直接在对话里完成。4. 踩坑实录文档里不会写的东西4.1 故障速查表把我在 Windows 和 Mac 两边遇到的所有问题整理成一张表方便你遇到问题直接查。症状可能原因处理方式本地 API 访问返回 404Zotero 没启动启动 Zotero 后重试端口 23119 被占用其他软件占用了本地端口用 netstat/lsof 查端口关掉冲突进程MCP server 状态显示 failedWeb API Key 错误检查 Key 是否复制完整、权限是否勾选 readnpx 不是内部命令Node 没装或 PATH 没刷新重新安装 Node新开终端验证 node -vPowerShell 禁止运行脚本ExecutionPolicy 限制用 RemoteSigned 策略放开当前用户Mac 上 MCP 一直超时防火墙拦截了 Node/Python 进程到系统设置允许传入连接查询结果不包含最新文献Web API 同步延迟打开 Zotero 客户端先执行一次同步Claude 说没有找到该工具会话启动早于 MCP 注册重启 Claude Code 会话用 mcp list 确认中文条目显示乱码终端编码问题Windows 用 Windows TerminalMac 确保 locale 为 UTF-8这个表不是万能的但覆盖了九成以上初学者会遇到的问题。如果这里没中招耐心看后面的具体分析。4.2 Windows 专属的坑Windows 上最难缠的不是 Zotero 本身而是终端环境。我第一次配置时卡在执行策略上报错信息很吓人——“无法加载文件因为在此系统上禁止运行脚本”但这个坑其实两分钟就能解决用 RemoteSigned 不要用 Unrestricted保持基本安全底线。真正让我花时间的事是 npx 路径问题。当时 PowerShell 里claude mcp add命令提交了MCP 状态全是failedLog 里提示找不到 npx。排查了两轮发现是 PATH 环境变量在安装 Node 后没有刷新新终端里npx是能用的但 Claude Code 所在的进程是以旧会话启动的路径缓存没更新。所以记住装完 Node 之后务必关掉所有终端窗口重新开别偷懒。还有个冷门的坑如果你的 Windows 用户名是中文或者项目路径里有空格npx 通过 MCP 的 stdio 启动子进程时引号处理容易出问题。表现为 server 能注册但一调用就报spawn npx ENOENT或 JSON parse error。解决办法是把 npx 换成全路径并且给整条命令加上引号claude mcp add zotero --env ZOTERO_API_KEY你的Key --env ZOTERO_USER_ID你的ID -- C:\Program Files\nodejs\npx.cmd -y zotero-mcp另外如果你在 Windows 上开启了 WSL但又在 WSL 里访问 Windows 宿主机上的 Zotero 服务127.0.0.1 指向的是 WSL 自己不是 Windows。别问我是怎么知道的问就是那晚我查了半小时防火墙。4.3 Mac 专属的坑Mac 上踩坑的方向完全不一样。第一件事是 macOS 的隐私弹窗。系统对本地网络访问管控很严第一次启动 Zotero MCP server 时会弹一个“允许 Node.js 接受传入连接”的窗口如果你手快点了“不允许”后续所有 MCP 调用都会在握手阶段超时。这个设置在系统设置里的“网络”一栏把那几个禁用的 Node/Python 条目改回“允许”即可。第二件让人头疼的是 Homebrew 的 Node 版本管理。如果你之前装过 nvm后来用 brew 又装了 node两个版本会在 PATH 里打架。node -v显示的是 A 版本npm -v却是 B 版本MCP server 启动时因为依赖不匹配直接崩。后来我把 nvm 彻底清理掉统一用 brew 管理才算安静下来。第三件Apple Silicon 上跑 Python 类 MCP server有些包没有 arm64 预编译轮子pip install会现场给你编源码时间很长还可能缺依赖。强烈建议直接brew install uv用uvx zotero-mcp启动uv 会自动建好独立环境省掉这些破事。Mac 本地的 Zotero 数据库路径是/Users/用户名/Zotero/默认没问题但如果你把 Zotero 数据目录移到外置硬盘或自定义路径部分 MCP 工具在解析附件路径时会拿到奇怪的路径组合一般不影响元数据查询但读取 PDF 附件功能会失效。平时我把数据目录保持默认尽量不折腾。4.4 文献数据本身的坑环境问题解决之后数据层面的坑才真正开始。第一个坑本地 API 和 Web API 的条目标识不一致。同一个文献通过本地 API 查到的key字段和通过 Web API 查到的可能不一样原因在于本地库还没有完全同步到云端或者你在两台设备上编辑过。这个问题在混合使用两种模式时特别致命你可能用本地模式让 Claude 找到了一条 PDF 附件路径然后切到 Web API 模式发现那个条目根本不存在。解决思路就是要么全程用 Web API要么全程用本地模式别混着来。第二个坑PDF 全文读取不是默认能力。很多 MCP server 号称支持“读取附件内容”但实际上只是拿到附件的元数据和路径。要真正读 PDF 正文server 内部还得调解析器而且 Zotero 附件如果是链接型Link to File而不是存储型Stored File解析难度会更大。我的经验是如果只是想查标题、作者、摘要、DOI、标签MCP 完全够用但如果你要让 Claude 基于 PDF 正文回答问题建议另外把文献原文丢给文档分析工具处理或者先用 Zotero 的翻译/阅读插件把文本导出成笔记再进 MCP。第三个坑中文标签和特殊字符。Zotero 里标签库我习惯用中文MCP server 调用时如果没做 URL encode中文字符很容易导致请求失败。大部分 server 内部会处理但个别实现不会。遇到“搜索中文标签没结果”时直接让 Claude 先用 list_collections 或 list_tags 工具看看它到底能看到什么比瞎猜快得多。4.5 进阶玩法与扩展接好之后我就不满足于“问一条答一条”了开始琢磨更高级的用法。目前我日常用得最勤的是“综述素材生成”。给 Claude 一个主题词让它搜索 Zotero 里所有相关文献然后按年份分组、提取每篇的关键贡献、标出实证方法和样本量最后自动输出一张 Markdown 表格。之前这种工作要我自己在 Excel 里筛半天现在一句话搞定。第二个玩法是“引文审计”。写论文之前我先让 Claude 根据我在 Zotero 里的某个收藏集核对参考文献列表看看哪些引文信息不完整——缺 DOI、缺期刊名、作者名写了一半。它会把缺项条目列出来我再统一去补省了很多逐条审查的力气。第三个值得推荐的是“系统性综述初筛”。拿一个研究主题先让 Claude 读文献库里标记过的候选文献按纳入/排除标准做二分类输出待全文评估的清单。虽然模型判断有时会失误但作为初筛工具效率远高于纯人工。这些玩法都不需要再改配置MCP 本身只是通道真正的想象力在 Claude 怎么使用这条路。建议你接好 Zotero 后先花十分钟把你的收藏夹结构、标签体系理顺越规整Claude 查询的准确性越高。5. 最后想说的个人经验折腾这两天我最深的体会倒不是省了多少时间而是工作方式变了。以前是我想办法把自己觉得有用的文献片段贴给 AI现在 AI 能自己去查、去筛、再回来给我结果。虽然中间报错报得我想摔键盘但用熟之后确实回不去了。最后再说一句安全提醒Zotero Web API Key 就是你文献库的通行证别留在.mcp.json里提交到 GitHub 仓库。我自己就吃过这个教训有次提交项目时差点把 Key 带上去后来养成了配置文件的 template 和实际的 env 分离的习惯。MCP 配置跟着机器走Key 只在本地这才是舒服的状态。