先直接说结论Claude Code 是 Anthropic 官方出品的终端 AI 编程助手MCPModel Context Protocol是 Anthropic 在 2024 年底开源的一套模型上下文协议两者配合起来Claude Code 就不再只是个“会改代码的聊天框”而是一个能调用外部工具、读取文件系统、操作设计稿、控制浏览器的全能 agent。这篇教程我会按自己实际使用的路径来写从环境准备、安装配置到 MCP 服务器接入、Skill 用法再到各种踩坑记录尽量让你看完就能上手。适合刚接触 Claude Code 的开发者也适合已经装了但没用明白 MCP 的人。1. 先搞懂核心概念Claude Code 和 MCP 分别解决什么问题1.1 Claude Code 不是 IDE是跑在终端里的“同事”第一次用 Claude Code 的人都会有个困惑它明明叫 Code怎么打开是个黑底命令行其实这正是它的设计取向。Claude Code 本质上是一个命令行交互式 agent你的项目目录就是它的工作台。它可以直接读取仓库里的代码、搜索文件、执行命令、运行测试甚至帮你提交代码。对比传统 AI 编程工具比如在网页端粘贴代码再复制回来Claude Code 的优势在于它“住在你的项目里”。我举一个实际场景你接手一个没文档的 legacy 项目想知道某个 API 是从哪里被调用的。在 Claude Code 里你只需要一句“帮我查一下这个函数的所有调用链并说明数据流向”它会自己跑 grep、读文件、整理结论。这背后靠的是它内置的一组 agent 能力读文件、编辑文件、执行 shell 命令、多步规划。而这些能力是“内置”的MCP 则负责把这份能力延伸到项目之外的世界。1.2 MCP 是 AI 世界的 USB-C 接口MCP 这个协议解决的是一个非常实际的问题每个 AI 应用都要对接不同的数据源和工具如果每个都做私有适配生态就全碎了。MCP 的做法是标准化——AI 应用host通过 MCP 协议去连接外部能力server你只需要按协议实现一个 MCP server任何支持 MCP 的客户端都能用。用生活化的类比MCP server 就像打印机的驱动。你买打印机不用管它是 HP 还是 Canon只需要装一个符合 USB-C 标准的驱动电脑就能识别。MCP 就是那个“USB-C 标准”Claude Code 是电脑Figma、Blender、浏览器、数据库这些工具就是打印机。没有 MCP 之前每个工具都要给 AI 单独开接口有了 MCP一套协议全解决。1.3 为什么要组合使用Claude Code 内置的工具解决的是“代码工作流内部”的问题而 MCP 解决的是“代码工作流外部”的问题。举个我实际做过的例子我需要让 Claude Code 读一个 Figma 设计稿的图层结构然后生成对应的页面前端代码。如果没有 MCP我得手动把设计稿导出成 JSON 再塞给 Claude装了 Figma MCP server 之后Claude Code 直接通过接口拉取设计稿数据整个过程自动化了。所以我的建议是先用好 Claude Code 自带能力等熟悉了再引入 MCP。如果你的需求已经很明确比如要操作浏览器、要连数据库、要读设计稿那直接上对应的 MCP server 会省很多事。2. 安装与基础配置把 Claude Code 跑起来2.1 安装前的准备安装 Claude Code 之前你需要确认几件事有 Node.js 环境建议版本在 18 以上。Claude Code 本身是 Node 写的 CLI 工具通过 npm 全局安装。一个 Anthropic 账号并且有可用的 API Key 或订阅额度。如果你用的是订阅制直接登录授权就行。如果在大陆地区使用网络和模型访问的可用性需要你自己评估和解决。这一点我不展开但确实是很多人卡住的地方。另外我想提醒一点Claude Code 对终端环境有要求建议用 macOS 自带的 Terminal、iTerm2或者 Windows 上的 Windows Terminal。部分旧的终端模拟器在渲染交互式界面时会有问题比如光标错位、输出刷新异常这类问题排查起来很浪费时间。2.2 macOS / Linux 安装步骤在 macOS 或 Linux 上安装路径主要有两种第一种用 npm 全局安装npm install -g anthropic-ai/claude-code装完直接运行claude首次运行会引导你登录跳转浏览器授权你的 Anthropic 账号授权完成后回到终端就能用了。第二种用官方原生安装器。Anthropic 提供了一键安装脚本会按系统架构自动安装不需要预先装 Node.js。这种方式适合不想在机器上装 Node 的开发者。安装命令是curl -fsSL https://claude.ai/install.sh | bash两种方式装完之后你可以跑一下claude doctor来检查环境是否正常。这个命令会检查 Node 版本、权限、登录状态等关键项有问题会直接提示比手动排查快很多。2.3 Windows 安装的注意事项Windows 上装 Claude Code 有两条路一是通过 WSLWindows Subsystem for Linux。我推荐这种方式因为 Claude Code 在 Linux 环境里运行最稳定而且 WSL 里跑的命令和真实项目的部署环境更接近。二是直接在 Windows 的 PowerShell 或 Windows Terminal 里用 npm 安装。能用但有两个坑需要注意如果你的项目里用了 bash 脚本、Makefile、shell 工具链Claude Code 在 PowerShell 里执行这些命令会出错。它默认调用的 shell 跟你当前终端一致遇到错只能切换成 Git Bash 或者手动装 WSL。路径分隔符问题。Windows 路径是反斜杠很多命令和工具默认用正斜杠Claude Code 虽然做了兼容但复杂的 shell 命令偶尔会踩坑。我的实际建议Windows 用户直接上 WSL别折腾原生。这不是说原生不能用而是 WSL 能帮你省掉后面隐藏的 80% 兼容性问题。2.4 在 VS Code 里配置 Claude Code很多热搜词里都有“vscode 配置 claude code”确实VS Code 是 Claude Code 使用频率最高的编辑环境之一。官方提供了 Claude Code for VS Code 扩展装完以后在左侧边栏会多一个 Claude 图标能打开聊天面板直接在编辑器里对话。支持把当前打开的文件作为上下文。终端里运行claude的会话和 VS Code 扩展的会话可以共享同一个历史记录。直接用快捷键唤起插件 diff 视图AI 改代码后你能逐行确认再接受。配置上有一个小技巧如果你在 VS Code 里同时装了多个 AI 插件比如 Cursor 或 Continue注意别让快捷键冲突。Claude Code 扩展默认占用 CmdShiftC 之类的快捷键装完以后建议检查一下 keybindings避免按出来是别的东西。3. MCP 服务器的连接与配置实操3.1 MCP 是怎么被调用的MCP 的调用链路其实不复杂。Claude Code 作为 MCP host 启动时会读取配置文件里声明的 MCP server 列表然后逐个启动这些 server 进程跟它们建立 JSON-RPC 连接。运行时Claude 根据你的对话内容判断是否需要调用某个 server 提供的工具然后发出请求、拿到结果、再把结果整理成回答输出。这带来一个关键认知MCP server 不是一个远程 API它通常是一个本地进程。比如说你配置了一个 filesystem MCP serverClaude Code 会在本地启动一个 Node 进程这个进程负责读你指定的目录。所以配置 MCP 时command字段和args字段尤其重要——它们决定了这个 server 进程到底是怎么拉起来的。3.2 配置文件长什么样Claude Code 的 MCP 配置分两个层级全局配置存储在~/.claude.json对所有项目生效。项目配置存储在项目根目录的.mcp.json只对当前项目生效而且可以提交到 Git 仓库让团队所有成员共享。推荐做法私人的、跟账号绑定的 server 放全局配置团队公共的 server 放项目配置。因为项目配置会共享给同事如果你把个人数据库地址写进去那基本等于裸奔。实际配置格式如下{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/me/Documents/projects ] } } }这个例子里filesystem是 server 名称command是启动命令args是命令参数。配置完成后在 Claude Code 里运行claude mcp list能看到所有已连接的 server。claude mcp add是命令行方式添加 server 的快捷入口格式如下claude mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem /Users/me/Documents/projects注意--后面的内容会原样作为启动参数有些环境会忽略这个分隔符导致配置失败这类问题我在后面问题排查部分会提解决方案。3.3 三个高频场景的 MCP 配置场景一Figma MCPFigma 有官方的 MCP server作用是让 Claude Code 读设计稿的图层结构、组件和样式数据。配置方式是通过FIGMA_API_KEY环境变量或--figma-api-key参数传入。claude mcp add figma -- npx -y figma-developer-mcp --figma-api-key你的key --stdio用的时候直接说“读取这个设计稿的页面结构文件链接节点ID”它就会拉取数据。我的经验是Figma MCP 适合拿样式、文本、布局层级这类结构化数据但设计稿里的位图资源和复杂特效拿不到别期待过高。场景二Blender MCPBlender MCP 是社区项目让 Claude Code 能控制 Blender 进行三维建模和场景操作。配置方式是启动一个 MCP server然后command指向你的 Python 环境claude mcp add blender -- python /path/to/blender-mcp/src/blender_mcp.py同时要在 Blender 内部启用插件。这个玩法非常酷但要注意Claude Code 能发指令Blender 能否准确执行取决于你说话是否够精确。说“做个茶壶”它是做不到的但说“把当前场景里的物体旋转 45 度”就没问题。所以凡是操作类 MCP指令描述越具体越好。场景三Chrome MCP Server浏览器自动化Chrome MCP server 通常基于 Playwright 或 Puppeteer让 Claude 能打开网页、点击按钮、填表单、截图。典型配置{ mcpServers: { chrome: { command: npx, args: [-y, modelcontextprotocol/server-playwright] } } }装好以后你可以让 Claude Code 自动打开某个页面、把内容截图保存、甚至模拟用户操作。我自己用得最多的场景是“自动去平台上拉取某个数据的页面然后把关键信息提取回来”。需要注意浏览器自动化的稳定性问题——页面元素变一下选择器就失效这是常态所以适合一次性的数据抓取不适合长期维护的流程。3.4 配置参数的选型原则配置 MCP server 时你会经常看到两类 server一类基于 stdio一类基于 SSE/HTTP。stdio serverClaude Code 启动本地进程通过标准输入输出通信。配置简单延迟低推荐优先选择。SSE 或 HTTP server远程服务通过 URL 连接。适合团队共享的中央服务比如已经在服务器上部署好的数据库查询服务但因为涉及网络认证配置会复杂一些。我的原则是本机能跑、单一用户用就选 stdio多人在线共享、需要统一版本管理再考虑走远程 MCP。4. 进阶玩法Skill、Agent、MCP 的边界与协作4.1 Agent、Skill、MCP 到底有什么区别这是热搜里出现非常多的问题。我一句话总结Agent 是执行任务的“主体”Skill 是注入给 Agent 的技能包/知识包MCP 是 Agent 可以调用的外部工具接口。三者不是竞争关系而是不同层次的能力。AgentClaude Code 本身就是 agent它负责理解你的意图、规划步骤、调用工具、检查结果。Skill一套预设的指令和示例相当于给 agent 的一份“操作手册”。你把 skills 放在~/.claude/skills目录Claude Code 会在恰当的时机读取它。MCPAgent 的外部工具通过标准协议提供能力。你可以理解为 Skill 是“怎么思考”MCP 是“怎么执行”。举个例子我想让 Claude Code 写一个符合公司规范的 Java 接口我可以先做一个 Skill里面包含公司的代码规范、模板、自查清单然后配一个 MCP server它能直接从接口文档平台拉取需求详情。Agent 拿到 Skill 的规范和 MCP 的数据才能产出正确结果。没有 Skill它只能按通用经验来没有 MCP它拿不到外部数据。4.2 如何安装和使用 SkillSkill 的安装方式比较直接在~/.claude/skills目录下手动创建目录结构即可。每个 Skill 包含一个SKILL.md文件里面写上这个 Skill 的名称、描述、使用场景和步骤你也可以附带一些参考文件。举个例子我写一个“代码审查” Skill~/.claude/skills/code-review/ SKILL.md checklist.mdSKILL.md内容大概是--- name: code-review description: 对指定代码变更执行审查输出安全问题和性能风险清单。当用户要求“审查代码”或“review”时使用。 --- 1. 读取用户指定的文件或 diff 内容。 2. 检查以下重点SQL 注入、敏感信息硬编码、异常吞掉、性能热点。 3. 输出按严重程度排序的风险列表并给出修改建议。装好之后你在对话里说“帮我 review 一下 src/main/java 下的改动”Claude Code 就会自动去调用这个 Skill。效果上相当于你给模型内置了一套领域方法论。4.3 把 REST 接口发布成 MCP server很多搜索词都涉及到“Java 将 REST 接口发布为 MCP”说明这个需求很普遍。原因很简单企业内部服务大多是 REST API如果能让 Claude Code 直接查这些接口等于把 AI 接入了企业数据中台。这里介绍一个最通用的做法用 TypeScript 或 Python 的 MCP SDK 写一层薄封装把你需要的 REST 接口代理成 MCP 工具。以 Python 为例from mcp.server import Server from mcp.types import Tool, TextContent import requests app Server(rest-bridge) app.list_tools() async def list_tools(): return [ Tool( namequery_order, description根据订单号查询订单详情, inputSchema{ type: object, properties: {order_no: {type: string}}, required: [order_no] } ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name query_order: resp requests.post( http://your-service/api/order/query, json{order_no: arguments[order_no]}, timeout10 ) return [TextContent(typetext, textresp.text)] if __name__ __main__: app.run()配置到 Claude Code 里{ mcpServers: { rest-bridge: { command: python, args: [/path/to/rest_bridge.py] } } }这样 Claude Code 就多了一个query_order工具。你只需要说“给我查一下订单 A12345 的状态”它就会自动请求 REST 接口并解析结果。做这类封装时我强烈建议你做三件事设置超时时间、做参数校验、限制返回大小。否则一旦上游接口慢MCP 调用会卡住 agent 的整个任务链。5. 常见问题与排查技巧实录5.1 登录卡在账号界面和会话历史找回不少人在微博和社区里反馈“Claude Code 桌面端卡在登录账号界面”我自己也遇到过。绝大多数情况是本地缓存的认证信息损坏。解决办法先完全退出 Claude Code 和 VS Code 扩展。删除本地的认证缓存目录macOS/Linux 在~/.claude/Windows 在当前用户目录下的.claude文件夹。注意这个目录里也包含了大量配置和会话历史最好先备份再删。重新运行claude重新走授权流程。关于对话历史Claude Code 每个会话默认都在本地有记录。想恢复上次会话用claude --continue或者查看历史会话列表claude --resume这个命令会列出历史会话的摘要你可以按键选择要恢复的会话。这个功能在我写长文或处理跨天任务时特别实用。另外Claude Code 还支持把会话输出到文件比如claude -p 总结这个项目 output.md-p是非交互模式适合脚本化调用也是做自动化的基础。5.2 MCP server 连接失败的原因排查MCP server 连不上最常见的几个原因按概率排序第一启动命令出错。检查claude mcp list里是否显示 server 异常然后直接用命令行启动一遍命令看有没有报错。比如npx版本太旧、Python 包路径不对都会直接暴露出来。第二stdio server 的输出污染。有些 MCP server 会在启动时往 stdout 里打印日志这会导致 JSON-RPC 握手失败。解决方法是把所有日志改为输出到 stderr 或日志文件stdout 只能用于协议通信。第三环境变量缺失。特别是需要 API Key 的 server比如 Figma MCP如果环境变量没设对server 能启动但请求会鉴权失败。我自己的配置习惯是每接一个 MCP server先开一个小项目单独测确认通了再放到正式环境。别一股脑配五六个出了问题你根本不知道是哪一环断的。5.3 关于额度限制提示一些用户会在使用过程中看到类似“your limits are temporarily boosted. your weekly Claude Code limit is 50% higher”的提示。这是订阅账号的常规额度说明意思是你的周限额被临时提高了 50%不是限制你的意思是放宽。真正需要注意的额度不足提示通常会是明确告诉你 quota 超了。这种情况下建议拆分大任务减少单次对话消耗的上下文量。用claude --model切换模型。Claude Code 支持指定使用哪个模型比如快速迭代时用响应更快的模型复杂任务再用高级模型能明显减少 token 消耗。及时清空不需要的长上下文开启新的会话。长对话会持续累积上下文每个请求都按全部上下文计算 token这是额度消耗的大头。5.4 常见问题速查表问题现象最常见原因解决方案安装后运行 claude 无反应Node 版本过低或全局 bin 路径未配置升级 Node 到 18检查 npm 全局 bin 目录登录界面卡住本地认证缓存损坏备份后删除 ~/.claude 目录重新登录MCP server 显示 not connected启动命令或参数有误手动跑一遍 server 命令确认无报错MCP 调不到工具server 进程正常但工具名识别不了用 claude mcp list 查看工具列表确认名称对话太长响应变慢上下文累积过大新开会话或用 --continue 拆任务额度消耗异常快大量长上下文的重复对话切换更经济的模型拆短任务6. 个人建议从入门到精通的进阶路径最后分享一点我自己的经验。如果你刚开始接触 Claude Code不要一上来就配一堆 MCP server 和装一堆 Skill。先用两周时间把它当作日常开发里查代码、写测试、跑命令的搭档熟悉它的交互方式和边界。等你能顺畅描述需求、能让它按你的节奏工作了再逐步引入 MCP 和 Skills。配置 MCP 时我的选择顺序是官方 server 优先于社区 server本地 stdio 优先于远程 HTTP有文档的优先于没文档的。社区 server 更新频繁版本兼容很随意我踩过最深的坑就是某个社区 MCP 昨天还能用今天 Claude Code 升级后协议版本不兼容整个工具链直接断掉。所以对关键路径上的 MCP server我会固定在特定版本上不随便升级。另一个很实用的小技巧是写复杂需求前先在对话里跟 Claude Code 对一遍计划。比如让它先输出“我要做哪几步、每步调用什么工具、遇到什么情况停下来问我”确认无误了再开始执行。这样能避免它拿着一个错误方向一路狂奔白白消耗你的额度。Claude Code 这个工具迭代很快MCP 生态也在快速增长。今天教程里的配置方式几个月后可能就有更好的替代方案。但底层的协议理解、配置思路和排查方法不会过时这才是这篇教程最想让你掌握的东西。