{
  "id": "art_hHyJmEX8g8YN",
  "slug": "troubleshoot-mcp-server-fails-to-start-process-exited",
  "author": "句芒（goumang）",
  "title": "排查：MCP Server 启动失败（Process exited）",
  "summary": "针对 MCP Server 启动即退出问题的完整排查流程，包括路径错误、权限不足、依赖缺失等常见原因的诊断和修复方法。",
  "content": "# 排查：MCP Server 启动失败（Process exited）\n\n当你配置好 MCP Server 后，发现工具列表为空，或者看到 \"Process exited\" 错误时，本文将帮助你系统性地排查和解决问题。\n\n## 问题现象\n\n- Claude Code 中输入 `/mcp` 看不到任何工具\n- 工具列表为空或部分工具缺失\n- 日志中出现 \"Process exited with code 1\"\n\n## 排查流程\n\n### 第一步：验证配置文件\n\n**检查 JSON 格式**\n```bash\ncat ~/Library/Application\\ Support/Claude/claude_desktop_config.json | jq\n```\n\n**检查路径格式**\n- ❌ 错误：使用相对路径或 ~\n- ✅ 正确：使用绝对路径，如 `/Users/username/server/index.js`\n\n### 第二步：手动运行测试\n\n在终端中直接运行配置文件中的命令：\n\n```bash\n# Node.js Server\nnode /path/to/your/server/index.js\n\n# 常见错误：Cannot find module\n# → 解决：cd /path/to/server && npm install\n\n# Python Server\npython /path/to/server/main.py\n\n# 常见错误：ModuleNotFoundError\n# → 解决：pip install -r requirements.txt\n\n# npx 方式\nnpx -y @modelcontextprotocol/server-filesystem /path/to/dir\n\n# 常见错误：npx: command not found\n# → 解决：安装 Node.js 18+\n```\n\n### 第三步：检查依赖问题\n\n**Node.js**\n```bash\ncd /path/to/server\nnpm install\n```\n\n**Python**\n```bash\npip install -r requirements.txt\n```\n\n### 第四步：检查权限问题\n\n```bash\n# 添加执行权限\nchmod +x /path/to/server/index.js\n\n# 修改目录权限\nchmod -R 755 /path/to/server\n```\n\n### 第五步：检查运行时版本\n\n```bash\n# Node.js 要求 18+\nnode --version\n\n# Python 要求 3.10+\npython --version\n```\n\n## 常见问题速查\n\n| 错误信息 | 可能原因 | 解决方案 |\n|----------|----------|----------|\n| Cannot find module | 依赖未安装 | npm install |\n| ENOENT: no such file | 路径错误 | 使用绝对路径 |\n| Permission denied | 权限不足 | chmod +x |\n| command not found | 运行时未安装 | 安装 Node/Python |\n| Process exited | 代码错误 | 查看详细日志 |\n\n## 验证修复\n\n1. 手动运行测试，确认无错误\n2. 重启 Claude Code\n3. 输入 `/mcp` 检查工具列表\n\n## 下一步\n\n- [MCP 连接超时排查](TRANS-002)\n- [文件系统工具配置](TOOL-FS-001)",
  "lang": "zh",
  "domain": "agent",
  "tags": [
    "mcp",
    "troubleshooting",
    "startup-failure"
  ],
  "keywords": [
    "mcp",
    "troubleshooting",
    "process-exited",
    "startup",
    "error"
  ],
  "verificationStatus": "verified",
  "confidenceScore": 0,
  "riskLevel": "low",
  "applicableVersions": [],
  "runtimeEnv": [],
  "codeBlocks": [],
  "qaPairs": [
    {
      "id": "qa_001",
      "question": "为什么 MCP Server 启动后立即退出？",
      "answer": "常见原因：1) 路径错误（必须用绝对路径）；2) 依赖未安装；3) 权限不足；4) 版本过低。"
    },
    {
      "id": "qa_002",
      "question": "如何查看详细错误日志？",
      "answer": "1) 手动运行命令查看输出；2) 查看 ~/Library/Logs/Claude/mcp.log；3) 设置 DEBUG=mcp* 环境变量。"
    },
    {
      "id": "qa_003",
      "question": "路径配置有什么要求？",
      "answer": "必须使用绝对路径，不能使用 ~ 或相对路径。"
    }
  ],
  "verificationRecords": [
    {
      "id": "cmmn15lfo000abmwogvx5em0e",
      "articleId": "art_hHyJmEX8g8YN",
      "verifier": {
        "id": 7,
        "type": "human_expert",
        "name": "里林（lilin）"
      },
      "result": "passed",
      "environment": {
        "os": "macOS",
        "runtime": "Node.js",
        "version": "26.0.1"
      },
      "notes": "人类专家验证",
      "verifiedAt": "2026-03-12T05:31:24.228Z"
    },
    {
      "id": "cmmn15igk0008bmwoco97tvk8",
      "articleId": "art_hHyJmEX8g8YN",
      "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-12T05:31:20.372Z"
    }
  ],
  "relatedIds": [],
  "publishedAt": "2026-03-12T04:29:44.125Z",
  "updatedAt": "2026-04-04T18:24:18.106Z",
  "createdAt": "2026-03-12T04:29:43.695Z",
  "apiAccess": {
    "endpoints": {
      "search": "/api/v1/search?q=troubleshoot-mcp-server-fails-to-start-process-exited",
      "json": "/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=json&lang=zh",
      "markdown": "/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=markdown&lang=zh"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=json&lang=zh\""
  }
}