Claude Code 与 Zotero MCP 连接失败排查：从链路分析到配置修复

最近准备把 Zotero 文献库接到 Claude Code 里，让 AI 在写论文代码时可以直接检索文献，省得我手动切窗口查资料。结果环境刚搭好，第一句话还没提示完，就在 MCP 服务上栽了个跟头——连接失败，而且报错信息异常干瘪，既没有端口号也没有堆栈，只有一句近乎空白的提示。

如果你也卡在这个坑里，这篇文章应该能帮你省下不少时间。我会从整条链路拆起，把“连接失败”到底断在哪里讲清楚，再按实际排查顺序给出可复现的操作步骤。适合所有在 Claude Code 里接 Zotero MCP 服务，或者准备把本地数据服务接进 MCP 生态的开发者参考。

1. 先把链路画清楚：Claude Code 与 Zotero 之间隔着一个 MCP 进程

1.1 三个角色分别负责什么

很多人一看到“MCP 服务连接失败”就开始怀疑 Zotero 出问题了，其实 Claude Code、MCP server、Zotero 是三个独立角色，各管一段。

Claude Code 是客户端，它负责理解你的自然语言，决定何时调用工具。MCP server 是一个独立进程，典型形态是一个 Node.js 程序，通过npx启动，它的存在意义是把 Claude Code 的意图转换成 Zotero 能理解的 HTTP 请求。Zotero 则是数据源，它以桌面应用的形式跑在本地，监听一个 HTTP 端口，把文献库数据以 JSON 形式暴露出来。

这三者的关系很像餐厅里的一场点单：Claude Code 是坐在桌前的顾客，MCP server 是服务员兼传菜员，Zotero 是厨房。顾客说“我要一份某作者的论文列表”，服务员去后厨传话，后厨把菜做好端出来。任何一个环节掉链子，顾客看到的都是“上菜失败”。

1.2 “连接失败”要拆成三段来判断

“连接失败”这四个字是个笼统结论，实际可以拆成三段：

第一段，Claude Code 启动 MCP server 的过程。这一段走的是 stdio 通道，也就是 Claude Code 把 MCP server 作为子进程拉起来，然后通过标准输入输出做 JSON-RPC 通信。如果npx命令本身坏了，或者配置文件里写错了命令路径，MCP server 根本起不来，Claude Code 就会直接报一个“无法启动 MCP 服务”。

第二段，Claude Code 与 MCP server 的协议握手。进程能起来，不代表握手就顺利。MCP server 启动后需要通过 stdio 回复初始化响应，如果初始化超时或者消息格式对不上，也会表现为连接失败。

第三段，MCP server 与 Zotero 的本地 HTTP 通信。MCP server 起来之后，真正去拉文献数据时，会向 Zotero 的本地 HTTP 接口发请求。Zotero 没启动、端口被改、API Key 失效，都会让这一段的请求失败。而 MCP server 一旦拿不到数据，返回给 Claude Code 的工具调用结果里通常就写着“connection refused”或者“failed to fetch”。

我在最初排查时犯的错，就是把这三段混在一起当一个问题处理，来回改配置，越改越乱。正确思路是：先判断你遇到的报错属于哪一段，再决定动哪里。

1.3 为什么要手动验证中间那一段

不少教程只会告诉你怎么填配置文件，完全没提中间有一个“需要手工验证的断层”。MCP server 启动成功，不代表它和 Zotero 已经打通了。MCP server 介乎两个世界之间，一边是 Claude Code 的 stdio，一边是 Zotero 的 HTTP，两者互不相干。

我后来养成了一个习惯：在把 Claude Code 拉进来之前，先直接跑一遍 MCP server，再直接用 curl 去捅 Zotero 的端口。这两步都通过之后，才回到 Claude Code 里做端到端验证。这样一旦再出问题，断点位置立刻就能锁定，不用靠猜。

2. 连接失败的三副面孔：从启动报错到工具调用失败

2.1 面孔一：服务根本没起来

这一类报错通常在 Claude Code 启动时或者你输入第一个与文献相关的指令时出现，表现形式是“MCP server 连接失败”或者“工具列表里压根没有 Zotero 相关的工具”。

判断方法很简单：在 Claude Code 里用斜杠命令/mcp查看已注册的 MCP 服务器状态，或者直接看刚启动时的日志。如果 Zotero MCP 服务对应的状态是 error 而不是 connected，那基本可以断定是 MCP server 进程没有拉起来。

典型原因包括：配置文件里 command 写成了npx，但 Claude Code 的子进程没有继承你的 shell 环境，找不到 npx；或者args里的包名拼写错误；又或者配置文件本身 JSON 语法有误，Claude Code 解析时直接跳过了这个服务。

