# 排查：MCP Server 启动失败（Process exited）

> 针对 MCP Server 启动即退出问题的完整排查流程，包括路径错误、权限不足、依赖缺失等常见原因的诊断和修复方法。

---

## Content

# 排查：MCP Server 启动失败（Process exited）

当你配置好 MCP Server 后，发现工具列表为空，或者看到 "Process exited" 错误时，本文将帮助你系统性地排查和解决问题。

## 问题现象

- Claude Code 中输入 `/mcp` 看不到任何工具
- 工具列表为空或部分工具缺失
- 日志中出现 "Process exited with code 1"

## 排查流程

### 第一步：验证配置文件

**检查 JSON 格式**
```bash
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq
```

**检查路径格式**
- ❌ 错误：使用相对路径或 ~
- ✅ 正确：使用绝对路径，如 `/Users/username/server/index.js`

### 第二步：手动运行测试

在终端中直接运行配置文件中的命令：

```bash
# Node.js Server
node /path/to/your/server/index.js

# 常见错误：Cannot find module
# → 解决：cd /path/to/server && npm install

# Python Server
python /path/to/server/main.py

# 常见错误：ModuleNotFoundError
# → 解决：pip install -r requirements.txt

# npx 方式
npx -y @modelcontextprotocol/server-filesystem /path/to/dir

# 常见错误：npx: command not found
# → 解决：安装 Node.js 18+
```

### 第三步：检查依赖问题

**Node.js**
```bash
cd /path/to/server
npm install
```

**Python**
```bash
pip install -r requirements.txt
```

### 第四步：检查权限问题

```bash
# 添加执行权限
chmod +x /path/to/server/index.js

# 修改目录权限
chmod -R 755 /path/to/server
```

### 第五步：检查运行时版本

```bash
# Node.js 要求 18+
node --version

# Python 要求 3.10+
python --version
```

## 常见问题速查

| 错误信息 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Cannot find module | 依赖未安装 | npm install |
| ENOENT: no such file | 路径错误 | 使用绝对路径 |
| Permission denied | 权限不足 | chmod +x |
| command not found | 运行时未安装 | 安装 Node/Python |
| Process exited | 代码错误 | 查看详细日志 |

## 验证修复

1. 手动运行测试，确认无错误
2. 重启 Claude Code
3. 输入 `/mcp` 检查工具列表

## 下一步

- [MCP 连接超时排查](TRANS-002)
- [文件系统工具配置](TOOL-FS-001)

## Q&A

**Q: 为什么 MCP Server 启动后立即退出？**

常见原因：1) 路径错误（必须用绝对路径）；2) 依赖未安装；3) 权限不足；4) 版本过低。

**Q: 如何查看详细错误日志？**

1) 手动运行命令查看输出；2) 查看 ~/Library/Logs/Claude/mcp.log；3) 设置 DEBUG=mcp* 环境变量。

**Q: 路径配置有什么要求？**

必须使用绝对路径，不能使用 ~ 或相对路径。

---

## 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"
```