排查：MCP Connection Refused 或 Timeout 错误

当 MCP Server 启动成功但无法连接，或出现超时错误时，本文将帮助你排查网络层面的问题。

问题现象

• MCP Server 启动成功但工具无法调用
• 出现 "Connection refused" 错误
• 出现 "Timeout" 或 "ETIMEDOUT" 错误
• 连接不稳定，时好时坏

排查步骤

第一步：检查端口占用

检查端口是否被占用

# macOS/Linux
lsof -i :3000

# Windows
netstat -ano | findstr :3000

解决端口冲突

# 查找占用端口的进程
lsof -ti:3000 | xargs kill -9

# 或修改 MCP Server 使用其他端口

第二步：检查防火墙设置

macOS 防火墙

# 检查防火墙状态
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# 临时关闭防火墙测试
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off

检查应用权限

• 系统设置 → 隐私与安全 → 防火墙
• 确保 Claude Code 有网络访问权限

第三步：检查网络策略

代理设置

# 检查环境变量
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 临时取消代理测试
unset HTTP_PROXY
unset HTTPS_PROXY

VPN 冲突

• 某些 VPN 会拦截本地连接
• 尝试断开 VPN 后测试

第四步：检查 MCP Server 监听地址

检查 Server 配置

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "HOST": "127.0.0.1",
        "PORT": "3000"
      }
    }
  }
}

确保监听 localhost

• 检查 server 代码中是否监听 127.0.0.1 或 localhost
• 避免监听 0.0.0.0 可能导致的问题

第五步：测试连接

使用 curl 测试

# 测试 HTTP MCP Server
curl http://localhost:3000/health

# 测试 SSE 连接
curl http://localhost:3000/sse

使用 nc 测试端口

# 测试端口是否开放
nc -zv localhost 3000

常见错误速查

错误信息	可能原因	解决方案
Connection refused	端口未监听/防火墙	检查服务状态、关闭防火墙测试
ETIMEDOUT	网络超时	检查网络、代理设置
ECONNRESET	连接被重置	检查 server 日志、重启服务
socket hang up	连接异常关闭	检查 server 稳定性

验证修复

1. 使用 nc 或 curl 测试端口连通性
2. 重启 Claude Code
3. 测试工具调用是否正常

下一步

• Python 环境排错
• Node.js 环境排错
• 文件系统工具配置