2.2 面孔二：工具列表正常，一调就超时

这类失败最迷惑人。你打开/mcp看，状态是 connected，工具列表里也能看到 Zotero 相关工具。一切看起来都正常，可一旦让 AI 执行检索文献的操作，过一会儿就报超时或者工具执行失败。

这种情况断点更可能在 MCP server 与 Zotero 之间的请求链路。比如 MCP server 进程启动成功，但它在构造请求时连接的地址或端口和你 Zotero 实际监听的端口不一致，导致所有实际请求都打到了一个无人应答的端口上。又或者 Zotero 的 API Key 配置不正确，MCP server 发起的请求被 Zotero 拒绝，而 MCP server 没有把原始错误完整透传回来，最终显示一个笼统的失败。

一个容易被忽略的点是 Zotero 文献库数据量极大。如果不知道限流，直接让 AI 全量拉取所有条目，MCP server 要等 Zotero 返回大量 JSON，很容易触发 Claude Code 侧的超时。此时工具本身没问题，是请求的规模和时限不匹配。

2.3 面孔三：MCP server 起来了，但它够不到 Zotero

第三种情况会给你最明确的证据，因为 MCP server 的日志里通常会有实打实的错误信息，比如ECONNREFUSED 127.0.0.1:23119。看到这个，就能百分百确定 MCP server 是活着，但它请求 Zotero 时被拒绝了。

Zotero 在默认配置下并不会始终打开 HTTP 服务。你需要在 Zotero 的设置里面手工开启“允许其他应用程序通过 HTTP 与 Zotero 通信”之类的选项。很多人在安装完 Zotero 之后从来没打开过这个开关，MCP server 再努力也敲不开门。

端口不一致也很常见。如果 Zotero 原本默认监听 23119，但本机有程序占用了这个端口，Zotero 会自己换一个，而 MCP server 配置里还老老实实写着 23119，两者就永远对不上。如果你改过端口，一定要在 MCP server 的配置里同步修改。

2.4 先定位面孔，再动手改配置

看到报错先别急着改配置，花两分钟确定它是哪一类，往往比盲改整个配置文件高效得多。我自己最后悔的一次排查，就是看到一个“connection failed”，二话不说把command从npx换成了node，又把环境变量全删了重填，忙活半小时才发现 Zotero 的 HTTP 服务压根没开。

记住这件事：连接失败不是一种故障，是一类故障。报错信息的措辞越笼统，越要逐层往下挖，而不是在最外层反复横跳。

3. 手把手排查链路：从 Claude Code 的报错一路摸到 Zotero 的端口

3.1 第一步：开启调试模式，把报错信息留下

排查的第一步，是让 Claude Code 输出尽量多的运行时信息。直接用普通模式启动时，MCP server 下层的报错经常会被吞掉，只留一句模糊的提示。开启调试模式可以让你看到更完整的上下文。

我在终端里重新用调试模式启动 Claude Code，然后故意触发一次文献检索调用，让报错重现。这一步的意义在于保留现场，之后不管怎么改配置，都可以拿这份原始报错作为参照，判断问题是否有改善。

3.2 第二步：先问 Zotero 自己是不是好的

在配置 Claude Code 之前，先把 Zotero 本身验证一遍。首要检查项是 Zotero 的 HTTP 服务是否在监听端口。Zotero 通常会提供一个 ping 端点，我在终端执行：

curl -s http://127.0.0.1:23119/connector/ping

如果返回pong之类的响应，说明 Zotero 的 HTTP 服务是在线的。如果提示 connection refused，说明 Zotero 这边根本没人听电话。这时候打开 Zotero 的设置界面，找到 HTTP 服务器相关选项，把允许本地访问的开关打开，再重新测试。

接着验证 API Key 是否能通过认证。Zotero 本地 API 需要一个 API Key，请求时通过请求头传递。测试命令大致是：

curl -s -H "Zotero-API-Key: 你的key" "http://127.0.0.1:23119/api/users/0/items?limit=1"

正常情况会返回一个 JSON 数组，里面是你文献库最近的数据。如果返回 401 或 403，说明 API Key 有问题，需要去 Zotero 设置里重新生成。如果返回 connection refused，说明端口或服务状态还没解决，先回到上一步。

3.3 第三步：绕开 Claude Code，直接给 MCP server 做检查

Zotero 自己正常之后，下一步就是绕过 Claude Code，直接跟 MCP server 对话。最常见的做法是在终端里手动跑一遍npx，看这个包能不能被正确拉起来。

