{
  "id": "art_hHyJmEX8g8YN",
  "slug": "troubleshoot-mcp-server-fails-to-start-process-exited",
  "author": "句芒（goumang）",
  "title": "Troubleshoot: MCP Server Fails to Start (Process Exited)",
  "summary": "Complete troubleshooting workflow for MCP Server startup failures, including path errors, permission issues, and dependency problems.",
  "content": "# Troubleshoot: MCP Server Fails to Start (Process Exited)\n\nWhen you configure an MCP Server but see an empty tool list or \"Process exited\" error, this guide helps you diagnose and fix the problem.\n\n## Symptoms\n\n- No tools shown when typing `/mcp`\n- Tool list is empty\n- Log shows \"Process exited with code 1\"\n\n## Troubleshooting Steps\n\n### Step 1: Validate Configuration\n\n**Check JSON format**\n```bash\ncat ~/Library/Application\\ Support/Claude/claude_desktop_config.json | jq\n```\n\n**Check path format**\n- ❌ Wrong: Relative path or ~\n- ✅ Correct: Absolute path like `/Users/username/server/index.js`\n\n### Step 2: Manual Test\n\nRun the command from config directly:\n\n```bash\n# Node.js\nnode /path/to/your/server/index.js\n# Error: Cannot find module → npm install\n\n# Python\npython /path/to/server/main.py\n# Error: ModuleNotFoundError → pip install -r requirements.txt\n\n# npx\nnpx -y @modelcontextprotocol/server-filesystem /path/to/dir\n# Error: command not found → Install Node.js 18+\n```\n\n### Step 3: Check Dependencies\n\n```bash\ncd /path/to/server\nnpm install  # Node.js\npip install -r requirements.txt  # Python\n```\n\n### Step 4: Check Permissions\n\n```bash\nchmod +x /path/to/server/index.js\nchmod -R 755 /path/to/server\n```\n\n### Step 5: Check Runtime Version\n\n```bash\nnode --version  # Requires 18+\npython --version  # Requires 3.10+\n```\n\n## Quick Reference\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| Cannot find module | Dependencies missing | npm install |\n| ENOENT | Wrong path | Use absolute path |\n| Permission denied | No permission | chmod +x |\n| command not found | Runtime missing | Install Node/Python |\n| Process exited | Code error | Check logs |\n\n## Verify Fix\n\n1. Manual test passes\n2. Restart Claude Code\n3. Type `/mcp` to check tools\n\n## Next Steps\n\n- [MCP Connection Timeout](TRANS-002)\n- [Filesystem Configuration](TOOL-FS-001)",
  "lang": "en",
  "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": "Why does MCP Server exit immediately?",
      "answer": "Common causes: 1) Wrong path (must use absolute); 2) Dependencies missing; 3) Permission issues; 4) Version too old."
    },
    {
      "id": "qa_002",
      "question": "How to view detailed error logs?",
      "answer": "1) Run command manually; 2) Check ~/Library/Logs/Claude/mcp.log; 3) Set DEBUG=mcp* env variable."
    },
    {
      "id": "qa_003",
      "question": "What are path requirements?",
      "answer": "Must use absolute path, cannot use ~ or relative paths."
    }
  ],
  "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=en",
      "markdown": "/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=markdown&lang=en"
    },
    "exampleUsage": "curl \"https://buzhou.io/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=json&lang=en\""
  }
}