Claude Code连接Zotero MCP失败排查：从配置到环境变量的完整指南

写这篇的起因很简单：我最近在整理一个跨平台文献综述项目，Zotero 里存了几百条带注释的文献，而日常写代码、写方案都泡在 Claude Code 里。这两边来回切换非常割裂，我第一想法就是通过 MCP 把 Zotero 直接接进 Claude Code，让它在对话里就能检索、读取我的文献库。

模型和服务都装好了，配置也写了，结果 Claude Code 里的 MCP 服务列表反复显示连接失败。折腾了差不多一下午，把配置、环境、端口、代理全查了个遍，最后定位到问题。这篇文章把整个排查思路、关键操作和踩过的坑完整记下来，给同样在 Claude Code 里接 Zotero MCP 的同学一个能直接复现的方案。

适合谁看呢？用 Claude Code 做科研相关开发、写文献综述、或者折腾 MCP 服务发现连接不稳的人，都可以直接照着排查流程走一遍。这篇文章不假设你有很深的 MCP 背景，核心链路和配置结构我会先讲清楚，再进实操。

1. 先别急着改配置，把这条链路彻底搞明白

1.1 Claude Code、Zotero、MCP 这三者到底在干什么

理解这个组合之前，先回到一个最基础的问题：MCP 是什么。全称是 Model Context Protocol，模型上下文协议，它的作用简单概括就是给 AI 助手和外部工具/数据源之间定了一个标准接口。

打个比方：Claude Code 就像一个什么都会一点的助理，但它本身没有你本地 Zotero 里的几百条文献。想让助理翻你的文献库，不能直接把数据库文件塞给模型，那样又大又乱。MCP 相当于一个标准化插座，Claude Code 是插头，Zotero 的 MCP 服务是把 Zotero 数据改造成标准协议后暴露出来的服务端。插头插上插座，模型才能按约定格式去检索、读取、引用你的文献。

Zotero MCP 服务的工作方式，通常是先读取 Zotero 本地客户端的存储数据（或者通过 Zotero 本地 API），把搜索结果转成结构化 JSON，再通过 MCP 协议交回给 Claude Code。所以不要把它想象成一个云服务，它本质上是你机器上一个本地中间层进程。

1.2 一次正常调用要经过哪几段链路

这套组合一旦报错，很多人的第一反应是“MCP 出问题了”，但 MCP 只是中间一段。我排查时习惯把完整链路画出来：

Claude Code 会话发起工具调用 -> 读取项目里的 MCP 配置文件 -> 根据配置启动或连接 MCP Server 进程 -> MCP Server 去请求 Zotero 本地接口或读取数据 -> 返回结构化结果 -> Claude Code 把结果展示给模型 -> 模型继续生成回答。

你发现没有，这里至少有三段可能断掉的地方：

第一段是配置层。Claude Code 怎么找到 MCP Server？靠的是配置文件里的 command、args、env 这些字段。任何一个字段写错，服务就起不来。

第二段是进程层。MCP Server 本身可能启动了，但启动后立刻崩溃，或者连不上 Zotero。这个阶段问题多半出在依赖、环境变量、端口上。

第三段是数据层。Server 和 Zotero 都正常，但 Zotero 客户端没开、数据库被锁定、API token 失效等，照样返回失败。

我这次踩的坑是：一开始只盯着配置层改，改来改去都没用，后来才发现是进程层就挂了。所以先建立这个分层概念，后面排查会快很多。

2. 看清报错才能下手：各种失败信息的真实含义

2.1 高频报错速览

连接失败的时候，Claude Code 主要有几种表现，我先列一张速查表，后面再逐个展开：

我遇到的情况属于最典型的“failed to load”加“Client closed connection”。这组看起来很吓人，其实方向很明确：MCP Server 进程没在 Claude Code 手里活下来。它可能刚启动几秒就退了。

2.2 没有报错的“隐性失灵”

比显式报错更恶心的是服务状态显示正常，但工具调不出来，或者第一次调用就卡死。

有一类情况是：Claude Code 成功启动了 MCP Server，但因为 MCP Server 启动的时候没有拿到 Zotero 的访问凭证，导致它进入了一种“半死不活”的状态——不会主动崩，但每次查询都超时。这时候界面上看起来一切正常，实际上所有调用都是废的。

还有一种情况是，服务列表里能看到 zotero，但调用时 Claude Code 提示该工具不存在。这个往往是因为配置改动后没有重新加载，Claude Code 还拿着旧的工具清单。