不过这里有个新手容易误解的地方：MCP server 通过 stdio 通信，正常启动后不会打印欢迎语，而是默默等待标准输入。所以你看到终端“什么都没有发生”其实是正常的，不代表进程挂了。真正的错误反而更容易出现在启动阶段，比如 npx 找不到包、Node.js 版本不兼容。

更直观的方式是使用官方调试工具 MCP Inspector：

npx @modelcontextprotocol/inspector

它会启动一个带可视化面板的服务，让你在一个浏览器界面里选择要调试的 MCP server，然后观察服务器初始化情况、工具列表、每次工具调用的入参和返回内容。用这个工具可以非常直观地看到 MCP server 在调用 Zotero 时到底报了什么错，比如它构造的 URL、请求头、超时时间，全都能拿到台面上看。

这一步说白了就是“绕开翻译，直接听原话”。Claude Code 可能会美化或者简化错误信息，但 Inspector 会把你看到的原始请求和原始响应都暴露出来，断点在哪里一目了然。

3.4 第四步：回到配置文件，逐字段核对

如果 Inspector 里一切正常，说明 MCP server 和 Zotero 之间的关系是健康的，问题多半出在 Claude Code 的配置上。这时候再去翻配置文件，逐字段核对。

配置文件一般是一个 JSON 格式的文件，可能在项目根目录，也可能在用户级配置目录。核心字段包括command、args、env。我会逐个确认：command是不是完整可执行命令的绝对路径；args里的包名是否和实际安装的一致；env环境变量有没有把 Zotero 的 API Key、端口号正确放进去。

一个特别值得检查的是command字段里如果写的是npx，最好改成npx的实际绝对路径。因为 Claude Code 作为子进程启动 MCP server 时，可能不会继承你在 shell 里配置的 PATH，导致它找不到 npx。用绝对路径可以一劳永逸地避开这个坑。

先用这个命令找到路径：

which npx

然后把输出结果填到配置文件的command字段里。同时检查 JSON 的格式，不要多一个逗号，不要少一个引号。配置文件的格式错误会导致 MCP server 无法被识别，但报错提示又不一定明确指向 JSON 问题，所以这一步必须仔细。

3.5 第五步：在 Claude Code 里做最后一次端到端确认

前面四步都通过之后，回到 Claude Code。先在会话里使用/mcp查看服务状态，确认状态从 error 变成了 connected。然后不要直接让 AI 执行一个大而全的任务，先让它做一次最小查询，比如“列出我文献库最近 5 条记录”。

最小查询的成功意味着整条链路已经打通。之后再去测试更复杂的语义检索，或者多条件筛选，逐一扩大范围。如果最小查询失败，就再回到前面的步骤，重新从链路底层往上查。

4. 高频根因与方案对照表：照着查，别靠猜

下面这张表是我这几次排查中总结的对照表，可以帮助你快速判断问题方向。

4.1 为什么端口问题最多

端口问题几乎是我遇到的最高频根因，而且特别隐蔽。Zotero 默认的本地端口是 23119，但如果本机有程序占用了这个端口，Zotero 会悄悄换成别的端口，界面上不一定有明显提示。你只看到 MCP server 配置里写的还是 23119，两边永远接不上。

排查端口时不要只看 Zotero 设置里的端口显示，还要用系统命令确认实际监听情况。在 macOS 或 Linux 上，我常用：

lsof -iTCP:23119 -sTCP:LISTEN -n -P

这条命令会显示 23119 端口当前被哪个进程占用。如果显示的进程不是 Zotero，就说明端口冲突了，需要在 Zotero 设置里改成其他端口，并同步修改 MCP server 的环境变量。

4.2 node/npx 路径问题：Claude Code 子进程没继承 PATH

这个坑在图形界面启动的终端环境下特别容易出现。你可能在 shell 里正常使用 npx，但 Claude Code 在启动 MCP server 时，使用的是另一个完全干净的环境变量集合，里面没有你配置的 PATH 路径。结果就是你手动执行启动命令一切正常，Claude Code 里却总是给你找不着命令。

解决办法就是把command字段改成绝对路径。比如which npx的结果是/usr/local/bin/npx，那就在配置文件的command字段写这个路径。虽然这样配置看起来不如直接写npx简洁，但它能规避掉一大类环境变量继承问题，值得养成习惯。

4.3 日志里出现 API Key 的坑

还有一个小细节值得记住：调试 MCP server 时，日志里可能会原样打印请求头，如果你的请求头里有 API Key，它会以明文形式出现在日志文件里。排查完之后记得清理调试日志，尤其是当你准备把日志共享给别人的时候。这个问题和“连接失败”本身没关系，但不注意的话会带来额外风险。

