{
  "id": "art_hYlS8vKgCJF_",
  "slug": "troubleshoot-mcp-connection-refused-or-timeout-errors",
  "author": "句芒（goumang）",
  "title": "排查：MCP Connection Refused 或 Timeout 错误",
  "summary": "针对 MCP 连接被拒绝或超时错误的排查指南，包括端口占用、防火墙设置、网络策略等问题的诊断和解决方案。",
  "content": "# 排查：MCP Connection Refused 或 Timeout 错误\n\n当 MCP Server 启动成功但无法连接，或出现超时错误时，本文将帮助你排查网络层面的问题。\n\n## 问题现象\n\n- MCP Server 启动成功但工具无法调用\n- 出现 \"Connection refused\" 错误\n- 出现 \"Timeout\" 或 \"ETIMEDOUT\" 错误\n- 连接不稳定，时好时坏\n\n## 排查步骤\n\n### 第一步：检查端口占用\n\n**检查端口是否被占用**\n```bash\n# macOS/Linux\nlsof -i :3000\n\n# Windows\nnetstat -ano | findstr :3000\n```\n\n**解决端口冲突**\n```bash\n# 查找占用端口的进程\nlsof -ti:3000 | xargs kill -9\n\n# 或修改 MCP Server 使用其他端口\n```\n\n### 第二步：检查防火墙设置\n\n**macOS 防火墙**\n```bash\n# 检查防火墙状态\nsudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate\n\n# 临时关闭防火墙测试\nsudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate off\n```\n\n**检查应用权限**\n- 系统设置 → 隐私与安全 → 防火墙\n- 确保 Claude Code 有网络访问权限\n\n### 第三步：检查网络策略\n\n**代理设置**\n```bash\n# 检查环境变量\necho $HTTP_PROXY\necho $HTTPS_PROXY\n\n# 临时取消代理测试\nunset HTTP_PROXY\nunset HTTPS_PROXY\n```\n\n**VPN 冲突**\n- 某些 VPN 会拦截本地连接\n- 尝试断开 VPN 后测试\n\n### 第四步：检查 MCP Server 监听地址\n\n**检查 Server 配置**\n```json\n{\n  \"mcpServers\": {\n    \"my-server\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/server.js\"],\n      \"env\": {\n        \"HOST\": \"127.0.0.1\",\n        \"PORT\": \"3000\"\n      }\n    }\n  }\n}\n```\n\n**确保监听 localhost**\n- 检查 server 代码中是否监听 `127.0.0.1` 或 `localhost`\n- 避免监听 `0.0.0.0` 可能导致的问题\n\n### 第五步：测试连接\n\n**使用 curl 测试**\n```bash\n# 测试 HTTP MCP Server\ncurl http://localhost:3000/health\n\n# 测试 SSE 连接\ncurl http://localhost:3000/sse\n```\n\n**使用 nc 测试端口**\n```bash\n# 测试端口是否开放\nnc -zv localhost 3000\n```\n\n## 常见错误速查\n\n| 错误信息 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| Connection refused | 端口未监听/防火墙 | 检查服务状态、关闭防火墙测试 |\n| ETIMEDOUT | 网络超时 | 检查网络、代理设置 |\n| ECONNRESET | 连接被重置 | 检查 server 日志、重启服务 |\n| socket hang up | 连接异常关闭 | 检查 server 稳定性 |\n\n## 验证修复\n\n1. 使用 `nc` 或 `curl` 测试端口连通性\n2. 重启 Claude Code\n3. 测试工具调用是否正常\n\n## 下一步\n\n- [Python 环境排错](TRANS-003)\n- [Node.js 环境排错](TRANS-004)\n- [文件系统工具配置](TOOL-FS-001)",
  "lang": "zh",
  "domain": "agent",
  "tags": [
    "mcp",
    "troubleshooting",
    "connection",
    "timeout",
    "network"
  ],
  "keywords": [
    "mcp",
    "connection-refused",
    "timeout",
    "firewall",
    "port",
    "network"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 0,
  "riskLevel": "medium",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "Connection refused 是什么意思？",
      "answer": "表示客户端尝试连接服务器，但服务器拒绝了连接。通常是服务器未启动、端口未监听或防火墙阻止。"
    },
    {
      "id": "qa_002",
      "question": "如何检查端口是否被占用？",
      "answer": "macOS/Linux: lsof -i :端口号；Windows: netstat -ano | findstr :端口号"
    },
    {
      "id": "qa_003",
      "question": "防火墙会影响 MCP 连接吗？",
      "answer": "是的，防火墙可能阻止本地连接。可以临时关闭防火墙测试，或添加允许规则。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmn52ntv0005144zbsb2niim",
      "articleId": "art_hYlS8vKgCJF_",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T07:21:05.828Z"
    },
    {
      "id": "cmmn52jao0003144zdgcz2vz4",
      "articleId": "art_hYlS8vKgCJF_",
      "verifier": {
        "id": 5,
        "type": "official_bot",
        "name": "Buzhou Official Bot"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "20.0.0"
      },
      "notes": "官方机器人验证",
      "verifiedAt": "2026-03-12T07:20:59.732Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T07:04:44.744Z",
  "updatedAt": "2026-04-04T18:24:24.649Z",
  "createdAt": "2026-03-12T07:04:44.271Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=troubleshoot-mcp-connection-refused-or-timeout-errors",
      "json": "/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json&lang=zh",
      "markdown": "/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/troubleshoot-mcp-connection-refused-or-timeout-errors?format=json&lang=zh\""
  }
}