最近总有人问我“MCP到底是什么你的 Claude 和 VSCode 是怎么连上各种工具的”这确实成了绕不开的话题。我在各种 AI 编码、自动化工作流里折腾了大半年MCPModel Context Protocol模型上下文协议已经成了我每天干活的基础设施。这篇文章就把 MCP 的概念、安装、使用以及如何在 Claude 和 VSCode 里接入这件事从零到一全部讲清楚。文章适合想给自己的人工智能工作流加“手和脚”的开发者和技术爱好者尤其是受够了在多个窗口之间反复复制粘贴、想让大模型直接操作本地文件、读取数据库、调用设计稿的人。我会把原理、配置文件和踩过的坑都说清楚照着做基本不会绕路。1. 为什么突然都在聊 MCP先把概念一次性讲透1.1 MCP 是什么MCP 的全称是 Model Context Protocol直译过来是“模型上下文协议”。它是 Anomaly 在 2024 年底开源的一种开放协议解决一个非常具体的问题大模型本身不会主动去读你的文件、查你的数据库、调用你公司的 API它只能跟你“聊天”。可光聊天能做的事太有限了——想让 AI 帮我整理某个文件夹里的 Markdown 文档它就得先把文档内容贴进对话框。想让 AI 帮我跑一段 Playwright 测试脚本它甚至没法直接打开浏览器。MCP 做的事情是把“AI 应用”和“外部工具/数据源”之间的连接标准化。你可以把它想象成 AI 世界的 USB-C 接口过去不同的外设文件系统、数据库、浏览器、设计软件各有各的插头和接口AI 根本认不过来。现在统一成了同一个标准接口只要工具实现了 MCP 协议任何支持 MCP 的 AI 应用插上就能用。从 2024 年底到现在MCP 已经从一个概念变成了一整套生态。GitHub 上出现了成百上千个现成的 MCP ServerOpenAI 在 2025 年也宣布支持 MCP各大大模型厂商基本都倒向了这个标准。现在的关键问题已经从“要不要用 MCP”变成了“怎么用好 MCP”。1.2 架构拆解Host、Client、Server 三件套MCP 的架构非常简单只要记住三个角色MCP Host宿主就是 AI 应用本身比如 Claude Desktop、VSCode、Cursor。它是用户直接打交道的程序负责把用户的意图告诉模型再把模型觉得需要的工具调用请求发出去。MCP Client客户端Host 内部跟 Server 建立连接的组件负责协议握手、发送请求、接收结果。普通用户不用关心这一层但是如果你要自己写 MCP Client 集成就需要了解。MCP Server服务端真正干活的部分。它暴露出一组“工具”Tools一个工具就是一个可以被模型调用的函数比如“读取文件内容”“查询数据库”“搜索网页”“浏览网页截图”等。模型本身不执行函数它只在对话中判断“我现在需要调用某个工具”然后把调用请求通过 MCP 协议发送出去。结果会以文本形式回流给模型模型再根据结果继续生成回复。整个过程完全由协议驱动因此任何实现了同样协议的 Server 都可以无缝替换。打个更直白的比方MCP Server 就像给 AI 装的一副“义肢”协议就是神经接口。宿主里有大脑模型义肢各有各的功能读文件、开网页、截图神经接口统一了信号格式于是大脑学会了怎么指挥不同功能的义肢。1.3 一次请求的背后发生了什么事理解到请求级别你才能真正解决问题。MCP 协议基于 JSON-RPC 2.0核心方法就那么几个initialize连接建立时客户端告诉服务端我要跟你通信双方的协议版本得对上。tools/list客户端问服务端你会哪些技能服务端返回一个工具列表每个工具带名字、描述、参数 schema。tools/call客户端真正调用某个工具传入参数。resources/list/resources/read另一种暴露数据的方式不执行动作只提供内容有点像“只读文件”。当你在 Claude Desktop 里输入“帮我看一下桌面上那个 todo.md 里有什么”背后发生的事情是模型先判断需要调用 filesystem server 的read_file工具于是 Claude Desktop 里的 Clien 端向本地通过 stdio 启动的 filesystem Server 发起了tools/call请求Server 读取文件把内容返回给模型模型再组织语言回复你。整个链路看起来有点绕但好处是分工明确模型不用学“怎么读文件”它只需要知道“有个工具能读文件、参数是路径”。不同的 Server 可以随意插拔这就是标准化带来的可组合性。2. MCP Server 从哪来现成、远程、自建三种路径2.1 官方与社区预构建 Server 库对初学者来说你不需要从零写任何代码就能先玩起来。Anomaly 官方维护了一批高质量的参考 Server常见的有Filesystem文件读写与目录操作最常用的入门 Server。GitHub可以调用 GitHub API比如创建 issue、读仓库文件、查看 PR。PostgreSQL / SQLite通过自然语言查询数据库。Playwright控制真实浏览器做页面操作和截图做网页自动化测试非常顺手。Fetch抓取网页内容并转成 Markdown。Memory给 AI 提供一个持久化的知识图谱记忆。Brave Search给 AI 加上联网搜索能力。你可能会好奇这些能力有些不是早就有了吗是的大模型应用里确实一直有“工具调用”这个概念但过去每个应用都自己定义一套工具协议导致 A 应用写的工具B 应用用不了。比如之前我在 Cursor 里给模型接了一套自定义 MCP 类似的文件工具换到 Claude Code 就要全部重写。现在大家都用同一套协议生态才真正滚起来。2.2 远程 HTTP Server设计工具和安全产品都在接入除了本地 stdio 方式的 ServerMCP 还支持通过 HTTP(S)SSE 方式连接远程 Server。这类 Server 的特点是不需要在本机下载依赖只要你有访问权限AI 应用就能直接通过互联网调用。比较典型的是设计协作领域比如蓝湖 MCP、Figma MCP。这让 AI 可以直接读取设计稿上的图层信息、尺寸、切图资源。我在某个项目里试过让 Claude 通过蓝湖 MCP 直接查看设计稿标注然后生成对应的前端样式代码这一步省掉了大量来回翻设计稿的时间。安全测试领域同样有 Burp Suite 的 MCP Server、Yakit 的 MCP 集成脑洞很大。远程 Server 通常会涉及 API Key 或 OAuth 授权配置的时候要特别留意权限范围别把有写权限的 key 交给不受信任的模型调用。2.3 自己写一个 MCP Server 难不难说实话比你想象中简单。官方提供了 Python 和 TypeScript 的 SDK核心代码可能只需要几十行。比如一个返回当前时间的最小 Python Serverfrom mcp.server.fastmcp import FastMCP mcp FastMCP(time-server) mcp.tool() def get_current_time(timezone: str Asia/Shanghai) - str: 返回指定时区的当前时间 from datetime import datetime import zoneinfo return datetime.now(zoneinfo.ZoneInfo(timezone)).isoformat() if __name__ __main__: mcp.run()pip install mcp python time_server.py然后在 Claude Desktop 里配置成 stdio server 就能用了。更复杂的 Server 无非是多加几个工具函数处理一下鉴权、日志和异常。如果你已经有现成的 API 封装包一层 MCP 工具是很快的。自己写 Server 最大的价值在于你可以把公司内部的私有系统、遗留脚本、命令行工具都暴露给 AI。注意这层能力会给安全边界带来很大挑战定位是“给你信任的 AI 助手用”而不是随便公开访问。3. 在 Claude Desktop 里安装 MCP十分钟跑通第一个工具3.1 事前准备先确认环境先声明一下这里说的 Claude 既可以是 Claude Desktop桌面客户端也可以是 Claude Code命令行工具。我先讲 Claude Desktop 怎么配。你需要准备三样东西Claude 桌面客户端最好是最新版本因为老版本可能没有 MCP 设置入口。Node.js 18 以上。大多数官方 Server 通过 npx 运行所以 Node 环境是硬依赖。你想接入的 MCP Server 的启动命令。官方 Server 一般是npx -y modelcontextprotocol/server-xxx。Windows 用户特别提示如果你在 Windows 上装 Claude 新版遇到了“workspace requires the virtual machine platform”之类提示这其实是新版客户端要求开启 Windows 的“虚拟机平台”功能才能运行内置的容器隔离环境。解决办法是去“控制面板 - 程序 - 启用或关闭 Windows 功能”勾选“虚拟机平台”重启电脑。这一步不做Claude 可能直接无法启动。macOS 和 Linux 用户一般没这个步骤。3.2 配置文件的写法与常见坑Claude Desktop 的 MCP 配置写在claude_desktop_config.json里。不同系统位置不一样macOS~/Library/Application Support/Claude/claude_desktop_config.jsonWindows%APPDATA%\Claude\claude_desktop_config.jsonLinux~/.config/Claude/claude_desktop_config.json文件内容长这样{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/Desktop, /Users/yourname/Documents ] }, fetch: { command: uvx, args: [mcp-server-fetch] } } }配置的路径参数决定 AI 能访问哪些目录此处建议只把你真正想让 AI 操作的目录暴露进去。如果把整个根目录配进去模型就有权限读取你机器上几乎所有文件出问题的时候后悔都来不及。新手最常见的坑有三个用npx直接启动时Windows 系统偶尔会弹出一个“npx 不是可识别的命令”的报错多半是 Node 没加入 PATH。这时候可以改成cmd /c npx -y ...或者干脆写 Node 的绝对路径。JSON 格式错误。少逗号、多括号是最高频问题改完保存后最好用一个 JSON 校验工具过一遍再重启。配置文件改完不生效。Claude Desktop 不会热加载配置必须完全退出进程再重新打开。3.3 验证 Server 是否接通配置好以后重启 Claude Desktop打开对话窗口仔细观察工具列表里有没有增加内容。判断是否连接成功最直接的方法是问它一句“你现在能访问我桌面的文件吗帮我列一下桌面有几个文件。”如果它真去列出了你的文件说明 MCP Server 已经接通。如果模型回答“我没有这个能力”说明配置可能没生效或者 Server 启动失败。建议去 Claude 的日志目录看具体报错信息Windows 和 macOS 的日志路径可能有差异一般位于用户目录下的claude日志文件夹。排查的思路是先确认 Server 能不能单独启动再确认配置文件格式最后才是检查权限和路径。3.4 换个方式通过设置面板添加 MCP较新版本的 Claude Desktop 也提供了图形化的 MCP 管理入口打开“设置Settings”找到“Developer/开发者选项”或者直接的 MCP 标签页可以一键添加本地 Server 或输入远程 Server 地址。我个人的习惯是如果是官方现成 Server优先用命令行配置文件因为可复制、可版本控制如果只是想临时试一个远程 Server用设置面板更方便。两种方式本质是同一个东西最终都写进同一份配置。4. 在 VSCode 里接入 MCPClaude Code 和 Codex 的实操配置4.1 为什么 VSCode 反而成了 MCP 的主战场虽然 Claude Desktop 是 MCP 的“原生宿主”但真正让我觉得 MCP 不可替代的场景全都在代码编辑器里。原因很简单开发生成式 AI 工具时代编辑器就是生产力工具的核心。在 VSCode 里接好 MCP意味着 AI 助手既能读代码、查文档、跑测试命令还能在同一个面板里操作外部工具。在 VSCode 里接入 MCP主流方案有两个Claude Code 扩展和 OpenAI Codex 扩展。下面都讲一遍。4.2 方案一VSCode Claude Code先安装 Claude Code。如果没有装过在终端里执行npm install -g anthropic-ai/claude-code装完在 VSCode 扩展市场里搜“Claude Code”并安装官方扩展然后在 VSCode 的终端里运行claude跟着提示完成登录授权。这一步必须确保你的 Claude 账号可用。如果登录时报“unfortunately, claude is not available to new users right now”说明账号被限流或者该地区不支持这类问题只能耐心等待或更换账号环境没有其他太好的捷径。接下来添加 MCP Server。有两种方式方式一命令行添加claude mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem D:/projects这个命令会在 Claude 的全局配置文件里写入对应的 MCP 配置。用claude mcp list可以查看已添加的 Server用claude mcp inspect可以测试某个 Server 是否能够正常启动并获取工具列表。这种方式适合长期使用的 Server。方式二项目级 .mcp.json在项目根目录创建.mcp.json{ mcpServers: { playwright: { command: npx, args: [-y, playwright/mcplatest] } } }项目级配置的好处是跟着仓库走团队协作时每个人克隆下来就能用不用重复配置全局环境坏处是配置文件如果被推送到公共仓库可能会泄露 Server 的敏感参数。配置完成后在 Claude Code 对话里输入/mcp可以看到当前连接的 Server 状态和可用工具列表。你可以直接让 AI 调用这些工具例如“用 playwright 打开百度搜索 MCP 教程并把结果页截图保存到当前目录”。Claude Code 在 VSCode 里的体验相当流畅它能看到你的项目结构也能通过终端执行命令配合 MCP 简直是如虎添翼。4.3 方案二VSCode Codex 扩展如果你用的是 OpenAI 的 CodexVSCode 里的 Codex 扩展MCP 配置路径完全不同。Codex 读取的是~/.codex/config.toml格式是 TOML 而不是 JSON。例如接入一个 Figma MCP[mcp_servers.figma] command npx args [-y, figma-developer-mcp, --port9123] env { FIGMA_API_KEY your_key_here }配好以后重启 Codex 或重载 VSCode 窗口Codex 会自动识别新的 MCP Server。如果你想在配置里引用环境变量而不是明文写 key可以写成env { FIGMA_API_KEY ${FIGMA_API_KEY} }然后在系统环境变量里设置这样就不会把密钥提交进版本控制。之前搜 Codex 相关词时很多人打错成了“fingma mcp”实际就是 Figma 的 MCP Server。这类设计工具 MCP 的价值在于你可以直接让 AI 从设计稿提取颜色、字体、间距等样式值然后生成接近还原度的前端代码。我自己试过几次虽然不能做到像素级完美但省掉的“截图上屏-肉眼测色-手动调整”的时间非常可观。4.4 VSCode 里配置后的一个完整实测场景为了让你清楚看到“VSCodeMCP”到底能给实际开发省多少事我分享一个真实操作过程。我在一个重构项目里需要把公司旧官网的所有页面截图整理归档并顺便检查几百个页面的标题是否规范。如果手动做一个人一个下午基本搭进去。我的做法是在当前项目里配置了 Playwright MCP然后在 Claude Code 会话里输入这样一段话“帮我遍历 sitemap.xml 里的前 50 个 URL逐个打开页面、等待加载完成、将页面标题记录下来并且给每个页面截取一张整页截图保存到 shots 目录文件名按 URL 路径生成。”Claude Code 先调用了 Playwright MCP 的browser_navigate和browser_snapshot工具逐个访问页面截图工具生成的文件路径返回给模型后模型再继续下一个 URL。整个过程自动化跑下来我不需要打一行测试代码只负责观察输出结果是否合理。那一次我最大的感受是MCP 把“AI 只会说话”的尴尬彻底解决了。以前这种活要么我自己写爬虫脚本要么手动搞现在只要 AI 调用合适的工具同一件事的边际成本几乎为零。5. 常见问题与排查技巧实录5.1 速查表新手最容易翻车的六个场景现象可能原因排查思路Server 在配置里添加了但工具列表不显示JSON 配置语法错误或路径写错用 JSON 校验工具检查配置逐个排查命令字段启动时报 “command not found: npx”Node.js 未安装或未加入 PATH在终端单独执行npx -v验证环境Windows 尝试cmd /c npxWindows 启动 Claude 报 virtual machine platform 错误系统未开启“虚拟机平台”功能控制面板 - 启用或关闭 Windows 功能 - 虚拟机平台 - 重启部分远程 MCP Server 连接一直转圈网络不通、端口未开放或需要代理在浏览器里直接访问 Server 的 HTTP 地址测试连通性Server 能启动但模型说“我没有权限”工具返回报错或鉴权失败claude mcp inspect单独测试每个工具查看 Server 日志配置文件添加了多个 Server但只有一部分生效某个 Server 启动失败拖垮整体配置逐个注释掉再重启做二分定位5.2 一些调试经验调试 MCP 最核心的思路是先把配置环境和网络环境剥离出来。如果 Server 是用npx拉的第一次运行会下载依赖国内网络环境下容易卡住可以先在终端手动执行一次同样的命令确认能秒开再指望 AI 应用能接上。另外多 Server 同时配置时有一个 Server 挂了可能会让整个工具列表刷新变慢。我在自己的配置里习惯按实用频率把 Server 控制在两到四个不常用的用claude mcp remove随时清掉保持环境干净。claude mcp inspect这个命令值得多说一句。它不仅能显示工具名称还会把每个工具的参数 schema 列出来。你可以拿着这个信息反过来调试自己写的工具“为什么模型总是不传 timezone 参数”一看 schema 就明白了也许是描述写得不够清楚模型不知道这个参数有什么用。6. 我最后的几点使用心得玩了大半年 MCP我的感受是这个协议最大的意义不是某个工具好用而是它把 AI 的能力边界往前推了一大步。过去 AI 是“嘴强王者”现在它可以有手有脚过去接一个新工具要写一堆胶水代码现在只要一个命令加一段配置。但要提醒的是MCP 不是万能的。它本质上还是让模型“调用预定义的函数”模型并不会因为接入了 MCP 就变成 Agent 自动规划一切。你想要让 MCP 真正产生价值自己的业务逻辑得先清楚哪一步最适合让模型判断哪一步需要调用工具哪一步必须人工确认。把 MCP 当成“增强版的函数库”远比当成“全自动机器人”更稳妥。对刚上手的朋友我的建议是先从 filesystem 和 fetch 这两个官方 Server 开始把“配置 — 重启 — 调用”整个链路跑通再逐步加 Playwright、GitHub 等偏业务功能的 Server。跑顺一个场景之后你对 MCP 的整个心智模型就建立起来了后面学自定义 Server、远程部署都会很顺。等技术熟练了再回头看看哪些重复劳动可以交给 AI 去操作那时候你会发现自己根本离不开 MCP。