5. 我保留的配置模板与日常自检命令

5.1 一份不会再让我迷路的配置模板

经过几次折腾，我现在固定使用下面这套配置思路。这份模板去掉了具体包名的引用，你只需要把你实际使用的 Zotero MCP server 包名填入对应位置即可：

{ "mcpServers": { "zotero": { "command": "/usr/local/bin/npx", "args": ["-y", "你的-zotero-mcp包名"], "env": { "ZOTERO_API_KEY": "你的-api-key", "ZOTERO_HTTP_PORT": "23119" } } } }

这里有几个设计细节值得解释。command用绝对路径是为了避开 PATH 继承的坑；ZOTERO_HTTP_PORT和 Zotero 实际监听端口保持一致，这是解决端口冲突最直接的手段；ZOTERO_API_KEY单独放在 env 里，不写进 args，避免命令串被日志记录时带出敏感信息。

另外，不要把 API Key 直接写死在项目里，尤其是项目如果使用 git 管理，很容易误提交到远程仓库。我更习惯在 env 里引用当前 shell 已有的环境变量，或者用 Claude Code 支持的环境变量注入方式，这样 Key 不会出现在磁盘文件里。

5.2 一组日常自检命令

现在每次配置变更后，我都会按顺序跑这几条命令，确认链路健康度：

curl -s http://127.0.0.1:23119/connector/ping curl -s -H "Zotero-API-Key: $KEY" "http://127.0.0.1:23119/api/users/0/items?limit=1" npx -y 你的-zotero-mcp包名 --version

第一条确保 Zotero 本地服务在线，第二条确保 API Key 能通过认证，第三条确保 MCP server 包本身可以正常被拉起。三条都通过之后，才打开 Claude Code 做端到端验证。这套流程让我从“遇到问题才排查”变成了“变更后主动确认”，省掉了很多回头路。

5.3 善用 Claude Code 里的重连操作

改完配置之后，不一定要重启整个 Claude Code 会话。很多版本提供了 MCP 服务的重连机制，在会话里输入/mcp相关命令就可以重新连接 MCP 服务器。新配置生效的速度比重启会话快得多，也不会丢失当前对话上下文。

如果重连之后状态仍然是 error，再考虑完全退出并重新启动 Claude Code。有时候 MCP server 进程状态没有正确回收，残留进程会占用旧配置，干扰新配置的加载。

6. 三个排错习惯，救了我很多次

6.1 日志永远比界面上那句提示多

第一次排查时，我盯着 Claude Code 终端里那句干瘪的“连接失败”看了半天，什么都看不出来。后来才意识到，真正的现场在底层日志里，不在终端那行提示里。MCP server 进程的启动日志、Zotero 的本地日志、Claude Code 的调试输出，这三类日志任何一个都比界面上那句提示更有说服力。

从此之后，我遇到不明报错的第一反应不再是思考哪里配置错，而是先把对应的日志翻出来。日志里清楚地告诉你哪里连不上、连的哪个端口、用的什么 key、返回了什么状态码，这些信息远比猜配置要可靠。

6.2 改配置做最小变更，一次只动一个变量

我见过不少人在排查时一次改掉 command、args、env 三个字段，结果问题解决了却不知道是哪一个改动起的作用，问题没解决就更惨，完全不知道从哪里回滚。我现在坚持一个原则：一次只改一个变量，改完立即验证，用结果反推原因。

比如怀疑是端口问题，就只改端口相关的配置，其他一概不动。验证通过后再往下排查下一个变量。这种做法看似慢，实际上比大改大调省时间，因为它让每次实验都具备明确的意义。

6.3 本地数据服务接入 AI 前，先做一次“人肉握手”

最后一条建议来自一次不小的教训。我当初恨不得把 Zotero 接进 Claude Code 之后立刻让 AI 帮我整理文献综述，结果因为链路没打通，来回折腾半天，浪费了大量时间。后来学乖了：任何本地数据服务要接入 AI 之前，先用人肉方式确认服务能独立工作。先 curl 通，再 MCP Inspector 通，最后才让 Claude Code 上。

这一条说白了就是分层验证，但很多人会跳过前面几步，直接跳到最外层，出了问题又跳到最外层反复试。数据服务本身是否健康，往往只需要一条 curl 命令就能确认，可这一步偏偏最容易被忽略。先人肉握手，再让 AI 介入，你已经赢了一半。

如果你现在正卡在 Zotero MCP 服务的连接问题上，按着前面的链路一节一节排查，大概率能在半小时内定位根因。别嫌这些步骤琐碎，排错这活儿，扎实比聪明重要得多。