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

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:

# 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

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

Step 4: Check Permissions

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

Step 5: Check Runtime Version

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
• Filesystem Configuration