做技术写作这些年，我见过太多工具刚火起来就被吹成银弹，Claude Code 和 MCP 最近的热度也一样。但说实话，Claude Code 并不是一个"终端里的聊天窗口"，MCP 也不是又一个看着高级、实际没人用的协议缩写。它俩组合起来，解决的是 AI 编程工具真正落地的那个大问题：让模型不只"会说话"，还能自己动手去读文件、调接口、改仓库、看设计稿。
这篇教程我准备了很久，把从安装到配置、从原理到实战的路子都按我自己的使用经验重新捋了一遍。会覆盖 Windows 和 macOS 两套环境，讲清楚 Claude Code 和 MCP 到底是什么关系，为什么你的项目需要它，以及怎么用配置文件和命令把 GitHub、Figma、蓝湖、Apifox 这类服务全部接进来。新手能照着一步步做，已经在用的人也可以直接跳到最后两节看排查方案和进阶玩法。
1. 先搞清楚：Claude Code 与 MCP 各自解决什么问题
1.1 Claude Code 是什么
Claude Code 是 Anthropic 推出的命令行 AI 编程助手，核心是能在终端里直接和 Claude 模型对话，并让它读取你的代码、修改文件、执行命令、操作 Git。你可以把它理解成一个住在你电脑里的"结对程序员"，但它不是简单地把聊天记录贴到编辑器里，而是真正长在你的项目上下文里。
我第一次用的时候最直观的感受是：它和普通 AI 聊天网站完全不一样。普通聊天你需要把代码复制粘贴进去，它给你一段修改建议，你再手动应用，来回折腾很费劲。Claude Code 则可以直接扫当前目录，看 diff，改文件，跑测试，甚至连续执行一系列命令。它本质上不是编辑器插件，而是一个可以独立运行的 Agent，而 VS Code 里那个插件只是它的一层外壳而已。
当然，它也不是万能的。它的能力边界很大程度取决于你给它接了多少"工具"，比如能不能读某个特定格式的文件、能不能操作某个外部系统。这就要引出 MCP 了。
1.2 MCP：“模型上下文协议”到底是啥
MCP 全称 Model Context Protocol，是 Anthropic 在 2024 年底开源的一套开放标准。你可以把它理解成 AI 界的 USB-C 接口：以前每个 AI 工具对接一个外部系统，都得写专门的私有代码，接口五花八门，换一个模型就得重来一整套。有了 MCP 之后，模型、数据源、工具之间有了统一的协议规范，任何支持 MCP 的客户端都能以同样的方式去调用任何兼容 MCP 的服务器。
在 Claude Code 里，MCP 承担的具体工作是连接外部资源。比如我想让 Claude 读取一个 Figma 设计稿的尺寸，或者直接查数据库里的订单表，靠模型自身的知识是做不到的，因为模型拿不到那些数据。但通过 MCP，Claude Code 可以调用一个"Figma Server"或"数据库 Server"，由这个 Server 去真实地访问外部系统，再把结果返回给模型。
所以你可以这样记：Claude Code 是那个干活的 Agent，MCP 是它伸出去的手，MCP Server 是手上能换的"工具头"。没有合适的工具头，它再聪明也没法直接操作你的设计稿和数据库。
2. 从零安装：环境准备与三分钟跑通 Claude Code
2.1 安装 Node.js 和包管理器
Claude Code 目前最主要的安装方式是 npm，所以第一步是把 Node.js 装好。这一步很多人会踩坑，因为直接去官网下了个最新版，结果过两个月你会发现版本兼容出问题。我建议装 LTS 长期支持版，比如现在常用的 Node.js 20 LTS 或更高版本，至少在 18 以上。
很多人问要不要用 nvm，我的建议是：如果你日常会同时开发多个 Node 项目，那一定用 nvm 这种版本管理器，别直接在系统层面装死版本。macOS 上可以用 Homebrew 装 nvm：
brew install nvm # 然后按提示在 shell 配置文件里加两行 source 语句 # 再安装某个具体版本 nvm install 20 nvm use 20Windows 上可以直接用官方安装包，或者通过 winget 装：
winget install OpenJS.NodeJS.LTS装完之后在终端里确认一下，输出两个版本号就说明环境正常：
node -v npm -v接下来所有命令都以 npm 为基础，所以这一步千万别跳过。
2.2 安装 Claude Code 本体
环境就绪后，安装其实就是一条命令：
npm install -g @anthropic-ai/claude-code全局安装的好处是任何目录下都能直接使用claude命令。如果 npm 全局安装失败，多是因为权限问题，macOS 上记得在命令前加sudo，Windows 上要确保终端以管理员身份运行时再执行。
安装完成检查版本：
claude --version这时候直接输入claude就能进入交互界面。第一次运行会让你登录 Claude 账号并授权，走完授权流程后会默认允许当前目录作为项目上下文。后续再用的时候，在项目根目录敲claude启动即可。
另外，如果你用的是 VS Code，可以直接在扩展商店搜 "Claude Code" 安装官方插件。插件本身不包含模型运行，它还是要调用系统里装好的claude命令，所以即使你用插件，也建议先把命令行版本装好。装完之后按Ctrl+Shift+P输入 "Claude" 找到入口就能打开侧边栏聊天窗口。
2.3 登录鉴权与基础权限设置
Claude Code 第一次启动会走设备码授权流程，跟着终端提示打开浏览器确认身份即可。这里有一点容易忽略：同一个账号登录后，在不同终端会话里是共享登录态的，但如果你平时用多个 Claude 账号，要注意claude /logout先退出再切换，别在错误项目里用错账号。
权限设置上，Claude Code 提供几种模式，整理成表方便对比：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 默认模式 | 执行命令、写文件前逐次询问 | 日常开发，安全性最高 |
| plan 模式 | 只做分析和计划，不实际修改 | 复杂需求的设计阶段 |
| acceptEdits 模式 | 自动接受对当前文件的编辑 | 已明确范围的重构、补全 |
| bypassPermissions | 跳过所有授权，直接执行 | 自动化脚本、CI/CD 中 |
我自己的建议是：日常开发老老实实用默认模式，让 Claude 每次动手前解释清楚它要干什么。只在跑自动化流水线、完全可信的脚本时才用 bypassPermissions，而且一定要加上--dangerously-skip-permissions参数来明示你清楚风险。Claude Code 有权限，但使用权限的人要心里有数。
2.4 升级、卸载与版本管理
Claude Code 迭代非常快，我基本每周都会碰到新功能更新。升级很简单：
npm update -g @anthropic-ai/claude-code卸载则要注意清理残留：
npm uninstall -g @anthropic-ai/claude-code # 然后手动删除配置文件 rm -rf ~/.claude rm -rf ~/.claude.json # macOS/LinuxWindows 上对应的路径一般是C:\Users\你的用户名\.claude。如果你在 VS Code 里也装过插件，记得去扩展面板里一起禁用删除，否则残留配置会影响重装后的体验。
3. MCP 运行原理：host、server、tool 的关系
3.1 一次 MCP 调用的完整链路
很多人配置完 MCP 但完全不知道它是怎么跑起来的，出了问题也不知从何排查。这里我用最直白的方式把链路讲一遍。
MCP 体系里有三个角色：MCP Host、MCP Client 和 MCP Server。在 Claude Code 场景下，Host 就是 Claude Code 本身，它既是对话入口，也是发起 MCP 请求的那个主体。Client 通常内嵌在 Host 里，负责跟 Server 通信。Server 是真正干活的进程，比如文件系统服务器或者 Figma 服务器。
当你在对话里说"帮我看看 aaaa 目录下的文件结构"，Claude 模型会根据用户意图决定调用哪个工具。这个决定过程会通过 Client 向 Server 发送一条标准化的请求，Server 执行实际操作后把结果返回给模型，模型再组织语言回复你。整个过程对用户是透明的，你在对话里看到的只是"正在调用工具 filesystem"这类提示。
这里最关键的一点是：MCP 不是把整个对话历史发给 Server，而是按需调用具体工具。也就是说，MCP 更像"工具箱"，而不是"知识库"，它不存你的业务数据，只在你明确需要某个能力时被拉起来执行。
3.2 stdio 与 SSE 两种通信模式
MCP Server 和 Client 之间的通信有几种方式，最开始你只需要弄懂两个：stdio 模式和 SSE 模式。
stdio 模式是最常见的本地模式。Claude Code 启动时会直接拉起一个子进程运行 MCP Server，二者通过标准输入输出传递 JSON 消息。这种模式配置简单、启动快，不需要开端口，适合文件系统、Git 这类本地工具。缺点是这个 Server 进程只能在 Claude Code 运行时存活，不能让远程服务也来调用。
SSE 模式则基于 HTTP，Server 作为独立服务运行，可以通过 URL 对外提供服务。适合把 MCP Server 部署在服务器上，让多个客户端共享访问。比如常见的 "Apifox MCP" 或者远端的数据库 MCP，就可以用 SSE 方式接入。
配置的时候你会在 JSON 里看到command和args，那是 stdio 模式；如果看到url字段，那就是 SSE 模式。后期排查时先分清楚自己的 Server 属于哪种，问题就解决一半了。
3.3 值得装进生产环境的 MCP Server 清单
MCP Server 现在非常多，有些是官方示例，有些是第三方公司维护的，我按场景列几个我从实际项目里验证过、确实用得上的：
| Server | 用途 | 配置方式 |
|---|---|---|
| filesystem | 让 Claude 直接读项目目录、写文件 | stdio |
| github | 操作 issue、PR、代码仓库 | stdio 或远程 |
| figma-developer-mcp | 读取设计稿节点、生成 CSS 代码 | stdio |
| Apifox MCP | 自动执行接口调试、断言检查 | stdio 或远程 |
| 蓝湖 MCP | 读取设计标注、切图数据 | stdio |
| memory | 让 Claude 持久化保存关键信息 | stdio |
| DevSpace MCP | 管理远程 Kubernetes 开发环境 | 远程 |
这里要特别提醒：官方示例仓库里的"server-github""server-filesystem"等包经常调整，有些已改名或合并到新仓库，跑npx -y @modelcontextprotocol/server-xxx前先到 npm 上看一眼最新版本和废弃提示。我踩过最大的坑是照着三个月前的教程敲命令，结果一开始就报 package not found。
4. Claude Code 配置 MCP 的三种方式
4.1 命令行方式：claude mcp add 快速接入
Claude Code 提供了一套比较完整的 MCP 管理命令，建议先记下这几个常用指令：
claude mcp list claude mcp add <name> -- <command> [args...] claude mcp get <name> claude mcp remove <name>用命令行方式添加一个 filesystem Server 是这样的：
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/myproject这行命令的意思是把名为 filesystem 的 Server 注册到当前项目，执行方式是npx -y @modelcontextprotocol/server-filesystem，并传一个目录参数。加完以后用claude mcp list确认状态，看到 "connected" 就说明 Server 已经拉起来了。
命令行方式的优点是有 tab 提示和错误反馈，适合一边测试一边改。缺点是不太方便做团队统一管理，因为命令是写进本地配置里的，团队成员还是得各自执行一遍。
4.2 项目级配置文件 .mcp.json
比命令行稍微"工程化"一点的做法是在项目根目录放一个.mcp.json文件。Claude Code 读取到这个文件后会自动把里面声明的 Server 加载到当前项目，这样团队成员 clone 下来仓库就能直接用，不用每个人手工敲命令。
一个典型的 stdio 配置长这样：
{ "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-filesystem", "/Users/me/myproject" ] } } }如果要配置 SSE 远程服务，则是这种结构：
{ "mcpServers": { "remote": { "type": "sse", "url": "http://localhost:8931/sse" } } }文件名不要搞错，.mcp.json不是mcp.json也不是mcp-server.json。我见过太多人在 config 里写了一大堆，发现 Claude Code 根本没加载，十有八九就是文件名不对，或者文件放到了子目录里。项目级配置只认项目根目录。
4.3 全局配置与作用域选择
Claude Code 的 MCP 配置有作用域概念，大致分三种：
- 项目级：只对当前目录生效，写在
.mcp.json，适合项目相关的 Server。 - 用户级：对你当前账号在本机所有项目生效，保存在
~/.claude.json或~/.claude/mcp.json，适合个人常用工具。 - 本地级：仅在当前机器当前会话生效，适合临时测试的 Server。
命令行添加时可以用参数指定作用域。比如：
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-github日常使用中我的原则是：跟项目绑定的服务（比如项目专用的数据库、当前项目文件路径）放进项目级；个人通用的工具（如文件系统、GitHub）放大作用域，避免每个项目重复配置。如果管理不了作用域导致同一个 Server 被加载多次，反而会拖慢启动速度。
4.4 验证配置是否生效
配置好之后不要急着开工，先做一次完整验证。最简单的办法是进入 Claude Code 对话，直接问一句"MCP 工具里有哪些"或者"列出现在可用的工具"，它会展示已加载的工具列表。如果看到你注册的 Server 对应工具，说明连接成功了。
命令行层面也可以看状态：
claude mcp list看到 "connected/ready" 字样就正常。如果显示 "failed" 或 "not found"，重点检查路径、包名、node/npx 是否在 PATH 里。记住一句话：MCP Server 是独立进程，任何你想在终端里手动执行的命令，都必须保证 Claude Code 这个终端环境下也能执行成功。
5. 实操案例：从 GitHub 到设计稿到本地文件
5.1 接入 GitHub MCP 管理 issue 和 PR
GitHub 是开发者最常用的外部系统，把 GitHub MCP 接进来的价值在于：你可以直接在对话里让 Claude 拉取一个 issue 列表、给 PR 做代码 review、甚至整理发布说明，全程不用手动开仓库页面。
配置方式如下：
claude mcp add github -- npx -y @modelcontextprotocol/server-github这个包运行时需要 GitHub Token，通常会在首次启动时提示设置环境变量GITHUB_PERSONAL_TOKEN。Token 已经在 GitHub 的 Settings → Developer settings → Personal access tokens 里生成，权限按最小化原则勾选 repo、read:org 这几项，别图省事直接给 full control。
接入后可以试试这些指令：
- "帮我把这个仓库最近一周的 issue 汇总成清单"
- "看我当前分支的 PR，列一下修改文件"
- "根据这个 issue 内容草拟一条 commit message"
我实测下来，最稳的反而是 issue 数据整理这类低风险操作，涉及写操作（比如直接合 PR、改分支）还是建议先在默认权限模式下由 Claude 逐条确认，避免手滑执行危险命令。
5.2 文件系统 MCP Server：让 Claude 直接读写项目
filesystem Server 可以说是本地开发里我用得最频繁的一个，它让 Claude 能绕过很多"上下文文件太多"的限制，按需读取指定目录和文件。
推荐用官方维护的@modelcontextprotocol/server-filesystem，配置时注意把路径固定在你允许它访问的目录，而不是直接给根目录。一旦给了/，Claude 在默认权限模式下一路确认，可能有覆盖配置文件的危险。
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/workspace路径参数很关键。比如你把工作区限定在/Users/me/workspace，Claude 就只能在这个范围内读文件、写文件、列目录。对于多项目并行的人，建议按项目配置，不要全局共享一个宽泛的访问范围。
5.3 Figma MCP：token 获取与设计稿取色
前端同事问得最多的热词就是"Figma MCP token 在哪获取"，我这里完整说一遍流程。
首先在 Figma 官方客户端（网页端也可以）点击右上角头像，进入 Account settings，左侧菜单找到 Security，往下滚到 Personal access tokens 区域，点 Generate new token，输入 token 名称，选择有效期限，生成后立刻复制保存。Figma 只显示这一次，刷新页面就再也看不到了，务必放在本机密码管理器里。
拿到 token 后，配置 Figma 的 MCP Server：
export FIGMA_ACCESS_TOKEN="你的token" claude mcp add figma -- npx -y figma-developer-mcp --stdio这里对环境变量的依赖要留意，每次新开终端如果 token 没写入 shell 配置文件，MCP Server 就会因为缺 token 启动失败。建议在.zshrc或.bashrc里加上 export，或者用 direnv 做项目级环境变量管理。
接入之后，你能让 Claude 读取指定 Figma 文件的节点树、获取选中的设计区域内容，甚至直接生成对应颜色、字体、间距的 CSS 变量。对前端来说，"从设计稿到代码变量"这个链路省掉的可不是一点时间。
5.4 其他好用的 Server：蓝湖、Apifox、数据库
- 蓝湖 MCP：蓝湖是国内团队常用的设计交付平台，官方出的 MCP Server 把设计标注读取能力接进来后，Claude 可以拿到精确的尺寸、颜色、切图信息，替代手工看标注的环节。
- Apifox MCP：接口调试工具的 MCP 接入后，Claude 能直接调用项目里的接口定义，执行调试请求并核对返回值。自动化接口冒烟测试的体验很爽，记得给 Server 配置只读权限为主。
- 数据库 MCP：社区里有很多 MySQL/PostgreSQL 的 MCP Server，让 Claude 直接跑只读 SQL 查询，快速理解业务数据结构。这类 Server 安全性要求最高，建议只开放只读账号，且禁止执行 DDL/DML。
我判断一个第三方 Server 值不值得装，主要看三点：官方在不在维护、是否有明确的权限控制、配置文档是否更新及时。很多个人写的 Server 用一两次就坏，因为依赖的接口升级了，还不如自己包一层 API。
6. 进阶玩法：Skills、自定义 Server 与 Spring Boot 集成
6.1 Skills 是什么，和 MCP 的区别
最近热词里经常出现 "AI Agent Skill Memory MCP"，很多新人会把 Skill 和 MCP 搞混。这两个东西的定位完全不同。
Skills 是给 Claude Code 预置的一套"怎么做事"的提示词和流程模板，更像给模型的一份操作手册，比如"项目里提交 PR 之前必须跑这五个检查项"。MCP 是给模型接上"能做什么事"的外部工具，更像实际的手套和扳手。
实际使用中，我一般把二者叠加：Skill 规定步骤和规范，MCP 提供执行每个步骤的具体能力。比如写一个"发布流程" Skill，里面要求先跑测试、再检查 lint、再更新 changelog、最后发 GitHub Release，每一步都调用对应的 MCP Server 工具去完成。
Claude Code 里安装 Skill 的方式目前还在快速迭代，主流做法是把写好的 SKILL 目录放进~/.claude/skills，或者在项目根目录放.claude/skills，然后每次启动会被自动扫描。我自己习惯用 Markdown 文件写 Skill 内容，里面包含描述、触发条件和操作步骤，这样至少有版本控制，改起来也方便。
6.2 用 Node.js 写一个本地的 MCP Server
有些需求是现成 Server 满足不了的，这时候自己写一个 MCP Server 反而是最快路径。只要会 Node.js，十几行代码就能起一个能跑的 Server。
先装依赖：
npm install @modelcontextprotocol/sdk一个最简单的 Server 代码如下：
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; const server = new McpServer({ name: "demo-server", version: "1.0.0", }); server.tool( "getTime", "获取当前服务器时间", {}, async () => { return { content: [{ type: "text", text: new Date().toISOString() }] }; } ); const transport = new StdioServerTransport(); await server.connect(transport);这段代码会创建一个通过 stdio 通信的 MCP Server，提供一个名为getTime的工具。保存为server.js，用node server.js能正常运行后，在 Claude Code 里这样接入：
claude mcp add demo -- node /path/to/server.js自定义 Server 的典型场景是：把团队内部平台封装成一个 MCP 工具，让 Claude 能查工单、看日志、发部署请求。这样一来，你的 AI 助手就不再是通用玩具，而是真正长在你公司技术体系里的效率工具。
6.3 Java Spring Boot 集成 MCP 的 JDK/依赖注意点
热词里频繁出现 "Spring Boot MCP JDK"，是因为 Java 开发者也想把 MCP 接进已有服务。目前 Spring AI 官方提供了 MCP Server 的集成模块，可以让你的 Spring Boot 应用直接暴露 MCP 端点。
先说最容易踩的坑：JDK 版本。Spring AI 当前主流版本对 JDK 17 以上支持最好，如果你还在用 JDK 8 或者 11，大概率会遇到依赖冲突或者注解扫描不生效的问题。我建议先升级到 JDK 17 LTS，同时把 Spring Boot 升到 3.x，再引入 Spring AI 的 MCP 相关 starter，依赖坐标建议去 Spring Initializr 页面查询当前稳定版本，不要自己猜版本号。
接着把你的业务 Service 方法注册成 MCP 工具，Spring AI 会自动暴露。启动应用后，MCP Client 通过 SSE 方式访问/mcp/sse之类的端点，就能调用你 Service 里的方法。这套方案的亮点是：团队已有的 Java 服务不用大改，加几个注解就能变成 AI Agent 能用的工具，兼容性比我预想的好。
6.4 RAG 和 MCP 的正确选择
"RAG 和 MCP 区别"是很多人分不清的问题。RAG 是把外部知识检索出来，塞进模型的上下文里，让模型"更有知识"。MCP 是让模型能够"操作外部系统"，让模型"更有手脚"。
举个例子：你问 Claude 公司内部员工手册里写了什么，这是 RAG 的活，应该先做向量化、检索、再问答。你让 Claude 帮你提交一条请假审批，这是 MCP 的活，需要接 OA 系统的 MCP Server。两者完全不是替代关系，而是不同层次的能力。实际落地时，RAG 解决的"知识盲区"可以让 Claude Code 变得更懂你项目，MCP 解决的"能力边界"可以让 Claude Code 从建议者变成执行者。搭好这两块，你的 AI 开发环境才算是完整形态。
7. 高频问题排查与独家避坑手册
7.1 连接不了 / 工具不可用
MCP 配置好后最常见的问题是 Claude Code 里看不到工具，或者显示 disconnected。我的排查顺序是：
- 打开一个新终端，手动执行配置文件里的 command 和 args，看是否能正常运行。
- 检查
claude mcp list的输出，看状态是 connected 还是 failed。 - 如果在 VS Code 里使用，重启窗口让 Claude Code 重新加载配置。
- 确认 npx/node 路径在 Claude Code 启动的终端里可用，尤其是 macOS 上通过 GUI 启动时有 PATH 缺失问题。
我在 mac 上踩过最隐蔽的坑是 nvm 安装的 Node 不在系统路径里，导致 Claude Code 找得到 node 但子进程找不到，后来在配置里写死 node 完整路径才解决。如果你也遇到 "ENOENT" 或 "command not found" 这类报错，优先查 PATH。
7.2 工具调用报错 / 超时
MCP Server 本身启动成功，但调用某个工具时报错，大概率是权限或参数问题。GitHub token 权限不足时，工具会返回 403；Figma token 过期时，返回 401；文件写入路径超出限定范围时，返回 permission denied。
超时问题则要注意：stdio 模式下的本地 Server 启动通常只要一两秒，如果反复出现超时，可能是 npx 正在下载依赖包，第一次运行需要耐心等一会儿。远程 SSE 模式超时则要先检查服务器防火墙和端口开放情况，再考虑网络链路。不要一上来就调大超时时间，那是掩盖问题，不是解决问题。
7.3 权限太大？安全建议
Claude Code 能读文件、执行命令，MCP Server 又能访问 GitHub、数据库，这两者叠加，安全边界必须非常明确。我的安全底线是：
- 默认模式打开，不图省事关闭确认机制。
- MCP Server 的 token 使用最小权限，能只读不写，能单仓库不给全组织。
- 本地文件路径限制到项目目录内，不暴露整个用户目录。
- 定期检查
.claude目录下的配置，及时删除不用的 Server 和已泄露的 token。 - 团队协作时，把
.mcp.json里涉及敏感凭据的环境变量标记为<env>占位，不要直接提交真实 token 到仓库。
有一次我在测试时给文件系统 Server 配了~目录，结果 Claude 在一次代码审查中主动把用户目录下所有 config 文件全列出来了，虽然只是读取没造成破坏，但足够让人冒冷汗。从那以后，我所有本地配置都改成了最小必要目录。
7.4 安装、卸载与残留文件
重装 Claude Code 前，先理解它有哪些配置残留。~/.claude目录里存放着 Skills、MCP 配置、历史会话；~/.claude.json里存放着全局状态。如果你遇到登录异常或者权限莫名抽风，先重命名备份这两个路径，再重新登录，通常能解决大部分玄学问题，不用急着卸载重装。
真正的卸载不只是npm uninstall -g，还要清掉插件和缓存。VS Code 插件卸载后，建议重启一次软件再验证。Windows 上如果遇到 PATH 残留的旧版本，执行where claude或Get-Command claude看看到底跑的是哪个路径，很多时候你以为在跑新版本，其实还是旧版。
7.5 其他常见问题速查
| 现象 | 可能原因 | 处理方式 |
|---|---|---|
| claude 命令找不到 | npm 全局目录不在 PATH | 设置 npm prefix 并 export 到 PATH |
| 启动时报 OpenAI API key 错误 | 误设了环境变量 | 检查OPENAI_API_KEY等变量是否冲突 |
| MCP Server 启动即退 | 参数错误或 token 缺失 | 手动执行 command 看报错输出 |
| Skill 不生效 | 目录名或格式不对 | 检查~/.claude/skills和项目.claude/skills |
| 多开终端后配置互相干扰 | 全局与项目级作用域重叠 | 用claude mcp list查看作用域并清理 |
8. 我的个人实践心得与工作流建议
最后说说我用 Claude Code 和 MCP 这两个月最有体感的变化。以前我开发一个新功能，流程基本是：读代码、查接口、找设计稿、写实现、跑测试，光"上下文切换"就够消耗半天注意力。现在我的工作流变成：在项目根目录打开 Claude Code，让它加载 filesystem 和 github 两个 MCP Server，遇到设计图需求就在对话里引用 Figma 文件，代码写完让 Claude 直接跑测试并把结果贴回来。
这套工作流不是让 AI 完全替代我写代码，而是把很多"系统性动作"交给它，我专注在决策和评审上。我一直认为，AI 编程工具的价值不在"一个人写一百行代码"，而在"一个人能同时处理原本需要多个系统来回切换的复杂任务"。而帮你打通这些系统的，正是 MCP。
如果你刚开始接触，我建议不要贪多，先把 filesystem 和 github 两个 Server 配好，用一周时间习惯 ClCode 的交互节奏，再逐步引入设计稿、数据库、API 调试等能力。每加一个 Server，都要问自己：这真的让我的工作流变短了吗？如果只是多了一个聊天框里能看到的工具图标，那它还不值得配置。真正有效的接入，一定是某个操作步骤明显减少、某个信息获取明显变快。沿着这个标准去选型，你就不会在 MCP 的工具海洋里迷路。
