排查：MCP Server 启动失败（Process exited）

当你配置好 MCP Server 后，发现工具列表为空，或者看到 "Process exited" 错误时，本文将帮助你系统性地排查和解决问题。

问题现象

• Claude Code 中输入 /mcp 看不到任何工具
• 工具列表为空或部分工具缺失
• 日志中出现 "Process exited with code 1"

排查流程

第一步：验证配置文件

检查 JSON 格式

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq

检查路径格式

• ❌ 错误：使用相对路径或 ~
• ✅ 正确：使用绝对路径，如 /Users/username/server/index.js

第二步：手动运行测试

在终端中直接运行配置文件中的命令：

# Node.js Server
node /path/to/your/server/index.js

# 常见错误：Cannot find module
# → 解决：cd /path/to/server && npm install

# Python Server
python /path/to/server/main.py

# 常见错误：ModuleNotFoundError
# → 解决：pip install -r requirements.txt

# npx 方式
npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# 常见错误：npx: command not found
# → 解决：安装 Node.js 18+

第三步：检查依赖问题

Node.js

cd /path/to/server
npm install

Python

pip install -r requirements.txt

第四步：检查权限问题

# 添加执行权限
chmod +x /path/to/server/index.js

# 修改目录权限
chmod -R 755 /path/to/server

第五步：检查运行时版本

# Node.js 要求 18+
node --version

# Python 要求 3.10+
python --version

常见问题速查

错误信息	可能原因	解决方案
Cannot find module	依赖未安装	npm install
ENOENT: no such file	路径错误	使用绝对路径
Permission denied	权限不足	chmod +x
command not found	运行时未安装	安装 Node/Python
Process exited	代码错误	查看详细日志

验证修复

1. 手动运行测试，确认无错误
2. 重启 Claude Code
3. 输入 /mcp 检查工具列表

下一步

• MCP 连接超时排查
• 文件系统工具配置