所以我的第一个建议是：不要只看服务连接状态，一定要实际发起一次调用，用真实查询验证。比如让 Claude Code 用 zotero 工具搜一个你确定存在的文献标题，看它能不能返回结果。这一步能区分“看起来正常”和“真的正常”。

3. 分步排查实操：从配置到进程，逐层收窄问题范围

3.1 第一层：MCP 配置声明是否真能被 Claude Code 正确读取

Claude Code 里配置 MCP Server，最常见的方式是项目根目录放一个.mcp.json文件。它的基础结构长这样：

{ "mcpServers": { "zotero": { "command": "npx", "args": ["-y", "@tools/zotero-mcp"], "env": { "ZOTERO_API_KEY": "your-key-here" } } } }

注意几个关键字段：command表示用哪个程序启动，args是传给它的参数，env是传给这个子进程的环境变量。

这里大家最容易出问题的是这三件事：

第一，command写错。有的人图方便直接写了npx，但项目环境里没有 npx（比如 Node 没装好），或者用了npx但路径不对，进程根本起不来。建议先在外面终端手动跑一遍这个完整命令，确保能正常输出日志。

第二，args里的包名或脚本路径写错。很多 MCP 包有各自的启动命令，有的是tsx，有的是python -m，有的是npx -y远程拉包。写错了同样起不来。

第三，env字段缺失。有一段时期的报错我排查了很久，才发现问题不是 MCP 包本身，而是我在.zshrc里配置了一个环境变量，以为 MCP 进程能继承。实际上，Claude Code 启动的 MCP Server 会不会加载你的 shell 配置，取决于它是怎么被拉起的。有的场景会继承，有的不会。安全起见，所有 MCP 进程需要的关键环境变量都显式写进配置文件的env块里。

还有一个常见坑是配置格式问题。MCP 配置现在有两种主流传输模式：stdio（标准输入输出）和 HTTP/SSE。如果你在.mcp.json里写的配置实际是给 HTTP 模式用的（比如url字段），而 Claude Code 里用的是 stdio 模式启动，那就会一直连接失败。

3.2 第二层：Zotero 客户端和本地环境状态

MCP Server 只是个中间人，它最终要读的是 Zotero 的数据。Zotero 这一侧有几件事必须确认。

Zotero 客户端是不是真的在运行。听起来像废话，但 MCP Server 如果走的是 Zotero 本地 HTTP API，客户端没开，API 自然不会响应。我有一次排查到后半段才发现 Zotero 因为上次同步崩溃自动退出了，重开后立刻恢复正常。

Zotero 版本和 API 路径是否匹配。Zotero 各版本的本地 API 路径和鉴权方式有差异，社区常见的 Zotero MCP 包大多是针对较新版本适配的。如果你用的版本比较旧，或者反过来太激进，MCP Server 可能发出请求后拿到 404 或 401，这也会被 Claude Code 归纳为连接失败。

有没有多个 Zotero 实例同时在跑。这个情况少见但存在：一个 Zotero 开着，另一个通过命令行偷偷跑着，数据锁冲突导致 MCP Server 读库失败。排查方法很简单，进程列表里看 zotero 相关进程是不是只有一个。

3.3 第三层：直接手动启动 MCP Server，跳出 Claude Code 看问题

前两层查完还没定位，下一步一定要做：脱离 Claude Code，在终端里手动执行同样的启动命令。

这一步能把“Claude Code 的配置/加载问题”和“MCP Server 本身的问题”彻底切开。如果手动执行命令，终端里打印出一堆错误日志，那就跟 Claude Code 没关系，问题在 MCP Server 自身。

我当时手动跑完，日志里直接打出了某个依赖缺失的错误，说明是依赖环境的问题。还有一次则是打印了连接 Zotero 失败的网络错误。这两类问题在 Claude Code 界面里都只会显示成一句简单的连接失败，根本看不到真实原因。

手动启动之后，还能顺便做一件事：验证 Zotero API 是否真的可达。很多 Zotero MCP Server 支持直接用命令行参数传递 token，或者读环境变量，你可以在终端里设好环境变量，再跑一个简单的检索命令，看它能不能返回 PDF 标题、作者、年份之类的东西。

这一步如果通了，说明数据层没问题，问题就是 Claude Code 和这个进程之间的“桥”没搭好。如果这一步都不通，那就要回头解决 MCP Server 的依赖和鉴权问题，跟 Claude Code 反而没关系了。

4. 我遇到的高频原因和对应解法，可以直接抄

4.1 原因一：stdio 配置误用了 HTTP/SSE 地址

这个频率非常高。我第一个排掉的怀疑对象就是它——社区里很多 Zotero MCP 服务方案同时支持两种运行模式，一种是通过本地命令返回结果给 Claude Code（stdio 模式），一种是启动一个本地 HTTP 服务，通过 URL 连接（HTTP/SSE 模式）。

