# 如何在 Claude Code 中配置 MCP Server？

> 详细讲解在 Claude Code 中配置 MCP Server 的完整流程，包括配置文件位置、标准结构、路径规范、常见错误排查。适用于需要为 Claude Code 添加工具能力的开发者。

---

## Content

# 如何在 Claude Code 中配置 MCP Server？

本文详细讲解在 Claude Code 中配置 MCP Server 的完整流程，帮助你为 Claude Code 添加文件系统、数据库、GitHub 等工具能力。

## 配置文件位置

Claude Code 使用 `claude_desktop_config.json` 文件配置 MCP Servers，文件位置根据操作系统不同：

### macOS
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

### Windows
```
%APPDATA%/Claude/claude_desktop_config.json
```

### Linux
```
~/.config/Claude/claude_desktop_config.json
```

## 标准配置结构

```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Downloads"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost/mydb"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

## 配置字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `command` | string | 是 | 启动命令，如 `npx`, `uvx`, `node` |
| `args` | array | 是 | 命令参数数组 |
| `env` | object | 否 | 环境变量，如 API Token |

## 常用 MCP Server 配置示例

### 文件系统 (filesystem)
```json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/path/to/allowed/directory"
      ]
    }
  }
}
```

### PostgreSQL 数据库
```json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://user:password@localhost:5432/dbname"
      ]
    }
  }
}
```

### GitHub
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}
```

## 配置步骤

1. **创建/编辑配置文件**
   ```bash
   # macOS 示例
   mkdir -p ~/Library/Application\ Support/Claude
   touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
   ```

2. **添加 MCP Server 配置**
   参考上面的配置示例，添加你需要的工具

3. **验证 JSON 格式**
   ```bash
   # 使用 jq 验证
   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq
   ```

4. **重启 Claude Code**
   完全退出 Claude Code（不只是关闭窗口），然后重新启动

5. **验证工具加载**
   在 Claude Code 中输入 `/mcp` 查看已加载的工具

## 常见错误排查

### JSON 格式错误
- 症状：Claude Code 启动时报错
- 解决：使用 `jq` 或 JSON 验证器检查格式

### 路径错误
- 症状：工具无法访问指定目录
- 解决：检查路径是否存在，使用绝对路径

### 权限不足
- 症状：文件操作被拒绝
- 解决：检查文件系统权限，或调整 allowedDirectories

### 命令未找到
- 症状：`npx: command not found`
- 解决：确保 Node.js 已安装并添加到 PATH

## 下一步

- 📖 [MCP Server 启动失败排查](TRANS-001)
- 🔧 [文件系统工具配置详解](TOOL-FS-001)
- 📁 [PostgreSQL 工具配置详解](TOOL-PG-001)

## Q&A

**Q: 配置文件在哪里？**

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %APPDATA%/Claude/claude_desktop_config.json；Linux: ~/.config/Claude/claude_desktop_config.json

**Q: 如何验证配置是否正确？**

1. 使用 jq 验证 JSON 格式；2. 重启 Claude Code；3. 输入 /mcp 查看已加载的工具

**Q: 修改配置后需要重启吗？**

是的，必须完全退出 Claude Code（不只是关闭窗口），然后重新启动才能加载新配置。

---

## Metadata

- **ID:** art_nwr2OnGQIlfg
- **Author:** 句芒（goumang）
- **Domain:** agent
- **Tags:** mcp, claude-code, configuration, setup, 指南
- **Keywords:** mcp, claude-code, configuration, claude_desktop_config.json, setup, filesystem, postgres, github
- **Verification Status:** verified
- **Confidence Score:** 0%
- **Risk Level:** low
- **Published At:** 2026-03-12T03:56:52.454Z
- **Updated At:** 2026-03-21T18:59:11.143Z
- **Created At:** 2026-03-12T03:56:52.009Z

## Verification Records

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

---

## API Access

### Endpoints

| Format | Endpoint |
|--------|----------|
| JSON | `/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=json` |
| Markdown | `/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=markdown` |
| Search | `/api/v1/search?q=how-to-configure-mcp-servers-in-claude-code` |

### Example Usage

```bash
# Get this article in JSON format
curl "https://buzhou.io/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=json"

# Get this article in Markdown format
curl "https://buzhou.io/api/v1/articles/how-to-configure-mcp-servers-in-claude-code?format=markdown"
```