记录一次Context7 MCP 服务器连接失败问题解决

问题概述

Context7 MCP 服务器在启动时出现连接失败，主要表现为 Node.js ESM 模块依赖解析错误。

错误症状

MCP 连接状态

从Cherry Studio/kiro/cursor等MCP Client上面显示都是这个问题

[error] [Context7] Failed to connect to MCP server: MCP error -32000: Connection closed
[error] [Context7] Error connecting to MCP server: MCP error -32000: Connection closed

典型错误日志

一定要从去找到客户端日志，单从“MCP error -32000: Connection closed”这些关键字上面很难去从搜索引擎上找到合适的解决方案

Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/Users/{user}/.npm/_npx/eea2bd7412d4593b/node_modules/zod-to-json-schema/dist/esm/parsers/any.js' imported from /Users/{user}/.npm/_npx/eea2bd7412d4593b/node_modules/zod-to-json-schema/dist/esm/index.js

问题分析

根本原因

从 Cannot find module 关键字，我们能够基本的定位问题

1. 依赖包损坏：npx 缓存中的 zod-to-json-schema 包文件缺失或损坏
2. 权限问题：npm 缓存目录存在权限冲突
3. ESM 模块兼容性：Node.js ESM 模块解析配置不当

影响范围

• Context7 MCP 服务器无法启动
• 相关功能（文档查询、库解析等）不可用
• 可能影响其他基于 npx 的 MCP 服务器

解决方案

步骤 1：修复权限问题

# 修复 npm 缓存目录权限
sudo chown -R $(whoami) ~/.npm

步骤 2：清理缓存

# 清理 npm 缓存
npm cache clean --force

# 清理 npx 缓存
rm -rf ~/.npm/_npx

步骤 3：更新 MCP 配置

编辑 ~/.kiro/settings/mcp.json 文件：

{
  "mcpServers": {
    "Context7": {
      "command": "npx",
      "args": [
        "-y",
        "@upstash/context7-mcp@latest"
      ],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

步骤 4：验证修复

1. 重启 IDE，不管在Cursor还是其他IDE，修复MCP问题的时候重启IDE总能刷新链接状态。
2. 检查 MCP 服务器连接状态
3. 测试 Context7 功能是否正常

配置说明

关键配置项

配置项	说明	作用
@latest	使用最新版本	确保获取最新修复
NODE_OPTIONS	Node.js 运行参数	启用 ESM 实验性支持
--experimental-modules	ESM 模块支持	解决模块解析问题

环境变量选项

"env": {
  "NODE_OPTIONS": "--experimental-modules",
  "NODE_ENV": "production"
}

预防措施

定期维护

# 每月清理一次缓存
npm cache clean --force
rm -rf ~/.npm/_npx

# 检查权限
ls -la ~/.npm

配置最佳实践

1. 版本锁定：使用 @latest 或具体版本号
2. 环境变量：根据需要配置 Node.js 参数
3. 权限管理：避免使用 sudo 安装全局包

故障排查

常见问题

问题 1：权限拒绝

npm error syscall unlink
npm error errno -13

解决方案：

sudo chown -R $(whoami) ~/.npm

问题 2：模块未找到

Error [ERR_MODULE_NOT_FOUND]

解决方案：

rm -rf ~/.npm/_npx
npx -y @upstash/context7-mcp@latest

问题 3：连接超时

MCP error -32000: Connection closed

解决方案：

1. 检查网络连接
2. 重启 MCP 服务器
3. 验证配置文件语法

调试命令

# 检查 npm 配置
npm config list

# 测试包安装
npx -y @upstash/context7-mcp@latest --help

# 查看 MCP 日志
tail -f ~/.kiro/logs/mcp.log

相关资源

• Context7 官方文档
• MCP 协议规范
• Node.js ESM 文档

注意：本文档基于 macOS 环境编写，其他操作系统可能需要调整相应命令。