--- title: "在 Claude Desktop 中配置 MCP" wiki: mcp category: "客户端集成" slug: claude-desktop-setup url: https://learnagent.wiki/mcp/cards/claude-desktop-setup tags: ["MCP", "Claude Desktop", "配置", "入门", "macOS", "Windows"] last_updated: 2026-04-11 reading_time: 12 --- > Claude Desktop 是 Anthropic 官方的桌面客户端（macOS / Windows），也是最早支持 MCP 的 Host 之一。它内置了完整的 MCP Client 实现，你只需要在一个 JSON 配置文件里写几行，就能让 Claude 连上各种 MCP Server——读写文件、查 GitHub、搜索网页、操作数据库，全部在对话框里完成。 # 在 Claude Desktop 中配置 MCP ## 基础概念 Claude Desktop 是 Anthropic 官方的桌面客户端（macOS / Windows），也是最早支持 MCP 的 Host 之一。它内置了完整的 MCP Client 实现，你只需要在一个 JSON 配置文件里写几行，就能让 Claude 连上各种 MCP Server——读写文件、查 GitHub、搜索网页、操作数据库，全部在对话框里完成。 整个过程可以用一句话概括：**编辑配置文件 → 重启 Claude Desktop → 开始对话**。不需要写代码，不需要部署服务。 ### 核心要素 | 要素 | 说明 | |------|------| | **配置文件** | `claude_desktop_config.json`，告诉 Claude Desktop 要启动哪些 Server | | **Server 启动方式** | Host 读取配置后自动 spawn 子进程（本地 Server）或连接 URL（远程 Server） | | **传输方式** | 本地 Server 默认使用 stdio，远程 Server 使用 Streamable HTTP | | **工具发现** | 启动后 Claude Desktop 自动从所有 Server 收集工具列表，合并展示 | | **用户确认** | 每次模型要调用工具时，会先弹出确认框，你可以批准或拒绝 | ### 从配置到运行的完整流程 ```mermaid graph LR A["📝 编辑配置文件"] --> B["🔄 重启 Claude Desktop"] B --> C["⚙️ Host 自动启动 Server"] C --> D["🤝 能力协商（initialize）"] D --> E["🔨 工具列表就绪"] E --> F["💬 用户开始对话"] F --> G["🤖 模型决定调工具"] G --> H["✅ 用户确认"] H --> I["📤 执行并返回结果"] ``` ## 基础用法 ### 第一步：检查前置条件 | 条件 | 检查方式 | 说明 | |------|---------|------| | Claude Desktop | 已安装最新版 | 从 [claude.ai/download](https://claude.ai/download) 下载，菜单栏点 Claude → "Check for Updates..." 确认最新 | | Node.js | 终端运行 `node --version` | 需要 v18+，从 [nodejs.org](https://nodejs.org/) 下载 LTS 版本 | ### 第二步：找到配置文件 配置文件路径因操作系统而异： | 操作系统 | 配置文件路径 | |---------|-------------| | **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` | | **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` | **快捷打开方式**：在 Claude Desktop 里点菜单栏 **Claude → Settings → Developer → Edit Config**，会自动打开配置文件（如果不存在会自动创建）。 ### 第三步：写配置 下面是一个最简单的配置——挂载官方 Filesystem Server，让 Claude 能读写你桌面和下载文件夹的文件： **macOS 版本：** ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名/Desktop", "/Users/你的用户名/Downloads" ] } } } ``` **Windows 版本：** ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\你的用户名\\Desktop", "C:\\Users\\你的用户名\\Downloads" ] } } } ``` 每个字段的含义： - `"filesystem"`：你给这个 Server 起的名字，随便写，方便自己识别就行 - `"command": "npx"`：启动命令，用 Node.js 的 npx 来运行 - `"-y"`：自动确认安装 npm 包，不需要手动输 yes - `"@modelcontextprotocol/server-filesystem"`：Server 的 npm 包名 - 后面的路径：**这个 Server 被允许访问的目录**，只配了桌面和下载，其他目录 Server 读不到 > **安全提醒**：只授权你确实想让 Claude 访问的目录。Server 以你的系统账户权限运行，可以对授权目录进行读写操作。 ### 第四步：重启并验证 1. **完全退出** Claude Desktop（不是最小化，是 Quit/退出） 2. 重新打开 Claude Desktop 3. 看对话输入框右下角，应该出现一个 **MCP 图标**（锤子/滑块样式） 4. 点击这个图标，能看到 Filesystem Server 暴露的工具列表（如 `read_file`、`write_file`、`list_directory`、`search_files` 等） 如果图标没出现，跳到下面的"常见排查"部分。 ### 第五步：试一下 在对话框里输入： ```text 帮我看一下桌面上有哪些文件？ ``` Claude 会请求调用 `list_directory` 工具，弹出确认框让你批准。点击"Allow"后，Claude 就能列出你桌面的文件了。 ### 进阶：配置多个 Server + 环境变量 实际使用中你往往会同时挂多个 Server。下面是一个配了 3 个 Server 的完整示例： ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects" ] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx" } }, "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "BSAxxxxxxxxxxxxxxxx" } } } } ``` 几个要点： - **`env` 字段**：用来传环境变量。很多 Server 需要 API Key，通过 `env` 传入比写命令行参数更安全 - **多个 Server 互不干扰**：Claude Desktop 会为每个 Server 创建独立的 Client 实例，一个 Server 崩了不影响其他的 - **工具自动合并**：Claude 在对话中看到的是所有 Server 的工具合集。当你说"帮我在 GitHub 上搜一下 xxx 项目的 README，下载到本地"，Claude 可能会先调 GitHub Server 再调 Filesystem Server，跨 Server 协作 ### 日志排查 出问题时，先看日志： | 操作系统 | 日志路径 | |---------|---------| | **macOS** | `~/Library/Logs/Claude/` | | **Windows** | `%APPDATA%\Claude\logs\` | - `mcp.log`：MCP 连接的总日志（连接成功/失败） - `mcp-server-<名字>.log`：某个 Server 的 stderr 输出（报错信息在这里） macOS 上快速查看最近日志： ```bash tail -n 20 -f ~/Library/Logs/Claude/mcp*.log ``` ### 常见配置问题速查 | 现象 | 排查步骤 | |------|---------| | 重启后没有 MCP 图标 | ① 检查 JSON 语法（多余逗号、缺少引号是最常见的）② 检查 `command` 路径是否正确 ③ 看 `mcp.log` | | 图标出现但工具列表为空 | Server 启动了但没有注册任何 Tool。看 `mcp-server-xxx.log` 有没有报错 | | 工具调用失败 | ① 看 Server 日志 ② 在终端手动运行 Server 命令试试 ③ 检查环境变量是否正确 | | Windows 上报 ENOENT 错误 | 在 `env` 里加上 `"APPDATA": "C:\\Users\\你的用户名\\AppData\\Roaming\\"` | | `npx` 找不到 | 确保 Node.js 已安装并在 PATH 中。Windows 用户可能需要先运行 `npm install -g npm` | **终极排查法**：在终端手动运行 Server 命令，看它是否能正常启动： ```bash # macOS / Linux npx -y @modelcontextprotocol/server-filesystem /Users/你的用户名/Desktop # Windows（PowerShell） npx -y @modelcontextprotocol/server-filesystem C:\Users\你的用户名\Desktop ``` 如果这条命令本身就报错，说明是 Server 或 Node.js 的问题，不是 Claude Desktop 的问题。 ## 同类工具对比 Claude Desktop 不是唯一支持 MCP 的客户端，下面是几个主流选择： | 维度 | Claude Desktop | Claude Code（CLI） | Cursor | VS Code (Copilot Chat) | |------|---------------|-------------------|--------|----------------------| | 形态 | 桌面 GUI 应用 | 终端命令行 | IDE | IDE 插件 | | 配置方式 | 编辑 JSON 文件 | `claude mcp add` 命令 | Settings UI | `settings.json` | | 支持 Tools | ✅ | ✅ | ✅ | ✅ | | 支持 Resources | ✅ | ✅ | 部分 | 部分 | | 支持 Prompts | ✅ | ✅ | ❌ | ❌ | | 支持 Sampling | ✅ | ✅ | ❌ | ❌ | | 适合谁 | 日常对话、轻量办公 | 开发者、终端用户 | 开发者（写代码） | 开发者（写代码） | 核心区别： - **Claude Desktop**：最完整的 MCP 支持（Tools + Resources + Prompts + Sampling 全覆盖），适合非开发者和日常使用 - **Claude Code**：开发者首选，在终端里用 `claude mcp add ` 一行命令配 Server，不需要手动编辑 JSON - **Cursor / VS Code**：专注代码场景，MCP 支持主要服务于编程工作流 ## 常见误区 | 误区 | 准确理解 | |------|----------| | 以为需要手动安装 MCP Server | 不需要。配置里写了 `npx -y @modelcontextprotocol/server-xxx`，`npx` 会自动下载并运行，你不需要提前 `npm install` | | 以为改了配置立刻生效 | 必须**完全退出并重启** Claude Desktop，不是关闭窗口，是 Quit。配置在启动时读取 | | 以为 Claude 会静默执行工具 | 每次工具调用都会弹出确认框（除非你勾了"本次对话自动允许"），你拥有完全控制权 | | 以为路径可以用相对路径 | 配置里的路径必须是**绝对路径**。`~/Desktop` 在某些环境下不会展开，建议写完整路径 | | 以为配置文件只能手动编辑 | 可以在 Claude Desktop 里通过 Claude → Settings → Developer → Edit Config 打开，不需要自己找文件 | | 以为需要 Claude Pro 才能用 MCP | 免费版 Claude Desktop 也支持 MCP，不需要付费订阅 | ## 优劣势分析 | 优势 | 劣势 | |------|------| | **5 分钟上手**：编辑一个 JSON 文件、重启，就能用。零代码门槛 | **没有图形化配置界面**：需要手动编辑 JSON，对完全不懂编程的人有一点门槛（但 Settings → Developer → Edit Config 已经把打开文件这步简化了） | | **MCP 支持最完整**：Tools、Resources、Prompts、Sampling 全覆盖 | **每次改配置都要重启**：不能热加载，加了新 Server 必须 Quit 再打开 | | **安全的确认机制**：每个工具调用都需要用户批准，不会静默执行危险操作 | **只支持 macOS 和 Windows**：Linux 用户需要用 Claude Code 或第三方客户端 | | **多 Server 并行**：可以同时挂 10+ 个 Server，工具自动合并 | **Server 进程开销**：每个本地 Server 都是一个独立进程（通常是 Node.js），挂多了会占内存 | | **`npx` 自动安装**：不需要手动 npm install，配置里写包名就自动下载运行 | **配置文件没有校验**：JSON 写错了不会给明确提示，只会默默不加载，需要去看日志排查 | ## 思考题
初级：如果你想让 Claude 能搜索 Brave 网页结果，应该怎么改配置文件？ **参考答案：** 在 `mcpServers` 对象里加一个新的 Server 条目： ```json { "mcpServers": { "brave-search": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"], "env": { "BRAVE_API_KEY": "你的 Brave API Key" } } } } ``` 你需要先去 [Brave Search API](https://brave.com/search/api/) 注册并获取一个 API Key。然后把 Key 填到 `env` 的 `BRAVE_API_KEY` 里。保存配置后重启 Claude Desktop，就能在对话中让 Claude 搜索网页了。 如果你之前已经配了 Filesystem Server，把新的 `brave-search` 条目和已有的 `filesystem` 条目放在同一个 `mcpServers` 对象里就行，多个 Server 用逗号隔开。
中级：配了 3 个 Server 后，Claude 是怎么知道该调用哪个 Server 的工具的？ **参考答案：** Claude Desktop（Host）在启动时会为 3 个 Server 各创建一个 Client，每个 Client 和对应的 Server 完成能力协商后，通过 `tools/list` 拉取到该 Server 暴露的工具列表。然后 Host 把 3 份工具列表**合并成一个统一列表**，连同每个工具的名称、描述和参数 schema，一起喂给大模型。 当用户提问时，大模型从这个统一列表里选择要调用的工具（这就是模型的 Function Calling 能力）。模型选好后，Host 根据工具名反查"这个工具注册在哪个 Server"，把调用请求路由到对应的 Client，Client 再转发给 Server 执行。 整个路由过程对用户和模型都是透明的——模型不需要知道"这个工具在哪个 Server 上"，它只需要从一个扁平的工具列表里选。Host 负责做"分发邮件"的事情。
## 参考资料 1. 官方本地 Server 连接指南：（查询日期 2026-04-11） 2. Claude 帮助中心 - MCP 入门： 3. 官方 MCP 客户端列表： 4. Filesystem Server 源码： 5. Claude Desktop 下载： 6. MCP 调试工具文档： --- *Source: https://learnagent.wiki/mcp/cards/claude-desktop-setup* *Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*