【MCP 全栈教程】第 36 篇在 Claude Desktop / Claude Code 中使用 MCP Server本系列定位从协议原理到 Server 开发、Client 开发、再到各大平台实战集成系统化掌握 MCPModel Context Protocol全栈技术体系。本篇你将学到掌握 Claude Desktop 的claude_desktop_config.json完整配置方法理解mcpServers字段中command、args、env三要素的作用与写法学会同时连接多个 MCP Server 并管理权限审批流程掌握 Claude Code 命令行模式的 MCP 配置方式一句话总结Claude Desktop / Claude Code 是 MCP 生态中最成熟的 Host 应用掌握其配置等于打开了 MCP 实战的大门。一、Claude Desktop 与 MCP 的关系在前面几篇文章中我们已经深入学习了 MCP 协议规范、Server 端和 Client 端的开发。但要真正把 MCP 用起来最直接的方式就是通过一个现成的 Host 应用。Claude Desktop 是最早原生支持 MCP 的桌面客户端之一。它内置了完整的 MCP Client 实现能够通过 STDIO 传输方式拉起本地 MCP Server 进程自动完成能力发现initialize→tools/list/resources/list/prompts/list并将结果呈现给用户。Claude Code 则是面向终端的 AI 编程工具同样内置 MCP Client但配置方式更加贴近开发者习惯。下表对比两者在 MCP 维度的差异特性Claude DesktopClaude Code界面形态图形化桌面应用命令行工具配置方式JSON 配置文件CLI 命令 JSON 配置传输方式STDIO本地进程STDIO Streamable HTTP权限审批GUI 弹窗交互终端确认提示适用场景通用对话与自动化编程与代码工程多 Server支持支持二、配置文件路径Claude Desktop 的 MCP 配置统一写在claude_desktop_config.json文件中不同操作系统的路径如下操作系统配置文件路径macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinuxBeta~/.config/Claude/claude_desktop_config.json如果你找不到该文件可以手动创建。Claude Desktop 在启动时会读取这个文件如果文件不存在或格式错误MCP 功能不会生效但应用本身仍可正常使用。一个快速定位路径的技巧# macOSopen~/Library/Application\Support/Claude/# Windows (PowerShell)explorer$env:APPDATA\Claude三、claude_desktop_config.json 配置详解配置文件的顶层结构只有一个关键字段mcpServers它是一个对象键名是 Server 的逻辑名称值是该 Server 的启动配置。3.1 基本结构{mcpServers:{server-name:{command:启动命令,args:[参数列表],env:{ENV_KEY:ENV_VALUE}}}}三个核心字段说明字段类型必填说明commandstring是可执行命令如npx、python、uvx或绝对路径argsstring[]是传递给 command 的参数数组envobject否注入到子进程的环境变量3.2 理解 command args 的拼接逻辑Claude Desktop 实际上是在内部执行command args[0] args[1] ...这条 shell 命令来拉起 Server 进程。例如{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]}}}等价于在终端执行npx-ymodelcontextprotocol/server-filesystem /Users/me/projects3.3 使用 uvx 启动 Python Server对于用uv管理的 Python MCP Server推荐使用uvx启动它能自动处理虚拟环境{mcpServers:{my-python-server:{command:uvx,args:[my-mcp-server],env:{API_KEY:sk-xxx}}}}3.4 使用绝对路径避免 PATH 问题在 macOS 上GUI 应用启动的子进程可能无法继承完整的PATH环境变量导致找不到npx或python。推荐使用绝对路径{mcpServers:{filesystem:{command:/usr/local/bin/npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]}}}查找绝对路径的方法whichnpx# macOS/Linuxwhere npx# Windows四、Filesystem Server 实战Filesystem Server 是最经典的入门级 MCP Server它提供文件读写、目录浏览、文件搜索等能力。我们以此为例走通完整流程。4.1 配置{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects,/Users/me/documents]}}}args最后的路径参数是允许访问的根目录白名单可以配置多个。Server 只能操作这些目录范围内的文件。4.2 启动与验证保存配置文件。完全退出 Claude DesktopmacOS 上CmdQ不只是关闭窗口。重新打开 Claude Desktop。在输入框左下角应该能看到一个工具图标点击展开会显示已连接的 Server 及其暴露的 Tools 和 Resources。4.3 实际对话示例连接成功后你可以直接用自然语言驱动文件操作你的输入Claude 调用的 Tool“读取 /Users/me/projects/README.md 的内容”read_file“在 projects 目录下搜索所有包含 TODO 的文件”search_files“把这段总结写入 notes.md”write_file“列出 documents 目录下的所有文件”list_directory每次调用敏感操作如写文件前Claude Desktop 会弹出权限确认框你可以选择允许本次、允许该会话或拒绝。五、多 Server 同时连接mcpServers是一个对象天然支持配置多个 Server。Claude Desktop 会并行启动所有 Server并各自维护独立的 STDIO 通道。{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]},sqlite:{command:uvx,args:[mcp-server-sqlite,--db-path,/Users/me/data/app.db]},fetch:{command:uvx,args:[mcp-server-fetch]}}}配置多个 Server 后Claude 会根据用户意图自动路由到对应的 Server。例如你说查询数据库里 users 表的行数它会调用 sqlite Server 的工具说抓取这个网页内容它会调用 fetch Server。多 Server 连接时的注意事项注意点说明资源占用每个 Server 是独立进程注意内存和 CPU工具名冲突不同 Server 可能暴露同名 ToolClaude 会用serverName_toolName消歧启动顺序并行启动某个 Server 失败不影响其他 Server日志排查单个 Server 启动失败时在工具图标处会显示错误提示六、权限审批流程Claude Desktop 对 MCP 工具调用采用按需授权模型。理解审批流程对于安全使用 MCP 至关重要。6.1 审批层级层级触发时机用户操作连接授权首次连接某个 Server确认信任该 Server工具授权每次调用 Tool允许 / 拒绝 / 始终允许资源读取读取 Resource通常跟随工具调用一起授权6.2 授权选项含义当你看到权限弹窗时通常有几个选项Allow once本次允许仅允许这一次调用下次再调用还会询问Allow for this chat本会话允许当前对话窗口内不再询问该工具Always allow始终允许永久信任后续不再询问可在设置中撤销Deny拒绝拒绝本次调用Claude 会收到错误并尝试其他方案6.3 管理已授权工具在 Claude Desktop 的设置界面中可以查看和管理所有已授权的工具列表随时撤销某个 Server 或某个 Tool 的授权。这是一个重要的安全防线——尤其在配置了第三方 Server 时定期审查授权列表是好习惯。七、Claude Code 的命令行 MCP 配置Claude Code 作为终端工具提供了比 Desktop 更灵活的 MCP 配置方式支持三种作用域。7.1 三种配置作用域作用域命令参数影响范围适用场景Local本地--scope local默认当前项目的当前目录项目专属 ServerProject项目--scope project写入项目.mcp.json团队共享团队协作User用户--scope user当前用户全局通用工具 Server7.2 添加 MCP Server# 添加一个 STDIO 类型的 Server本地作用域claude mcpaddfilesystem -- npx-ymodelcontextprotocol/server-filesystem /home/me/projects# 添加一个带环境变量的 Serverclaude mcpaddmy-api-eAPI_KEYsk-xxx -- python my_server.py# 添加一个 Streamable HTTP 类型的 Serverclaude mcpaddremote-server--transporthttp https://api.example.com/mcp7.3 管理命令# 查看所有已配置的 Serverclaude mcp list# 查看某个 Server 的详情claude mcp get filesystem# 删除某个 Serverclaude mcp remove filesystem7.4 项目级 .mcp.json 文件当使用--scope project时Claude Code 会在项目根目录生成.mcp.json文件格式与claude_desktop_config.json类似{mcpServers:{docs:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,./docs]}}}团队成员克隆仓库后Claude Code 会检测到该文件并提示是否信任并启用这些 Server。八、调试技巧当 Server 无法正常连接时可以按以下步骤排查症状可能原因解决方案Server 未出现在工具列表配置文件路径错误或 JSON 格式错误用 JSON 校验工具检查语法启动后立即断开command找不到或args错误在终端手动运行command args测试工具调用返回错误Server 内部逻辑异常查看 Server 的 stderr 日志PATH 问题GUI 应用未继承终端 PATH使用绝对路径配置command一个实用的调试方法是把 Server 的输出重定向到日志文件便于事后分析{mcpServers:{my-server:{command:python,args:[-u,my_server.py],env:{MCP_LOG_LEVEL:DEBUG}}}}对于 Claude Code可以直接在会话中输入/mcp命令查看所有 Server 的连接状态和最近错误信息这是最快的排查手段。本篇小结知识点要点配置文件claude_desktop_config.json路径因系统而异核心字段commandargsenv三要素多 Server在mcpServers对象中并列配置Filesystem Server经典入门案例提供文件读写与搜索权限审批连接授权 工具授权两级模型Claude CodeCLI 配置支持 local/project/user 三种作用域调试手动运行命令、查看日志、使用/mcp命令下篇预告第 37 篇在 VS Code 中集成 MCP Server从编辑器视角出发讲解 VS Code 的 MCP 配置方式及其与 GitHub Copilot 的协作机制。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。
【MCP 全栈教程】第 36 篇在 Claude Desktop / Claude Code 中使用 MCP Server本系列定位从协议原理到 Server 开发、Client 开发、再到各大平台实战集成系统化掌握 MCPModel Context Protocol全栈技术体系。本篇你将学到掌握 Claude Desktop 的claude_desktop_config.json完整配置方法理解mcpServers字段中command、args、env三要素的作用与写法学会同时连接多个 MCP Server 并管理权限审批流程掌握 Claude Code 命令行模式的 MCP 配置方式一句话总结Claude Desktop / Claude Code 是 MCP 生态中最成熟的 Host 应用掌握其配置等于打开了 MCP 实战的大门。一、Claude Desktop 与 MCP 的关系在前面几篇文章中我们已经深入学习了 MCP 协议规范、Server 端和 Client 端的开发。但要真正把 MCP 用起来最直接的方式就是通过一个现成的 Host 应用。Claude Desktop 是最早原生支持 MCP 的桌面客户端之一。它内置了完整的 MCP Client 实现能够通过 STDIO 传输方式拉起本地 MCP Server 进程自动完成能力发现initialize→tools/list/resources/list/prompts/list并将结果呈现给用户。Claude Code 则是面向终端的 AI 编程工具同样内置 MCP Client但配置方式更加贴近开发者习惯。下表对比两者在 MCP 维度的差异特性Claude DesktopClaude Code界面形态图形化桌面应用命令行工具配置方式JSON 配置文件CLI 命令 JSON 配置传输方式STDIO本地进程STDIO Streamable HTTP权限审批GUI 弹窗交互终端确认提示适用场景通用对话与自动化编程与代码工程多 Server支持支持二、配置文件路径Claude Desktop 的 MCP 配置统一写在claude_desktop_config.json文件中不同操作系统的路径如下操作系统配置文件路径macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinuxBeta~/.config/Claude/claude_desktop_config.json如果你找不到该文件可以手动创建。Claude Desktop 在启动时会读取这个文件如果文件不存在或格式错误MCP 功能不会生效但应用本身仍可正常使用。一个快速定位路径的技巧# macOSopen~/Library/Application\Support/Claude/# Windows (PowerShell)explorer$env:APPDATA\Claude三、claude_desktop_config.json 配置详解配置文件的顶层结构只有一个关键字段mcpServers它是一个对象键名是 Server 的逻辑名称值是该 Server 的启动配置。3.1 基本结构{mcpServers:{server-name:{command:启动命令,args:[参数列表],env:{ENV_KEY:ENV_VALUE}}}}三个核心字段说明字段类型必填说明commandstring是可执行命令如npx、python、uvx或绝对路径argsstring[]是传递给 command 的参数数组envobject否注入到子进程的环境变量3.2 理解 command args 的拼接逻辑Claude Desktop 实际上是在内部执行command args[0] args[1] ...这条 shell 命令来拉起 Server 进程。例如{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]}}}等价于在终端执行npx-ymodelcontextprotocol/server-filesystem /Users/me/projects3.3 使用 uvx 启动 Python Server对于用uv管理的 Python MCP Server推荐使用uvx启动它能自动处理虚拟环境{mcpServers:{my-python-server:{command:uvx,args:[my-mcp-server],env:{API_KEY:sk-xxx}}}}3.4 使用绝对路径避免 PATH 问题在 macOS 上GUI 应用启动的子进程可能无法继承完整的PATH环境变量导致找不到npx或python。推荐使用绝对路径{mcpServers:{filesystem:{command:/usr/local/bin/npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]}}}查找绝对路径的方法whichnpx# macOS/Linuxwhere npx# Windows四、Filesystem Server 实战Filesystem Server 是最经典的入门级 MCP Server它提供文件读写、目录浏览、文件搜索等能力。我们以此为例走通完整流程。4.1 配置{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects,/Users/me/documents]}}}args最后的路径参数是允许访问的根目录白名单可以配置多个。Server 只能操作这些目录范围内的文件。4.2 启动与验证保存配置文件。完全退出 Claude DesktopmacOS 上CmdQ不只是关闭窗口。重新打开 Claude Desktop。在输入框左下角应该能看到一个工具图标点击展开会显示已连接的 Server 及其暴露的 Tools 和 Resources。4.3 实际对话示例连接成功后你可以直接用自然语言驱动文件操作你的输入Claude 调用的 Tool“读取 /Users/me/projects/README.md 的内容”read_file“在 projects 目录下搜索所有包含 TODO 的文件”search_files“把这段总结写入 notes.md”write_file“列出 documents 目录下的所有文件”list_directory每次调用敏感操作如写文件前Claude Desktop 会弹出权限确认框你可以选择允许本次、允许该会话或拒绝。五、多 Server 同时连接mcpServers是一个对象天然支持配置多个 Server。Claude Desktop 会并行启动所有 Server并各自维护独立的 STDIO 通道。{mcpServers:{filesystem:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,/Users/me/projects]},sqlite:{command:uvx,args:[mcp-server-sqlite,--db-path,/Users/me/data/app.db]},fetch:{command:uvx,args:[mcp-server-fetch]}}}配置多个 Server 后Claude 会根据用户意图自动路由到对应的 Server。例如你说查询数据库里 users 表的行数它会调用 sqlite Server 的工具说抓取这个网页内容它会调用 fetch Server。多 Server 连接时的注意事项注意点说明资源占用每个 Server 是独立进程注意内存和 CPU工具名冲突不同 Server 可能暴露同名 ToolClaude 会用serverName_toolName消歧启动顺序并行启动某个 Server 失败不影响其他 Server日志排查单个 Server 启动失败时在工具图标处会显示错误提示六、权限审批流程Claude Desktop 对 MCP 工具调用采用按需授权模型。理解审批流程对于安全使用 MCP 至关重要。6.1 审批层级层级触发时机用户操作连接授权首次连接某个 Server确认信任该 Server工具授权每次调用 Tool允许 / 拒绝 / 始终允许资源读取读取 Resource通常跟随工具调用一起授权6.2 授权选项含义当你看到权限弹窗时通常有几个选项Allow once本次允许仅允许这一次调用下次再调用还会询问Allow for this chat本会话允许当前对话窗口内不再询问该工具Always allow始终允许永久信任后续不再询问可在设置中撤销Deny拒绝拒绝本次调用Claude 会收到错误并尝试其他方案6.3 管理已授权工具在 Claude Desktop 的设置界面中可以查看和管理所有已授权的工具列表随时撤销某个 Server 或某个 Tool 的授权。这是一个重要的安全防线——尤其在配置了第三方 Server 时定期审查授权列表是好习惯。七、Claude Code 的命令行 MCP 配置Claude Code 作为终端工具提供了比 Desktop 更灵活的 MCP 配置方式支持三种作用域。7.1 三种配置作用域作用域命令参数影响范围适用场景Local本地--scope local默认当前项目的当前目录项目专属 ServerProject项目--scope project写入项目.mcp.json团队共享团队协作User用户--scope user当前用户全局通用工具 Server7.2 添加 MCP Server# 添加一个 STDIO 类型的 Server本地作用域claude mcpaddfilesystem -- npx-ymodelcontextprotocol/server-filesystem /home/me/projects# 添加一个带环境变量的 Serverclaude mcpaddmy-api-eAPI_KEYsk-xxx -- python my_server.py# 添加一个 Streamable HTTP 类型的 Serverclaude mcpaddremote-server--transporthttp https://api.example.com/mcp7.3 管理命令# 查看所有已配置的 Serverclaude mcp list# 查看某个 Server 的详情claude mcp get filesystem# 删除某个 Serverclaude mcp remove filesystem7.4 项目级 .mcp.json 文件当使用--scope project时Claude Code 会在项目根目录生成.mcp.json文件格式与claude_desktop_config.json类似{mcpServers:{docs:{command:npx,args:[-y,modelcontextprotocol/server-filesystem,./docs]}}}团队成员克隆仓库后Claude Code 会检测到该文件并提示是否信任并启用这些 Server。八、调试技巧当 Server 无法正常连接时可以按以下步骤排查症状可能原因解决方案Server 未出现在工具列表配置文件路径错误或 JSON 格式错误用 JSON 校验工具检查语法启动后立即断开command找不到或args错误在终端手动运行command args测试工具调用返回错误Server 内部逻辑异常查看 Server 的 stderr 日志PATH 问题GUI 应用未继承终端 PATH使用绝对路径配置command一个实用的调试方法是把 Server 的输出重定向到日志文件便于事后分析{mcpServers:{my-server:{command:python,args:[-u,my_server.py],env:{MCP_LOG_LEVEL:DEBUG}}}}对于 Claude Code可以直接在会话中输入/mcp命令查看所有 Server 的连接状态和最近错误信息这是最快的排查手段。本篇小结知识点要点配置文件claude_desktop_config.json路径因系统而异核心字段commandargsenv三要素多 Server在mcpServers对象中并列配置Filesystem Server经典入门案例提供文件读写与搜索权限审批连接授权 工具授权两级模型Claude CodeCLI 配置支持 local/project/user 三种作用域调试手动运行命令、查看日志、使用/mcp命令下篇预告第 37 篇在 VS Code 中集成 MCP Server从编辑器视角出发讲解 VS Code 的 MCP 配置方式及其与 GitHub Copilot 的协作机制。如果本篇内容对你有帮助欢迎点赞收藏有任何疑问欢迎在评论区交流。
