> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/claude_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp/4.3_config.md).

# 4.3 配置与实战指南

下面动手实践，在 Claude Desktop App 中通过 MCP 挂载几个强大的工具。

## 4.3.1 配置文件解析

Claude Desktop 通过一个 JSON 配置文件来管理所有的 MCP 连接。

### 配置文件位置

不同操作系统的路径如下：

* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

可以通过 VS Code 或任何文本编辑器打开它。如果文件不存在，请手动创建一个。

### 配置格式

文件的核心结构是一个名为 `mcpServers` 的对象。

```jsonc
{
  "mcpServers": {
    "server-name-1": {
      "command": "executable-command",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "VALUE"
      }
    },
    "server-name-2": { ... }
  }
}
```

* **Key (`server-name-1`)**: 自定义名称，方便识别。
* **command**: 启动 Server 的可执行程序（通常是 `npx`, `uvx`, `docker` 或 python 脚本路径）。
* **args**: 传递给命令的参数列表。
* **env**:（可选）传递给 Server 进程的环境变量（常用于传递 API Key）。

## 4.3.2 实战案例：打造全能工作台

下面将配置三个极其常用的 MCP Server：文件系统、SQLite 数据库和 Git。以下 JSON 都是 `mcpServers` 对象内部的条目片段；复制到完整配置文件时，需要放在 `{ "mcpServers": { ... } }` 里面。

### 挂载文件系统

让 Claude 能够读写指定的本地目录。

```jsonc
"filesystem": {
  "command": "npx",
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "/Users/username/Desktop",
    "/Users/username/Projects"
  ]
}
```

*注意：上例允许访问桌面和项目目录。将 `/Users/username` 替换为真实路径；出于安全考虑，请只挂载必要的目录，不要挂载根目录。*

### 连接 SQLite 数据库

让 Claude 甚至可以直接查询本地的 `.db` 文件进行数据分析。

```jsonc
"sqlite": {
  "command": "uvx",
  "args": [
    "mcp-server-sqlite",
    "--db-path",
    "/Users/username/data/chinook.db"
  ]
}
```

*注意：`uvx` 用于运行 Python 包；最后一个参数是你的 SQLite 数据库文件路径。*

### 集成 Git

让 Claude 可以查看提交记录、Diff，甚至帮忙创建 Commit。

```jsonc
"git": {
  "command": "python3",
  "args": [
    "-m",
    "mcp_server_git",
    "--repository",
    "/Users/username/Projects/my-app"
  ]
}
```

*注意：最后一个参数是 Git 仓库路径。*

## 4.3.3 环境变量与安全

很多 Server（如 GitHub, Slack, Postgres）需要认证。**不要把密码写在 `args` 里，也不要把真实 token 提交到 MCP 配置文件**。优先用操作系统密钥链、CI secret、企业 secret manager 或只保存在本机且已加入 `.gitignore` 的环境文件，在启动 MCP server 时注入最小权限凭据。

```jsonc
"github": {
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
    "ghcr.io/github/github-mcp-server"
  ],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<set by your secret manager at process launch>"
  }
}
```

*注意：早期教程常用的 `@modelcontextprotocol/server-github`（`npx` 方式）已于 2025 年随官方参考实现仓库归档、npm 包停止维护，上例改用 GitHub 官方的* [*github-mcp-server*](https://github.com/github/github-mcp-server)*（Docker 本地运行）。GitHub 还提供托管远程端点 `https://api.githubcopilot.com/mcp/`（OAuth 认证），支持远程 MCP 的客户端可直接连接。*

示例中的占位符不是 token 格式，不能替换为真实密钥后提交。GitHub PAT 应限制到当前 server 实际需要的仓库和 scopes，并定期轮换。

## 4.3.4 调试与故障排除

配置完成后，**必须重启 Claude Desktop** 才能生效。

### 怎么知道连接成功了？

启动 Claude 后，点击输入框右下角的 MCP 服务器指示图标（官方文档描述为“滑块”状图标；具体样式随版本可能微调）。

* 点击图标可以看到已加载的 Server 与工具列表（如 `read_file`, `query_table` 等）；列表中出现即表示连接正常。

### 常见错误排查

1. **“Connection failed”**: 检查 `command` 是否存在。例如 `npx` 需要安装 Node.js，`uvx` 需要安装 uv。
   * *Tip*: 在终端里手动运行由 `command` + `args` 组成的命令，看是否有报错。
2. **“ENOENT” / “File not found”**: 检查 `args` 里的绝对路径是否正确。不要使用 `~` 符号，尽量使用完整路径 `/Users/...`。
3. **“Permission denied”**: 某些目录需要特殊权限。

## 4.3.5 使用 MCP Inspector

如果正在开发自己的 Server，或者仅仅想看看 Server 到底发了什么数据，可以使用官方的调试工具 **MCP Inspector**。

```bash
npx @modelcontextprotocol/inspector python weather_server.py
```

它会启动一个网页界面，可以像使用 Postman 一样手动发送 MCP 请求并查看响应，而无需打开 Claude。把示例中的 `python weather_server.py` 替换成你自己的 server 启动命令。

***

配置好了，怎么用呢？其实对于用户来说，只要像往常一样说话就行。但如何将多个 MCP Server 组合起来发挥最大威力？

➡️ [场景化实战：MCP 的组合拳](/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp/4.4_practice.md)

***

> **🔥 踩坑实录**
>
> 某团队配置了一个 MCP 服务器用于数据库查询，在 Claude Desktop 中测试一切正常，能顺利执行数据库查询工具。但当把配置部署到无头服务器环境（Headless Server）后，MCP 连接始终失败。排查发现：Claude Desktop 会自动管理 MCP 服务器进程的生命周期（启动、保活），但在无头服务器环境中没有 Desktop App，MCP 进程需要手动启动并维持运行。最终通过 systemd 服务单元来管理 MCP 进程，并配置健康检查和自动重启，问题才解决。教训：MCP Server 的运维方式随场景而异，开发测试可依赖 Desktop，但生产部署必须考虑自动化生命周期管理。