这两年只要你在折腾 AI 编程工具大概率绕不开两个名字Claude Code 和 MCP。Claude Code 是 Anthropic 推出的命令行 AI 编程助手直接在终端里干活而 MCPModel Context Protocol模型上下文协议则是给这些 AI 助手插上「外接设备」的通用接口。很多朋友第一次接触 MCP 时满脑子都是「这玩意儿到底怎么配」「配了有什么用」「跟普通的插件有什么区别」。这篇文章就从我自己的实际踩坑经历出发把 Claude Code 和 MCP 从安装、配置到实战联动讲透尽量让完全没接触过命令行的朋友也能照着做出来。内容会比较长但每个步骤背后我都会解释为什么这么做而不是单纯给一段抄完就忘的配置。刚上手的时候我最大的困惑是分不清 Claude Code、MCP Server、MCP Host 这几个词的关系。后来我用一个生活化的类比才彻底理顺Claude Code 是「指挥官」MCP Server 是「各种工具人」MCP 协议就是双方约定好的「工作语言」。指挥官不懂工具人的具体技能但它会按协议下发任务工具人干完活再把结果按协议交回来。这样想后面所有配置逻辑就顺了。1. 先搞清楚Claude Code 和 MCP 到底是什么关系1.1 Claude Code终端里的 AI 编程搭档Claude Code 本质上是一个运行在终端里的 AI 编程环境。它不像 ChatBox 那种对话框而是直接和你的代码仓库、命令行、文件系统待在一起。你可以让它读代码、改文件、跑测试、查日志它通过命令行工具在本地执行操作而不是光靠聊天给你甩一段代码让你自己粘贴。我第一次用 Claude Code 时的真实感受是这玩意儿确实不是花架子。它能在真实项目里直接编辑文件能调用终端命令出了问题还会根据报错去排查。跟普通聊天式 AI 相比它最大的特点是「有手有脚」——因为 Claude Code 的进程可以访问当前目录下的文件、可以执行 shell 命令它就从一个只會出主意的顾问变成了一个能下场干活的实习生。但问题也随之而来它的「手和脚」默认只有那么几样。它能看文件、改文件、运行命令但这远远不够。我想让它直接查生产环境数据库让它读一下设计稿标注让它拉取某个远端 API 的数据默认状态下它做不到。这时候就该 MCP 出场了。1.2 MCP给 AI 装上的「万能外设接口」MCP 的全称是 Model Context Protocol中文常译作「模型上下文协议」。简单点说它就是一套统一标准让 AI 应用比如 Claude Code能够通过同一个协议接入各种各样的外部工具和数据源。你可以把 MCP 理解成 USB 接口。以前你要给电脑接打印机、接键盘、接手机每种设备都有专属接口厂商还得单独做适配。现在统一成 USB设备只要支持 USB 标准插上就能用。MCP 干的就是这件事让所有外部工具都按同一套「插拔标准」接入 AI。现在生态里已经有几百个现成的 MCP Server覆盖文件系统、GitHub、数据库、浏览器、Figma、Apifox、蓝湖、通达信本地数据等场景装上就能用。理解 MCP 的架构时记住三个角色就行MCP Host宿主程序也就是 Claude Code、Codex 这类 AI 客户端。它负责调度 AI 模型和 MCP Server 之间的通信。MCP Server提供具体能力的服务进程。比如「filesystem Server」提供文件操作能力「GitHub Server」提供仓库管理能力。一个 Host 可以挂多个 Server。MCP Protocol两边通信的协议标准。它定义了请求、响应、工具调用、资源读取等消息格式目前主流传输方式有 stdio标准输入输出和 SSEServer-Sent Events。有一个细节很多人容易忽略MCP Server 不是插件它往往是一个独立的进程。Claude Code 启动时会按照配置帮你把这个进程拉起来然后通过协议跟它对话。所以你在配置里填的其实不是「一段功能代码」而是一个「启动命令」。想通这一点排查问题的时候就会少走很多弯路。2. 从零开始安装与基础配置2.1 环境准备Node.js 版本是第一个坑Claude Code 官方推荐的安装方式是通过 npm 全局安装所以电脑上必须先有 Node.js 环境。很多 Windows 用户在这一步就翻车了——不是没装 Node而是装完 Node 之后 npm 的全局路径没配好导致命令行怎么都找不到 claude 命令。建议直接去 Node.js 官网下载 LTS 版本长期支持版目前 18 和 20 都有不少人用实测 20 比较稳。装完之后打开终端输入node -v npm -v能正常输出版本号说明 Node 环境没问题。如果在 Windows 上用 PowerShell 执行安装命令时提示「无法加载文件因为在此系统上禁止运行脚本」那就需要先放开 PowerShell 的执行策略。用管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这一步设置为 RemoteSigned 就够了既允许本地脚本运行又不会把安全策略完全关掉。看到提示问你是否更改执行策略输入 Y 回车就行。2.2 安装 Claude Code 与常见卸载方法安装 Claude Code 没有太多花活就是一条命令npm install -g anthropic-ai/claude-code如果你想装特定版本可以在包名后面加 版本号比如anthropic-ai/claude-code1.0.20。日常使用建议保持最新因为 Anthropic 迭代速度很快旧版本可能会遇到 MCP 配置格式不兼容的问题。装完验证一下claude --version能显示出版本号就成功了。我第一次安装的时候卡了很久后来发现是公司网络把 npm 的默认源墙了换成淘宝镜像秒装完npm config set registry https://registry.npmmirror.com然后再跑安装命令。如果你不确定当前 npm 源是什么执行npm config get registry查看。切换镜像源这件事我的建议是国内网络环境下直接用镜像没问题但如果之后要发布自己的 npm 包记得切回官方源。卸载的方式也很简单npm uninstall -g anthropic-ai/claude-codeWindows 用户如果遇到卸载不干净、重装后还是旧版本的情况八成是 npm 缓存的问题可以用npm cache clean --force清一下缓存再重装。另外Claude Code 的配置文件和登录态一般存在用户目录下如果你想把配置也清干净Windows 在C:\Users\你的用户名\.claude目录下macOS 在~/.claude目录下删除这个文件夹就能彻底重置。2.3 第一次运行登录与权限安装完成后在项目目录下运行claude命令会进入首次引导流程。它会让你登录 Anthropic 账号或者通过 API Key 方式接入登录成功后就能开始对话。这里有一个热词我特别想聊一下「claude code cli 如何给完全访问权限」。很多用户碰到这个问题是因为 Claude Code 在工作时要读文件、写文件、执行命令系统会弹出权限确认。如果在初始化时你选择了「限制模式」Claude Code 的很多能力会被锁住比如不能执行任意命令、不能修改系统文件。想给它完全访问权限在会话界面里输入命令/permissions在弹出的设置菜单里把权限模式调整为「允许」或者按需要单独开启某项能力的授权。也可以直接在启动命令时加参数/permission-mode acceptEdits但这会让 Claude Code 自动接受所有文件编辑有风险不太建议默认开启。macOS 上还有一个坑首次从终端调用 Claude Code 时系统会弹窗提示「终端想要访问您日历/通讯录/文件夹」之类的授权请求。如果你希望 Claude Code 能随意访问某个目录必须在「系统设置 → 隐私与安全性 → 文件与文件夹 / 完全磁盘访问权限」里把终端或你使用的 iTerm、VS Code 内置终端勾上。否则你会发现同一个命令在 GUI 工具里跑得好好的在终端里却一直提示没权限非常诡异。Windows 11 上类似的问题也存在不过形式变成了「终端应用需要访问你的文件夹」。一旦出现权限弹窗点允许就好如果手滑点了拒绝很容易出现「Claude 能聊天但一动文件就报错」的情况。修复方法是在 Windows 设置的隐私里手动把对应的终端应用权限打开。3. 动手配置让 MCP Server 跑起来3.1 MCP Server 该怎么选、在哪找配置 MCP 的第一步是找到合适的 Server。目前比较有名的「官方示例仓库」是 modelcontextprotocol/servers里面有 filesystem、github、fetch、memory、sequential-thinking 等常用 server。社区里也有大量第三方实现比如 Apifox MCP、蓝湖 MCP、Figma MCP、通达信本地数据 MCP 等。我的建议是先从官方维护的 server 开始不要一上来就装一堆花里胡哨的。官方 server 文档全、更新勤、坑少。等你理解了 MCP 的工作原理再按需找第三方遇到问题也容易排查。选型时要注意一个点MCP Server 的启动方式有很多种常见的有 npx 命令启动、本地脚本启动、远程 HTTP/SSE 地址连接。对于编程场景stdio 方式是主力而像 Figma、蓝湖这类云端工具往往走的是远程地址 Token 鉴权。等下在实战环节我分别演示。3.2 手动添加 Filesystem Server最稳的入门姿势Filesystem Server 可以让 Claude Code 访问指定目录之外的文件系统。默认情况下 Claude Code 只能操作当前项目目录但挂了 filesystem server 之后你可以显式指定其他目录让它读取或写入。添加 MCP Server 有两种主流方式命令行添加或者直接编辑 MCP 配置文件。命令行添加的方式是这样的claude mcp add my-filesystem -e npx -y modelcontextprotocol/server-filesystem /Users/你/想让它访问的目录这里my-filesystem是给这个 Server 起的名字-e npx表示通过 npx 启动/Users/你/想让它访问的目录是传给 Server 的参数也就是它允许访问的根目录。如果传多个目录可以空格隔开继续追加。另一种更可控的方式是手动编辑配置文件。Claude Code 支持项目级的.mcp.json文件放在项目根目录下。下面是我自己常用的一份记录{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/me/Documents, /Users/me/Downloads ] } } }配置好之后在 Claude Code 会话里运行/mcp命令就能看到当前加载的 MCP Server 列表和状态。如果显示 connected说明已经成功挂载如果显示 error那就得按第五部分的方法排查。这里有一个关键的细节值得多说两句npx启动 server 时首次运行会去 npm 仓库下载包所以第一次启动会比较慢甚至出现「看起来像卡住了」的情况。这其实是正常的等它下载完编译好就快了。如果你想要更快的启动速度可以先手动执行一次npx -y modelcontextprotocol/server-filesystem让包缓存到本地后续启动就快很多。3.3 常用 Server 配置参数与启动方式Filesystem 只是开胃菜真正能放大 Claude Code 能力的是那些跟开发工作流强相关的 Server。这里列几个我实际用下来觉得最能提升效率的并给出配置要点。先说说 GitHub Server。它是通过本地 CLI 启动的但需要环境变量存放 GitHub 个人访问令牌。添加时要注意把环境变量传进去claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKENghp_你的Token -e npx -y modelcontextprotocol/server-github如果你觉得命令行太长、容易看花眼就把它写进.mcp.json然后在env字段里配置环境变量{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: ghp_你的Token } } } }然后是 Fetch Server。这个 Server 允许 Claude Code 直接抓取网页内容适合做文档查阅、网页分析。配置起来最简单claude mcp add fetch -e npx -y modelcontextprotocol/server-fetch它没有额外的鉴权参数装上就能用。不过我提醒一句抓取网页内容时注意目标网站是否允许爬取有些站点反爬严格抓回来可能是验证码页面Copilot 和 Claude 都救不了。另外聊一下memoryServer。它可以让 Claude Code 在不同会话间记住关键信息比如你偏好的代码风格、常见的项目约束。配置方式claude mcp add memory -e npx -y modelcontextprotocol/server-memoryMemory 这种存储型 Server 对项目知识管理很有用但存储的数据量不要太大它本质是一个轻量的知识图谱塞太多东西反而会让 Claude 在检索时犯迷糊。3.4 如何验证并调试 MCP 是否真的生效很多朋友配完之后总担心「它到底连上没有」。验证方法其实很简单在 Claude Code 会话里输入/mcp就能看到所有 Server 的加载状态。如果显示 connected说明进程已正常启动如果显示 error那就需要进一步 debug。我推荐一个更直观的验证方式直接给 Claude 发一个只有该 Server 才能完成的任务。比如你配置了 filesystem server那就让它读取你指定目录下的某个文件配置了 GitHub server就让它列出你某个仓库的 issue。如果它能完成任务说明整条链路是通的。还有一种隐蔽的失败情况MCP Server 显示 connected但 Claude 压根不调用它。这种情况多半是模型判断当前任务不需要使用该工具。你可以试着在对话里明确告诉它「用 filesystem 工具帮我看看/Users/me/Documents下有什么文件」用指令强制它调用。如果这样还是不行再看配置文件的 scope 是不是选错了是不是把项目级配置放到了全局或者反过来。4. 实战进阶Figma、VSCode 与多工具联动4.1 Figma MCP获取 Token 的正确姿势Figma MCP 是很多设计师和前端开发者的刚需它能让 Claude Code 直接读取 Figma 设计稿的图层、样式、标注信息对「设计稿转代码」这类工作流帮助极大。热词里「figma mcp token在哪获取」被反复问到我专门详细说一下。步骤不复杂但用错入口的人很多登录 Figma 网页版点击左下角头像。在菜单里选择 Settings设置。进入 Account账号选项卡后往下翻找到 Security authentication安全与认证区块。在 Personal access tokens个人访问令牌部分点击 Generate new token。给它起个名字按需选择权限范围然后生成。生成的 Token 只会完整显示一次务必立刻复制保存。拿到 Token 之后通过 MCP 配置传给 Figma Server。目前的 Figma MCP Server 基本都是走 HTTP/SSE 方式挂载的典型配置长这样{ mcpServers: { figma: { type: http, url: https://your-figma-mcp-server.example.com/mcp, headers: { Authorization: Bearer YOUR_TOKEN } command: npx, args: [-y, figma-developer-mcp, --stdio], env: { FIGMA_API_KEY: YOUR_TOKEN } } } }不同版本的 Figma MCP Server 配置格式略有差异。如果你下载的 Server 包里有 README优先看 README 里给的标准配置别直接抄网上的。我就吃过一次亏照着旧版教程配了FIGMA_API_KEY结果新版 Server 改用FIGMA_ACCESS_TOKEN做环境变量名折腾了快一个小时才排查出来。4.2 在 VSCode 中配置 Claude CodeVSCode 配置 Claude Code 有两种常用姿势。第一种是直接在 VSCode 的集成终端里运行claude命令这种方式最简单不需要额外装任何插件只要你电脑上装好了 Claude Code打开 VSCode 的终端直接敲就行。集成终端里跑 Claude Code 有个隐形优势它能感知当前打开的工作区目录自动把项目上下文带进去比你在系统终端里手动cd到目录更高效。第二种是通过 VSCode 插件来集成。市面上的 Claude Code 插件有不少安装后会在侧边栏或面板里提供一个图形化的 Claude Code 界面。我个人更推荐第一种因为 Claude Code 本身就是为终端设计的交互形态插件界面反而多了一层封装出问题的时候反而不好排查。不管用哪种方式.mcp.json的配置文件都以项目为单位放在项目的根目录下。这里注意一个点.mcp.json会被 Git 追踪如果你想保留自己的本地私有 MCP 配置可以把文件加入.gitignore或者把账号级别的配置放在用户目录下的~/.claude.json里。4.3 与 Codex 等工具配合使用热词里有人提到「claude code和codex」「codex联动burp mcp」。我的看法是这俩工具是同类竞品日常使用不建议同时叠加但确实存在一种分工玩法——Claude Code 负责核心业务代码Codex 用来跑一些独立的脚本和批量任务。如果你非要让两个工具共享同一套 MCP Server 生态也不用担心协议不通。因为 MCP 是开放协议配好的 Server 不仅 Claude Code 能用Codex 等支持 MCP 的工具也能通过同样的标准接入。只是配置文件的格式和存放位置可能会有差异迁过去照着改改就行。这里我不建议把精力花在「让两个 AI 互相调用」上协议还没到那个成熟度实际效果多半会让你失望。真正的生产力提升来自「把重复性工具调用交给 MCP把人留在决策环节」。4.4 进阶场景举例本地数据、数据库、蓝湖、Apifox我实际在项目里还试过几类比较特别的 MCP 联动整理出来给大家参考。本地文件检索场景比如你有一个很大的技术文档目录散落着几百个 Markdown 文件想让 Claude 帮你跨文件总结但又不想把它们全部塞进上下文就可以用 filesystem server 把目录暴露给它让它逐个读取再汇总。这套方案比 RAG 轻量得多适合文档规模不大、不需要向量检索的场景。通达信等本地股票软件数据热词里提到「通达信 股票软件 本地数据 mcp」。这类 MCP 的做法通常是写一个本地脚本读取通达信的数据文件或导出的 CSV再封装成 MCP Server 暴露给 AI。可行性是有的但你要留意两个问题一是通达信的本地数据结构并不公开不同版本可能差异很大二是数据文件可能被软件锁定读取时需要做容错。如果只是做个人研究这个方向值得折腾如果是生产级应用我建议直接用第三方提供的行情接口。数据库操作场景有很多现成的数据库 MCP Server比如 postgres、mysql、sqlite 版本。配置方式大多是npx启动 Server再用环境变量或参数指定数据库连接串。我实践下来的经验是别让 AI 直接在生产库上自由执行写操作。可以配置一个只读账号给 MCP Server或者提前约定它只能执行 SELECT 语句。说到底AI 执行 SQL 的准确性已经不错但出现「意料之外」的 DELETE 或 UPDATE 时你是不想过火葬场式体验的。蓝湖 / Apifox这两个都属于国内团队的 MCP 实现。蓝湖 MCP 可以读取设计标注和切图信息Apifox MCP 可以让 AI 直接查询接口文档、生成接口调用代码。配置方式大同小异核心都是去对应平台生成 API Token然后在 MCP 配置里通过环境变量传入。5. 排坑手册常见问题与排查技巧实录MCP 配置这玩意儿说难不算难但坑是真的多。我把实际踩过的、以及社群里高频出现的问题整理成一张速查表先给大家一个直观对照后面再挑几个典型场景细说。现象可能原因排查思路claude命令找不到Node.js 未安装 / npm 全局路径未配置检查node -v重新安装 Node 并配置 PATHMCP Server 显示 errornpx 下载失败 / 环境变量缺失 / 启动参数错误手动在终端运行启动命令看报错检查 env 字段Server connected 但 AI 不调用模型任务判断未触发 / scope 配置不对在会话中显式要求调用该工具检查配置文件位置Windows 上提示脚本禁止运行PowerShell 执行策略受限执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUsermacOS 无法读取目标目录终端没有文件夹访问权限在系统设置的隐私设置里给终端授权Figma 连接 401Token 无效或权限不足重新生成 Token检查环境变量名是否正确初次启动 MCP Server 卡很久npx 正在下载依赖包等待或手动预下载包到本地缓存我详细讲几个最容易让人崩溃的场景。场景一MCP Server 配置好了但状态一直是 error遇到这个情况先别急着怀疑配置文件格式。有一个关键技巧把你配置文件里的command和args拼成一句完整命令自己手动在终端里跑一遍。比如配置是npx -y modelcontextprotocol/server-filesystem /some/dir你就在终端手动执行这条命令看看会输出什么。如果终端里就直接报错了那说明是 server 本身的问题跟 Claude Code 没任何关系。常见的错误是 node 版本太低不支持某些语法或者目录不存在。我之前有一次就是配置文件里写了一个不存在的目录结果 server 进程一启动就退出排查了半天才发现是手滑多打了一个字母。场景二Claude 说它用不了某个工具MCP 工具对模型来说是「按需加载」的。有时候你配好了 Server但 Claude 可能不会主动想起用它。并不是模型坏了而是它对你的上下文和当前任务的判断还没到需要调用工具的程度。这种时候最有效的办法就是「明牌」在对话里直接告诉它「你有没有 figma 工具帮我读取这个文件链接里的 Frame 信息」。它收到明确的指令后就会主动调用对应的 MCP 工具。场景三Windows 11 上一切正常但一重启就出问题「claude code win11」相关的不少问题出在环境变量持久化上。通过命令行设置的临时环境变量只在当前会话有效重启终端就没了。如果你从某个博客复制了一段set FIGMA_API_KEYxxx的命令它只对当前窗口有效。正确的做法是把环境变量写进系统环境变量或者干脆写进.mcp.json的env字段。这也是我为什么反复强调直接用配置文件管理环境变量的原因——它一次配置长期生效不会因为重启而丢失。场景四VSCode 里跑 Claude Code 看不到自己装的 Server这个现象很经典。你在系统终端里用claude mcp add添加的 Server进了 VSCode 集成终端却发现/mcp列表里没有。原因是claude mcp add默认写入的是用户级别的配置而 VSCode 集成终端加载的项目可能用了项目级配置覆盖了它。解决办法有两个选择一个固定的配置层级全部用全局配置或全部用项目级.mcp.json。我个人更推荐项目级配置因为团队协作时队友 clone 代码后拉取到的就是一套可复现的 MCP 环境。6. 再往深走一点RAG、Memory、Skills 与 MCP 的边界6.1 RAG 和 MCP 到底有什么区别热词里有一对很容易混淆的概念RAG 和 MCP。很多人会问我已经有 RAG 了为什么还要用 MCP直接用向量数据库存文档不行吗两者解决的问题维度不一样。RAG检索增强生成解决的是「AI 不知道某些知识但可以通过检索把答案找出来」的问题核心是知识库检索。MCP 解决的是「AI 不知道怎么操作外部系统和数据源」的问题核心是工具调用。一个是「找信息」一个是「做动作」。打个比方RAG 像图书馆管理员你问它什么它去书库里帮你查资料MCP 像你的助手你说「帮我把这堆文件整理好」它直接动手去整理。两者其实是可以共存的用 RAG 给 AI 补充专业领域知识用 MCP 让 AI 具备调用工具和数据源的能力。很多大型 Agent 应用里这两者是同时存在的不是非此即彼的关系。6.2 Skills、Memory 和 MCP 的扩展玩法Anthropic 官方一直在推「Agent Skills」的概念。如果说 MCP 是给 AI 连外部工具那 Skills 更像是给 AI 内置「领域技能包」——比如一个标准的代码审查流程、一个固定的日报生成模板都可以封装成 Skill让 Claude 在对应场景下自动使用。我在实践中的体会是当项目变大之后MCP 和 Skills 的边界会越来越模糊。你会发现完全可以把一个 Skill 实现为本地脚本 MCP Server 的组合让 Claude Code 通过 MCP 调用这部分能力。关键是要保持配置的可维护性不要让各种 Server 和 Skill 堆成一团乱麻。我自己的习惯是凡是需要外部数据的走 MCP凡是不需要外部数据、纯粹是处理流程规范的走 Skill。这样划分后续维护的时候头脑会很清晰。另外如果你做的是「Agent Memory」类应用MCP Memory Server 值得重点关注。它能让 AI 在多个会话间记住项目偏好、用户习惯、决策记录。配好之后你重启终端再进入项目AI 还能记得「这个项目里用户偏好用 pnpm 而不是 npm」「接口文档统一放在 docs/api 目录」这类约定。这种「越用越懂你」的体验跟每次从头开始聊天的感觉完全是两个时代的东西。最后说点实际的个人体会玩 Claude Code 和 MCP 这几个月最大的感悟是这些工具的门槛其实不在安装配置而在于你能否理解「协议思维」。你不需要记住每个 Server 的每个参数但你必须理解 Host、Server、工具、资源、上下文这几个概念之间的关系。一旦理解了这个模型任何新的 MCP Server 上车都只是读一遍 README、填几行参数的事。如果这篇文章只能留下一个建议那就是不要一上来就装全家桶。先把 Filesystem 配好把一个真实任务完整跑通再逐步扩展 GitHub、Figma、Fetch。每配一个新 Server都花两分钟想想——这个能力是不是我真正高频需要的是高频需要就值得花时间配置低频需要直接用命令行或脚本反而更快。配置的复杂度一旦失控维护成本很快就会超过工具带来的收益。到最后再送一个小技巧MCP Server 的日志和报错是排错的第一现场。大多数 Server 在启动失败时会直接输出原因到终端别急着去搜索引擎先仔细把报错读一遍。这些报错信息往往已经把答案送到你面前了。