如果你看到某些示例配置里写的是url字段，不要直接抄进.mcp.json。Claude Code 默认通过 stdio 启动本地命令，它跟url字段是两套东西。你用 stdio 模式时要把command和args写好，而不是只留一个url。

我还见过有人把command写成了http://localhost:1234，这在 stdio 模式下完全不对。这个写法的本意是连接一个 HTTP 服务，但 Claude Code 会尝试执行一个叫这个名字的本地命令，结果当然失败。

解法很简单：确认你的 Zotero MCP 服务官方提供的是哪种接法。如果是 stdio 接法，配置就是command+args；如果是 HTTP 接法，则需要用 Claude Code 支持远程 MCP 的配置方式，而不是把它塞进 stdio 字段。两种模式不要混着写。

4.2 原因二：环境变量没传进 MCP 进程，Zotero API 根本拿不到凭证

这个是我这次翻车的最终原因。

我的 Zotero API Key 一直写在 shell 配置文件里，手动在终端跑什么命令都能读到，所以我一直认定环境变量没问题。但 Claude Code 拉起 MCP Server 子进程时，并不一定加载你 shell 配置文件里的那一堆 export 语句。我观察到的现象是：MCP Server 启动后，它能看到系统基础环境变量，但看不到我为 Zotero 单独设置的那个 Key。

这种问题最坑的地方在于，MCP Server 自己没有像“缺少环境变量”这样的报错，它会以“无法连接到 Zotero API”的形式超时。

排查方法是在 MCP Server 的日志里加一行环境变量检查，或者用最小测试脚本验证。我自己写了一个很小的临时脚本，导入了和 MCP Server 一样的环境变量名，然后打印出来看是不是空的。一打印，果然 key 是空字符串。

解法最干净的不是去改 shell 配置，而是直接把这个 Key 写进.mcp.json对应的env块里。比如：

{ "mcpServers": { "zotero": { "command": "npx", "args": ["-y", "@tools/zotero-mcp"], "env": { "ZOTERO_API_KEY": "实际填入你的 Key", "ZOTERO_LIBRARY_ID": "实际填入你的 Library ID" } } } }

写完配置之后，一定要重启 Claude Code 或者使用它提供的重载 MCP 命令，让它重新读取配置并启动新进程。光改文件不清缓存不重载，等于白改。

4.3 原因三：本地端口被占用，或代理把 localhost 流量劫持了

如果你的 MCP Server 是 HTTP 模式，那端口问题一定会遇到。默认端口可能已经被别的服务占了。排查方式很简单，在终端里看一下端口监听情况：

lsof -i :端口号

如果看到别的进程占着这个端口，你就要么停掉那个进程，要么给 MCP Server 换一个没被占用的端口，然后同步修改配置里的 URL。

另一个隐蔽问题是代理。如果你本机配置了全局 HTTP 代理，MCP Server 向localhost或127.0.0.1发请求时，有些代理实现会把它劫持走，导致请求根本到不了 Zotero 本地 API。

这种问题非常难发现，因为你在终端里手动跑命令时也可能同样被代理影响。

解法是在启动 MCP Server 时，把代理相关环境变量针对本机地址排除掉。常见的变量名是NO_PROXY或no_proxy，里面要包含localhost,127.0.0.1。如果 MCP Server 使用的是更底层的网络库，可能还要同时设置HTTP_PROXY、HTTPS_PROXY里的 no_proxy 逻辑。具体写法不同系统有差异，核心意图就是：走本机的请求，不要绕去代理。

我在实际修复中还遇到过一种情况：Claude Code 自己运行在一个受代理影响的环境中，MCP Server 继承了这些代理变量，导致对 Zotero API 的请求被代理拦截。验证方法是在手动启动 MCP Server 时临时清空代理变量，看连接是否恢复。

5. 一次完整修复实录：从失败到跑通的全过程

5.1 故障现场记录

我当时的故障现象如下：Claude Code 项目里配置好了.mcp.json，服务列表里能看到 zotero 这个名字，但状态一直标红，点进去显示“Connection closed”。不管怎么重试，都是这个结果。

我刚开始以为配置写错了，于是反复检查 JSON 格式和字段，确认没有拼写错误。但这并没有解决问题。

然后我退出 Claude Code，重新启动，还是失败。当时已经有点上头，差点怀疑是 Claude Code 本身的问题。

5.2 逐步操作与对应结果

下面这一步我建议大家挨个做，每一步都记一下现象，不要跳。

