# 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。

### 挂载文件系统

让 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": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github"],
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<set by your secret manager at process launch>"
  }
}
```

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

## 4.3.4 调试与故障排除

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

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

启动 Claude 后，点击输入框右下角的“插头”图标🔌。

* 如果图标有一个绿点，说明连接正常。
* 点击图标可以看到已加载的工具列表（如 `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 <你的启动命令>
```

它会启动一个网页界面，可以像使用 Postman 一样手动发送 MCP 请求并查看响应，而无需打开 Claude。

***

配置好了，怎么用呢？其实对于用户来说，只要像往常一样说话就行。但如何将多个 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，但生产部署必须考虑自动化生命周期管理。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://yeasy.gitbook.io/claude_guide/di-er-bu-fen-gong-ju-pian/04_mcp/4.3_config.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.