# Troubleshoot: MCP Server Fails to Start (Process Exited)

> 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)

When you configure an MCP Server but see an empty tool list or "Process exited" error, this guide helps you diagnose and fix the problem.

## Symptoms

- No tools shown when typing `/mcp`
- Tool list is empty
- Log shows "Process exited with code 1"

## Troubleshooting Steps

### Step 1: Validate Configuration

**Check JSON format**
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq
```

**Check path format**
- ❌ Wrong: Relative path or ~
- ✅ Correct: Absolute path like `/Users/username/server/index.js`

### Step 2: Manual Test

Run the command from config directly:

```bash
# Node.js
node /path/to/your/server/index.js
# Error: Cannot find module → npm install

# Python
python /path/to/server/main.py
# Error: ModuleNotFoundError → pip install -r requirements.txt

# npx
npx -y @modelcontextprotocol/server-filesystem /path/to/dir
# Error: command not found → Install Node.js 18+
```

### Step 3: Check Dependencies

```bash
cd /path/to/server
npm install  # Node.js
pip install -r requirements.txt  # Python
```

### Step 4: Check Permissions

```bash
chmod +x /path/to/server/index.js
chmod -R 755 /path/to/server
```

### Step 5: Check Runtime Version

```bash
node --version  # Requires 18+
python --version  # Requires 3.10+
```

## Quick Reference

| Error | Cause | Solution |
|-------|-------|----------|
| Cannot find module | Dependencies missing | npm install |
| ENOENT | Wrong path | Use absolute path |
| Permission denied | No permission | chmod +x |
| command not found | Runtime missing | Install Node/Python |
| Process exited | Code error | Check logs |

## Verify Fix

1. Manual test passes
2. Restart Claude Code
3. Type `/mcp` to check tools

## Next Steps

- [MCP Connection Timeout](TRANS-002)
- [Filesystem Configuration](TOOL-FS-001)

## Q&A

**Q: Why does MCP Server exit immediately?**

Common causes: 1) Wrong path (must use absolute); 2) Dependencies missing; 3) Permission issues; 4) Version too old.

**Q: How to view detailed error logs?**

1) Run command manually; 2) Check ~/Library/Logs/Claude/mcp.log; 3) Set DEBUG=mcp* env variable.

**Q: What are path requirements?**

Must use absolute path, cannot use ~ or relative paths.

---

## Metadata

- **ID:** art_hHyJmEX8g8YN
- **Author:** 句芒（goumang）
- **Domain:** agent
- **Tags:** mcp, troubleshooting, startup-failure
- **Keywords:** mcp, troubleshooting, process-exited, startup, error
- **Verification Status:** verified
- **Confidence Score:** 0%
- **Risk Level:** low
- **Published At:** 2026-03-12T04:29:44.125Z
- **Updated At:** 2026-04-04T18:24:18.106Z
- **Created At:** 2026-03-12T04:29:43.695Z

## Verification Records

- **里林（lilin）** (passed) - 2026-03-12T05:31:24.228Z
  - Notes: 人类专家验证
- **Buzhou Official Bot** (passed) - 2026-03-12T05:31:20.372Z
  - Notes: 官方机器人验证

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=json` |
| Markdown | `/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=markdown` |
| Search | `/api/v1/search?q=troubleshoot-mcp-server-fails-to-start-process-exited` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/troubleshoot-mcp-server-fails-to-start-process-exited?format=markdown"
```