第一次在终端里敲下claude这个命令的时候说实话我没抱太大期待。当时市面上号称AI 编程助手的东西太多了多数是套一层 IDE 插件壳真正问两句就露馅。但 Claude Code 不一样——它直接在终端里跑能读写文件、执行命令、改完代码自己跑测试第一次用就有种这不是聊天框是一个真的在帮你干活的实习生的感觉。不过用了一阵子就撞到天花板它能操作你电脑上的东西却看不见你浏览器里的页面、Figma 里的设计稿、数据库里的表结构。直到我把 MCP 接进去才发现前面的使用方式只发挥了三成功力。这篇教程我就按自己从零折腾到熟练的路线把Claude Code 是什么、MCP 是什么、怎么装、怎么配、怎么接各种服务器、怎么避坑一次讲透。不管你是刚听说 MCP 的小白还是已经装好但不知道怎么深入的老手都应该能从这里找到对应的答案。1. 先搞清楚底层逻辑MCP 是什么Claude Code 又是什么1.1 MCP 不是插件是AI 世界的 USB-C 接口MCP 全称是 Model Context Protocol模型上下文协议。如果你搜过MCP 是什么会看到各种绕来绕去的定义我用自己的话说MCP 是一套让 AI 应用连接外部工具的标准化接口协议由 Anthropic 在 2024 年底开源。拿充电接口类比最好理解。以前每个手机品牌都有自己的充电口你出门要带好几根线后来大家统一成 USB-C一根线走天下。MCP 干的就是这件事在没有 MCP 之前每个 AI 工具要接入一个新服务都得为它专门写一套对接代码A 工具接完 FigmaB 工具想接还得重写一遍。有了 MCP 之后服务方只需要按照统一协议暴露一个MCP Server任何支持 MCP 的 AI 应用都能直接连上一次开发到处复用。所以说MCP 不是某个具体软件也不是某个插件它是一套约定。你平时听到的蓝湖 MCPFigma MCPPlaywright MCP都是基于这套约定写出来的具体服务器程序。1.2 Claude Code 是 MCP 体系里的宿主那 Claude Code 是什么简单说它是 Anthropic 官方推出的终端版 AI 编程代理。注意代理这个词——它不是简单的问答工具而是能直接在你电脑上执行操作的程序。你给它一个任务它会自己规划步骤读写代码文件、执行 shell 命令、运行测试、根据报错修改代码全程像有一个远程同事在替你操作终端。在 MCP 体系里Claude Code 扮演的是Host宿主角色。所谓 Host就是运行 MCP 客户端、并且最终把工具能力呈现给 AI 模型的那个应用。你可以把 Host 理解成插座MCP Server 理解成电器插上哪个电器AI 就多出哪个本领。这里有个很容易混淆的点很多人以为装了 Claude Code 就等于有了 MCP其实不对。Claude Code 本身只是 Host它自带了一些基础能力文件读写、执行命令但那些五花八门的外部能力——看图、操作浏览器、连数据库——全部要靠你主动接入 MCP Server 才能获得。1.3 三角色分工Host、Client、ServerMCP 协议里有三个角色搞清楚了你就不会再被各种教程绕晕角色是什么类比典型例子MCP Host发起连接的 AI 应用插座Claude Code、Claude 桌面版、VS Code 里的 AI 插件MCP ClientHost 内部负责和 Server 通信的组件插头隐藏在 Claude Code 进程里你不用管它MCP Server提供具体能力的独立程序电器Figma MCP、Playwright MCP、文件系统 MCPMCP Server 对外暴露三类能力Tools工具AI 可以主动调用的函数比如读取设计稿图层点击页面按钮Resources资源AI 可以读取的数据比如配置文件、文档内容Prompts提示模板预置好的交互模板。日常使用中你接触最多的是 Tools因为 Claude Code 干活基本都是在调工具。搞清楚这个关系之后你会发现整个人工智能工具链的玩法都变了以前是每个 AI 应用各自为政现在是一个 Host N 个 Server插拔组合自由拼装。2. 安装部署实测Win11、Ubuntu、macOS 三平台记录2.1 前置环境先检查 Node.js 和 npmClaude Code 是基于 Node.js 的命令行工具安装前先把环境准备利索省得后面各种报错。官方要求 Node.js 版本18 以上但根据我实际使用的经验建议直接用 20 LTS 或更新的版本旧版本在加载一些 MCP Server 时会出现兼容问题。检查命令node -v npm -v如果提示找不到命令说明 Node.js 还没装。Windows 用户建议去官网下载 LTS 安装包一路下一步Ubuntu 用户我推荐用 nvm 管理 Node 版本避免直接用 apt 装的版本过旧curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash nvm install 20 nvm use 20macOS 用户如果装了 Homebrew直接brew install node也行。这一步没什么技术含量但值得多说一句尽量别用系统自带的旧版 Node我见过好几个报错案例最后排查下来都是 Node 版本太老。2.2 安装命令与版本验证三平台的安装命令完全一样全局安装npm install -g anthropic-ai/claude-code装完之后验证claude --version能输出版本号就说明装好了。如果提示command not found大概率是 npm 全局 bin 目录没在 PATH 里。Windows 上常见于 PowerShell 执行策略限制可以试试Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserUbuntu 上如果出现 EACCES 权限报错说明 npm 全局目录的权限有问题不建议用 sudo 硬装一劳永逸的办法是把 npm 全局目录改到用户目录下mkdir -p ~/.npm-global npm config set prefix ~/.npm-global # 然后在 ~/.bashrc 里加上 export PATH~/.npm-global/bin:$PATH更新版本也很简单Claude Code 的迭代速度很快基本一两周就有新版本npm update -g anthropic-ai/claude-code2.3 登录认证与第一次对话装好后在终端输入claude首次启动会进入登录流程。Claude Code 需要 Anthropic 账号认证支持订阅用户登录也支持 API Key 方式。如果用 API Key记得先设置环境变量export ANTHROPIC_API_KEY你的keyWindows 用户用setx ANTHROPIC_API_KEY 你的key设置永久环境变量。登录成功后会进入交互界面先别急着干活用几个命令摸摸底/status查看当前登录账号、模型、工作目录/help查看所有斜杠命令/cost查看本次会话的 token 消耗/config打开配置文件编辑器首次对话我建议让它做点简单的事比如列出当前目录的文件并说明每个文件的作用先确认它能正常读写文件。如果这一步都报错多半是目录权限问题后面第 6 节专门讲。3. 配置体系拆解settings.json、权限模型与 VS Code 集成3.1 配置文件放哪、优先级怎么算Claude Code 的配置分散在几个位置搞清楚它们的优先级很重要不然你明明改了一个配置却不生效会怀疑人生。用户级配置~/.claude/settings.json所有项目生效项目级配置项目目录/.claude/settings.json跟着项目走适合团队共享本地覆盖配置项目目录/.claude/settings.local.json一般不提交到版本库放个人偏好环境变量.claude/settings.json里可以读${VAR}形式的环境变量优先级从高到低大致是本地覆盖 项目级 用户级。也就是说同一个配置项出现在多个文件里生效的是优先级高的那个。一个典型的用户级 settings.json 长这样{ model: opus, permissions: { allow: [ Bash(npm run *), Read(credentials/*) ], deny: [ Bash(rm -rf *) ] }, env: { ANTHROPIC_MODEL: claude-sonnet-4-5 } }注意model字段控制模型偏好env里的ANTHROPIC_MODEL也可以指定模型两者同时出现时以 env 为准。我通常把model设置成sonnet平衡速度和效果大任务再临时切换到opus。3.2 权限控制allow / ask / deny 三档Claude Code 能直接操作你的终端所以权限控制是配置里的重头戏。它的权限模型分三档allow直接执行不询问ask每次执行前弹确认让你决定放不放行deny直接禁止默认情况下Claude Code 对敏感操作删除文件、安装依赖、执行未知命令会走 ask 流程。用久了你会觉得每次都弹窗很烦这时可以把一些安全的命令加进 allow 列表。比如我经常让它跑项目测试permissions: { allow: [ Bash(npm run test), Bash(npm run lint) ], ask: [ Bash(git push *) ], deny: [ Bash(rm -rf /), Bash(.*sudo.*) ] }还有个--dangerously-skip-permissions参数加上之后所有操作都不询问直接执行。这玩意儿听着省事实际就是在裸奔非隔离环境千万别用。我见过有人图省事全程跳过权限结果 AI 误删了.git目录欲哭无泪。3.3 在 VS Code 里使用 Claude Code虽然 Claude Code 的战场是终端但很多人更习惯在编辑器里用。官方提供了 VS Code 扩展装好之后有几种用法集成终端在 VS Code 内置终端里直接跑claude工作在项目目录下这其实是我最常用的方式。命令面板CtrlShiftP搜 Claude Code可以快速启动对话。侧边栏视图新版扩展有独立的侧边栏界面能把对话和代码编辑并排显示。在 VS Code 里用有个天然好处Claude Code 修改文件后你能在编辑器的变更提示里直观看到改了什么随时回滚。我习惯在 VS Code 里用它改代码在纯终端里用它做运维操作分工明确。4. MCP Server 接入实战设计稿、浏览器自动化、3D 场景一次讲透4.1 添加 MCP Server 的三种方式这是全篇最核心的部分。接 MCP Server 有三种方式对应不同场景方式一命令行直接添加claude mcp add playwright -- npx playwright/mcplatest claude mcp add figma -e FIGMA_API_KEY你的token -- npx -y figma-dev/mcp-serverclaude mcp add后面跟的是给这个服务器起的名字--之后是启动命令。加环境变量用-e KEYvalue。查看和管理claude mcp list claude mcp remove playwright方式二项目配置文件 .mcp.json在项目根目录创建.mcp.json内容格式如下{ mcpServers: { playwright: { command: npx, args: [playwright/mcplatest] }, figma: { command: npx, args: [-y, figma-dev/mcp-server], env: { FIGMA_API_KEY: 你的token } } } }这个文件会跟着项目走团队成员 clone 下来就能用强烈推荐。注意.mcp.json和.claude/settings.json是两回事前者只存放 MCP 服务器的定义后者是 Claude Code 自身的配置。方式三连接远程 MCP Serverclaude mcp connect --transport http https://example.com/mcp适合连接已经部署在服务器上的 MCP 服务走 streamable HTTP 或 SSE 协议。这个是进阶玩法本地开发用得少。4.2 Figma MCP设计稿直接进上下文Figma MCP 是社区里呼声最高的服务器之一它解决的核心痛点是AI 终于能看见设计了。接入步骤在 Figma 个人设置里生成 Personal Access Token从设计稿 URL 里提取 File KeyURL 里file/后面那串字符按 4.1 的方式添加服务器设置FIGMA_API_KEY环境变量对话时直接把 Figma 文件链接丢给 Claude Code之后你可以问它这个设计稿用的什么色值首页的间距体系是什么甚至让它根据设计稿直接生成前端代码。很多人关心的Figma MCP 可以直接切图吗答案是能拿到图层信息和导出资源但生产级的切图还是要在 Figma 里配合规范来做MCP 更适合让 AI 理解设计意图、快速生成结构代码。实测下来让 Claude Code 读一张复杂设计稿然后写 Tailwind 页面还原度能有七八成剩下的细节需要人工校对样式变量。这一步对前端效率的提升是质变级的——以前从设计到代码要经历看图-理解-手写三个阶段现在 AI 可以直接跳过看图环节。4.3 蓝湖 MCP国内设计协同场景的补充蓝湖是国内团队常用的设计协作平台它家也出了 MCP Server原理和 Figma MCP 类似让 AI 直接读取蓝湖上的设计稿、标注信息、切图资源。对国内团队来说设计资产放在蓝湖而不是 Figma 的非常多这个 MCP 的价值就在于此。接入方式同样是拿到蓝湖的访问凭证配置好服务器后让 Claude Code 去读某个设计稿页面的标注和样式数据。实际协作场景里我一般用它来做设计稿信息问答和标注数据提取比如让 AI 确认某个按钮的圆角、边框、字号避免反复切图软件人工核对。4.4 Playwright MCP让 AI 自己操作浏览器Playwright MCP 是微软出的官方服务器它把 Playwright 的浏览器自动化能力暴露给 AI。接上之后Claude Code 可以自己打开浏览器访问页面点击、输入、滚动模拟真实用户操作截图然后看截图判断页面渲染是否正确抓取控制台报错、网络请求信息这对前端开发的调试效率提升是惊人的。以前排查为什么这个页面白屏要自己开 DevTools 慢慢看现在直接让 Claude Code 打开页面、截图、检查控制台很多问题它自己就能定位并修复。有一个技巧让 Claude Code 跑 Playwright 的时候明确告诉它每一步操作后都截图这样你能通过截图看到它的操作过程发现问题时也方便回溯。我踩过的坑是有些网站有反爬机制Playwright 默认的浏览器指纹容易被识别这种时候需要设置--browser chromium并考虑使用持久化上下文。4.5 值得关注的生态案例Blender、Burp、IDA、VivadoMCP 生态的想象力远比接几个官方服务器大。我在实际使用和调研中整理了几个方向Blender MCP连接 Blender让 AI 通过自然语言控制 3D 建模场景——创建物体、调整材质、设置动画关键帧。对 3D 内容生产流程是个潜在的游戏规则改变者。Burp MCP / IDA MCP安全测试和逆向工程领域让 AI 直接操作 Burp Suite 的代理数据、IDA 的反编译结果。做安全测试的人已经在探索让 AI 辅助分析流量和二进制代码。Vivado MCPFPGA 开发领域有人把 Xilinx Vivado 的工具链封装成 MCPAI 辅助写约束文件、分析综合报告。Spring Boot MCPJava 生态的集成Spring AI 官方支持 MCPJava 服务可以暴露 MCP Server 给 AI 调用。DevSpace MCPKubernetes 开发环境管理AI 直接操作集群资源。这些案例说明一件事MCP 的价值不在于某一个服务器有多强而在于它是统一接口。任何工具只要有人封装成 MCP Server就能立刻接入所有 MCP Host。作为使用者你不需要知道每个工具的底层 API只需要会接 MCP。5. 进阶玩法Skills 技能、自定义 MCP Server 与模型联动5.1 Skills 和 MCP 的区别以及技能的安装用熟 MCP 之后你还会碰到一个概念Skills技能。很多人把它和 MCP 混为一谈其实两者解决的问题完全不同。MCP 给 AI 的是手能调用外部工具做事情Skills 给 AI 的是脑内知识库教它特定任务怎么做、遵循什么规范一个 Skills 就是项目里的一个目录里面有一个SKILL.md文件用 Markdown 写清楚这个技能的使用场景、步骤、注意事项。Claude Code 在干活时会自动加载相关技能按里面的指引来执行。安装方式很简单创建.claude/skills/技能名/SKILL.md然后把内容写进去。比如我团队写了一个如何规范提交代码的技能# 代码提交规范 ## 适用场景 当需要执行 git commit 时使用。 ## 步骤 1. 先运行 git diff 查看变更内容 2. 根据变更类型选择前缀feat/fix/refactor/docs 3. 提交信息格式type(scope): description也可以从 GitHub 上找别人写好的 skills 仓库直接 clone 到.claude/skills目录。Skills 是纯文本、零依赖、跟着仓库走非常适合团队沉淀最佳实践。5.2 用 TypeScript 写一个本地 MCP Server如果现成的 MCP Server 满足不了需求你可以自己写。MCP 官方提供了 SDK支持 TypeScript 和 Python。我用 TypeScript 写一个最简版本地服务器让你感受一下import { McpServer } from modelcontextprotocol/sdk/server/mcp.js; import { StdioServerTransport } from modelcontextprotocol/sdk/server/stdio.js; import { z } from zod; const server new McpServer({ name: demo-server, version: 1.0.0, }); server.tool( add, 计算两个数字之和, { a: z.number(), b: z.number() }, async ({ a, b }) ({ content: [{ type: text, text: String(a b) }], }) ); const transport new StdioServerTransport(); await server.connect(transport);这段代码做的事情就是定义了一个叫add的工具接收两个数字参数返回它们的和。通过 stdio 传输层和父进程即 Claude Code通信。编译成 JS 之后在.mcp.json里用 node 命令启动它{ mcpServers: { demo: { command: node, args: [/path/to/demo-server.js] } } }对你来说技术难点不在写工具逻辑而在理解协议边界——工具的参数要定义得足够清晰AI 才知道怎么调用你。我写过几个内部工具血泪教训是参数描述比实现更重要因为 AI 是拿你的描述来理解工具用途的。5.3 RAG 和 MCP 到底有什么区别这两个概念经常被放在一起问因为都涉及给 AI 更多信息。它们的区别可以一句话概括RAG检索增强生成解决的是模型不知道的知识把文档切块、向量化、存到数据库里用户提问时先检索相关内容拼进提示词再让模型回答。MCP 解决的是模型做不到的事情读文件、调接口、操作浏览器这些需要实际执行的动作。一个是喂知识一个是给手。它们不冲突甚至经常配合使用——你可以用一个 MCP Server 去查询向量数据库把检索到的内容返回给模型。我接触过的很多所谓知识库问答项目本质就是 RAG MCP 的组合。5.4 把 Claude Code 接到 DeepSeek 等模型的思路很多人问 Claude Code 能不能接 DeepSeek、通义这类国产模型因为它们的 API 价格便宜不少。原理上可行但有个坎Claude Code 原生只认 Anthropic 的 Messages API 格式而 DeepSeek 提供的是 OpenAI 兼容接口两者协议格式不同。社区给出的解法是加一层协议转换路由层常见工具如claude-code-router。它把 Claude Code 发来的 Anthropic 格式请求转成 OpenAI 格式转发给 DeepSeek 等模型再把结果转回。配置思路大致是安装路由工具在配置文件里注册模型提供商填 DeepSeek 的 API Key 和接口地址启动 Claude Code 时指定走路由层另一个更直接的字段是ANTHROPIC_BASE_URL它用来指向任何兼容 Anthropic API 格式的服务端。如果你的模型服务商提供了 Anthropic 兼容端点直接用这个环境变量就能切换。需要提醒的是Claude Code 的一些特性比如工具调用、思考过程对不同模型的兼容度不一样接了第三方模型后可能出现工具调用格式对不上、行为不稳定。拿来玩玩可以生产环境我仍然建议用官方模型稳定性优先级最高。6. 高频问题排查权限拒绝、卸载残留、版本兼容全记录6.1 权限拒绝与高危命令审批遇到最多的报错是 Claude Code 执行命令时被权限系统拦下来提示类似 The user denied access to this tool 或者 permission not granted。这不是 bug是权限模型在正常工作。处理思路分两步第一步看这个操作是不是必要的。如果只是偶尔一次直接在弹窗里批准即可如果是高频操作加到settings.json的permissions.allow里。第二步检查是不是写错了权限规则。Claude Code 的权限规则支持通配符和正则形式的命令匹配比如allow: [ Bash(npm run *), Read(.*\\.env$) ]注意规则写得太宽会有安全风险Bash(.*)等于放行所有命令和裸奔没什么区别。我一般只放行自己反复确认过的安全命令前缀。6.2 彻底卸载与残留目录清理卸载 Claude Code 的命令npm uninstall -g anthropic-ai/claude-code但很多人卸载完还会遇到claude命令还能用的情况这是因为用户目录下有残留的可执行文件。检查并清理这些位置~/.claude/保存了配置、历史会话、日志删掉之后所有配置和登录信息都没了~/.config/claude-code/部分版本的用户配置在这里%USERPROFILE%\.claudeWindows 下删之前想清楚如果只是重装保留~/.claude/settings.json可以省去重新配置的麻烦如果是彻底卸载全部删掉。6.3 版本更新带来的兼容性问题Claude Code 版本更新频繁有次我升级后之前能用的一个自定义 MCP Server 突然连不上了报 JSON-RPC 解析错误。排查下来发现是服务器用的 SDK 版本太老和新版 Claude Code 的协议版本不兼容。解法很直接npm update modelcontextprotocol/sdk claude mcp list # 查看各服务器的连接状态遇到 MCP 连接异常先用claude mcp list看状态再用claude mcp inspect 服务器名如果支持看具体报错。多数情况下把 MCP Server 的依赖更新到最新版就能解决。另一个常见问题是 NVM 用户升级 Node 版本后全局安装的 Claude Code 找不到了。因为 NVM 的全局包是按 Node 版本隔离的切了版本之后需要重新安装。这个坑我踩过不止一次后来在 shell 配置里加了自动安装的逻辑切到新版本 Node 时自动跑一遍npm install -g anthropic-ai/claude-code。最后分享一个我长期使用下来的心得别急着把所有 MCP Server 都接上先想清楚你日常工作里最痛的那个环节是什么。前端就优先接 Figma 和 Playwright设计协作就接蓝湖测试就接浏览器自动化。MCP 的真正用法是把你的工作流拆成一个个可被 AI 调用的小能力而不是把一堆服务器堆在一起显得很酷。我现在自己维护的项目里.mcp.json一般只放两到三个服务器但每一个都在生产环境里实打实地提效。另外一个建议是给团队用的话把.mcp.json和.claude/skills都提交到版本库新成员 clone 下来就能获得完整能力这是最省心的团队协作姿势。