第一步，在项目目录对应的环境里，手动执行配置里的启动命令，不加任何包装，直接看输出。我当时执行之后，终端里显示了一段依赖错误，指向一个 Python 依赖包根本没有安装。到这里，我确认问题不在 Claude Code，而在 MCP Server 的依赖环境。

第二步，补装依赖。我用包管理器安装了这个缺失的包，然后重新执行启动命令。这次终端没有立刻报错，而是进入了一个看起来像“服务已启动，等待连接”的状态。到了这一步，进程层的问题基本解决。

第三步，用 MCP Server 自带的最小命令测试 Zotero 连通性。当时这个包支持直接命令行传参做一次检索，我传了一个 Zotero 里确定存在的文献标题，结果返回了“未找到”。我立刻检查环境变量，发现 ZOTERO_API_KEY 没有传进来，导致鉴权失败。这就是前面说的环境变量陷阱。

第四步，把 ZOTERO_API_KEY、ZOTERO_LIBRARY_ID 显式写入.mcp.json的 env 块，退出重新加载 Claude Code，服务状态从红色变成了可用的绿色。

第五步，在 Claude Code 会话里发起真实调用，让它搜索刚才那个文献标题，这次成功返回了标题、作者、年份和剪切板里的 PDF 信息。整个链路跑通。

5.3 回归验证的小建议

验证之后先别急着庆祝，我建议用三种不同方式回归测试一遍，确保不是只碰巧好使：

正常搜索：让 Claude Code 用 zotero 搜索一个关键词，看返回多条结果是否正确。多条件组合：比如按作者加年份筛选，确认查询逻辑没问题。读取附件：挑一个带 PDF 附件的文献，让 Claude Code 读取它的元数据或者附件路径。这一步能检验 MCP Server 对 Zotero 附件的访问权限。

我的经验是，很多 MCP 服务在调用一两次之后才会暴露问题，比如返回数据里某些字段为空、附件访问权限不足等。多跑几个场景再收工，后面用起来才稳。

6. 常见问题与避坑细节记录

6.1 日常踩坑速查表

6.2 容易被忽略的几个细节

第一个是包版本和运行时的搭配。很多 Zotero MCP 服务依赖特定版本的解释器环境。换一个 Node 或 Python 版本，可能从能用到直接崩。如果你之前一直用得很好，某天突然连接失败，先回顾是不是最近动过运行时版本。

第二个是配置文件的缓存问题。Claude Code 不一定每次都会重新读取.mcp.json。如果你改了配置但没生效，不要反复确认文件内容，去查它的 MCP 配置加载状态或者重启会话。我见过同事改完配置没重载，花了半小时排查“为什么配置对了还报错”。

第三个是不要把 Zotero 数据库文件直接丢给 MCP Server。MCP Server 和 Zotero 客户端共用一个数据库时，如果客户端处于写入状态，数据库可能被锁定。碰到这种情况，等 Zotero 同步结束再试往往就好了。

第四个是日志预留。连接失败时，MCP Server 的终端输出是你最重要的诊断材料。如果你用某种方式启动它，让它输出被吞掉了，那排查难度会成倍上升。我建议后续使用中，尽量保留日志到一个文件，留着出问题时候翻。

6.3 一个很多人问过的反向问题：Zotero 没开能不能用 MCP

明确说，绝大多数本地模式方案不能。因为 MCP Server 需要从 Zotero 获取数据，Zotero 客户端没有运行，本地 API 就不会响应。但如果你用的是基于 Zotero Web API 的 MCP 服务，那么不依赖客户端也能工作，只是走的是云端同步数据，不是你本地未同步的临时条目。

所以如果你需要完全离线、在不开 Zotero 客户端的情况下用，优先考虑支持 Web API 的方案，但要注意它读不到本地尚未同步的内容。

最后说点我的实际体会

这次排查下来，我最大的收获是：连接失败这种问题，第一步永远不是改配置，而是把链路拆开，确认到底哪一段断了。你手动启动一次服务，往往就知道答案了。我之前几次在配置里反复打转，本质上就是绕过了最直接的诊断手段。

另外一个经验是，环境变量这个东西，别指望继承。所有 MCP 进程要用的变量，统一写死在.mcp.json的 env 块里，一劳永逸。Zotero API Key 这种敏感信息写在项目配置里确实有泄露风险，可以在团队里约定好只放占位符，实际值走安全注入。但趋势上，宁可让配置稍微繁琐一点，也比运行时报一个莫名其妙的超时强。

希望这篇排查记录能帮你省下那一下午。如果你现在的报错还没解决，先回手动启动那一步，大概率问题就在那里等着你。