Claude Code + MCP 配置实战：从安装到进阶玩法全指南-育师

讲道理，Claude Code 这玩意儿出来有一阵子了，但真正用好它的人真不多。多数人还停留在“命令行里聊天写代码”的阶段，根本没把它当成一个可以无限扩展的开发平台。而让 Claude Code 从一个“能写代码的聊天框”升级成“能操作你整个开发环境的总管”，靠的就是 MCP，也就是 Model Context Protocol。

MCP 这个协议你要是没搞明白，Claude Code 你就只用了两成功力。我今天就把从安装、配置到把 MCP 玩出花的完整路径给你捋一遍，全程实际操作过的经验，踩过的坑也一并说了，保证你读完能直接上手干活。

这篇东西适合谁？刚听说 Claude Code 还没装过的小白，装了但只会聊天的普通用户，以及想用 MCP 接管文件系统、浏览器、设计稿甚至券商数据的老手，都能从这里拿到点东西。

1. 理解 MCP 的本质：为什么说它是 AI 时代的 USB 接口

1.1 先搞清楚 MCP 到底解决了什么问题

在没有 MCP 之前，你想让 AI 助手做一件“额外”的事，比如读一下你本地的某个文件、查一下线上服务的最新文档、帮你把网页自动截图，那基本得靠开发者给 AI 写死接口，或者用各种 hack 的方式往 Prompt 里塞数据。每一次新需求，就要重新接一次，又慢又脆。

MCP 干的事，就是把“AI 和外部世界对话”这件事标准化了。它规定了 AI（也就是 Host）该怎么去发现外部工具，怎么调用这些工具，以及工具的结果该以什么格式还给 AI。现在 Claude Code 就是一个 MCP Host，你给它接上什么 Server，它就多会什么“武功”。这个思路本质上跟 USB 接口是同一个道理——你电脑上 USB 口不用管插的是键盘、U盘还是读卡器，协议统一了，插上就能用。

1.2 MCP 的三个角色一句话版本

MCP Host：就是 Claude Code 这类的 AI 客户端，负责和你交互，以及主动发起调用。
MCP Server：一个提供具体能力的独立程序，比如“我可以读文件”“我可以发 HTTP 请求”。
MCP Client：Host 内部内置的协议连接器，负责 Host 和 Server 之间的握手和通信。

你只需要关心 Host 和 Server。Claude Code 负责把所有的 Server 拉起来、管好它们的生命周期，出了问题它自己会重启，你要做的只是声明“我要用哪些 Server”。

1.3 MCP 和普通的 API/插件/RAG 区别在哪

很多人会问：这跟以前用 API 接口接入有什么区别？区别在“动态发现”这件事。API 接口是死的，你得在代码里写死调用的 URL、参数、鉴权；MCP 是活的，Server 会把“自己有哪些工具、每个工具要什么参数”主动告诉 Host，Host 再根据当前对话上下文判断该调哪个。Claude Code 里/mcp敲一下，所有已连接的工具列表、状态、healthy or not，一目了然。

顺便说一句，老有人把 MCP 和 RAG 放在一起比较，这其实是两个维度。RAG 是“把资料检索出来塞进 Prompt 让 AI 有依据地回答”，本质是知识增强；MCP 是“给 AI 一双能对外界动手干活的手”，本质是能力扩展。可以结合着用，但替代不了彼此。

2. Claude Code 的安装与基础准备

2.1 安装前的环境检查

Claude Code 本质上是一个 Node.js 的命令行程序，所以你的电脑上得先有 Node.js。这里有个重点：版本不能太低，Node 18 以下基本没戏。我建议直接上 Node 20 LTS，实测最稳，12 以下的绝对跑不起来，别在版本上较劲。

检查方式自己心里有数就行：

node -v npm -v

没装的先去 nodejs.org 下载 LTS 版本装好，Windows 和 macOS 都是傻瓜式安装，这里不啰嗦。

2.2 安装和卸载：比想象中简单，也比想象中容易犯迷糊

安装命令非常简单，全局安装就行：

npm install -g @anthropic-ai/claude-code

装完验证一下：

claude --version

看到版本号说明装好了，接下来终端里直接敲claude就进入交互式界面了。第一次进去会提示你登录授权，跟着流程走，需要你有 Claude 的账号或者是 API Key 权限。

然后要重点说说卸载。这玩意儿卸载有个坑：你光 npm uninstall 是不够的，它会在你用户目录下写配置文件（尤其~/.claude.json和~/.claude/这个目录）。如果你打算重装排查问题，一定要一条龙清干净：

npm uninstall -g @anthropic-ai/claude-code rm -rf ~/.claude rm -f ~/.claude.json

Windows 用户对应的就是删除用户目录下的.claude文件夹。很多人重装完发现“怎么还是旧配置”，不用怀疑，就是这个文件在作怪。

2.3 相关经验和特别提醒

验证安装是否成功之后，建议先跑起来确认一下能不能正常联网，因为 MCP Servers 绝大多数需要从 npm registry 拉取。如果你在一个网络策略比较严格的环境里，连 Server 安装都会有奇奇怪怪的报错。到时候优先看是网络问题的原因，别一上来就怀疑自己装错了，这是最常见的误判。

另外，现在 Claude Code 本身其实有桌面版和 VSCode 插件版，但核心还是这个 CLI。VSCode 里配置 Claude Code 本质上就是调起 CLI 或者让它作为开发后端，快捷键面板里能直接呼出对话窗口。VSCode 用户装插件之后，终端里跑的命令和在系统终端里跑的命令是同一套逻辑，没有秘笈可言，会用 CLI 就什么都会。

3. MCP 配置实操：从零到一成功接上第一个 Server

3.1 配置文件在哪，用什么格式

这是新手最容易劝退的环节。MCP 的配置整体分为两种 scope：

local（本项目的）：配置存到项目根目录的.mcp.json，只对当前项目生效。
user（用户级全局的）：配置存到~/.claude.json的mcpServers字段里，任何项目都能用。

我个人的建议是：能用 project 级别就用 project 级别，因为你换台机器拉下代码，.mcp.json 还在，直接把别人需要的 MCP 能力带过去了，非常方便团队协作。全局级别的配置适合那种“不管哪个项目我都要有”的通用能力，比如读文件、写文件这类的。

3.2 通过命令行添加 Server：最不容易出错的方式

手动改 JSON 容易手抖，官方其实提供了命令行的方式，强烈推荐用这个方式去加：

# 给当前项目加一个 filesystem server claude mcp add filesystem -e D:/data npx -y @modelcontextprotocol/server-filesystem D:/data # 查看当前所有 MCP Server 以及它们的启停状态 claude mcp list # 测试连通性 claude mcp test

加完成后，在 Claude Code 对话里输入/mcp就能看到已加载的 Server 列表和提供的工具。注意，加完之后当前会话里可能不会立即生效，有时候需要重启一下会话，这是个很多人被卡住的小坑。

3.3 手写 JSON 也不难：懂原理才能出问题自己排

命令行工具帮你做了配置的生成，但拿不到或者要改细节时，还是要懂 JSON 长什么样。给一个全局配置的片段：

{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/你的用户名/Documents"], "env": {} }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_你的token" } } } }

字段不复杂，command是要跑的命令，args是命令参数，env是环境变量，就这么直白。你只需要记住：这些 Server 本质上是一个个子进程，Host 负责和它们保持通信。如果某个 Server 起来就崩了，问题大概率出在路径、环境变量或网络这三件事上。

3.4 权限管理：别上来就无脑跳过

Claude Code 对 MCP 工具有一套自己的权限管控逻辑。新加的 Server 默认会处于需要你确认的状态，当模型要调用某个工具时它会征求你同意，也就是 permission 提示。你可以针对具体的工具允许或拒绝，也可以让某个 Server 的所有工具都自动放行。

要特别提一下--dangerously-skip-permissions这个参数，很多教程会为了省事让你加上，但我真心不建议你一上来就这么干。你真不知道哪次对话模型会脑抽调一堆你不想要的工具。正确做法是：把常用的、低风险的 Server（比如文件操作限定目录的）设置为 allowed，把高风险的（比如能发网络请求的、能读环境变量的）保持确认状态。实际拿捏，宁严勿松。

4. 核心 MCP Server 实战：掌握这几个就掌握了八成场景

4.1 filesystem 文件系统操作：最刚需的一个

这个 Server 是最应该先装的。装上之后，你可以让 Claude Code 直接读某个目录下的文件列表、读文件内容、写文件、编辑文件。配合上自己设定的目录白名单，它就成了一个“懂你项目的文件管家”。

添加方式：

claude mcp add filesystem -e 项目根目录 npx -y @modelcontextprotocol/server-filesystem 项目根目录

注意，这里路径最好用绝对路径，后面加可以加多个目录，它会分别暴露给模型。用相对路径会偶发目录解析失败问题，属于能跑但治不好的小毛病，干脆避开。

使用时的体会是，当它需要读取文件信息时，不会一股脑把整个目录的文件全塞进上下文，而是按需获取。你问它“帮我改一下 src/utils/index.ts 里那个格式化函数”，它会先去把文件内容读出来，再局部修改，效率很高，不是那种“假装懂你代码”的废物。

4.2 context7 最新文档检索：搞技术的必需品

AI 模型的知识截止日期是个硬伤，训练完模型之后发布的新开发库、新版本 API，它很容易瞎编。Context7 这个 Server 干的事情就是实时去拉取官方最新文档，然后返回相关片段，让 Claude Code 在写代码时能查到最新用法，降低幻觉率。

claude mcp add context7 -e npx -y @context7/mcp-server

抢在代码生成前先让它查文档是很好的习惯，尤其你正在处理刚发布半年内的新库时。实测在处理某个 beta 版本 SDK 时，它的准确率提升是极为明显的。

4.3 Playwright 浏览器自动化：前端改 Bug 的效率利器

这个 Server 能让 Claude Code 直接控制一个真实浏览器，打开网页、点击、输入、截图，一气呵成。前端工程师搞样式 bug、做端到端冒烟测试会非常爽。

claude mcp add playwright -e npx -y @playwright/mcp@latest

下面是它的打开方式，我直接描述一下实际配合的过程。你让它“打开本地开发服务器，访问列表页，截图给我看下这个按钮在移动端是不是错位了”，它会真的拉起一个 Chromium 实例去执行，然后把截图拿回来自己对着看再改代码。这种“看得见摸得着”的调试方式，比纯靠猜前端问题要高效不少。

4.4 GitHub / Git 操作：代码管理的辅助手

默认情况下 Claude Code 能执行 git 命令，但要它去操作 GitHub 的 PR、Issue，你就需要 GitHub 的 MCP Server。它用的是 GitHub 的 Personal Access Token，这个 token 在 GitHub 设置里的 Developer settings → Personal access tokens 生成，需要勾选 repo 和 workflow 权限。

配好之后，对话里写“给当前分支提个 PR，标题是 xxx，帮我写好描述”，它就能直接完成。真省了很多去网页上点来点去的功夫。但注意，涉及写操作的工具，先看一遍它的 diff 再提交，别全自动。

4.5 Figma 设计稿直通代码：设计师和开发的共同话题

Figma MCP 一直是个热门话题。它的核心是拿到设计稿的 JSON 结构、图层名、样式信息，然后喂给 Claude Code 来辅助完成 1:1 还原。用法上，前提是要有个 Personal Token，这个 token 在哪拿？在 Figma 的头像菜单 → Settings → Security → Personal access tokens 里创建，一点不神秘。

拿到 token 后按老规矩配置进 env：

claude mcp add figma -e FIGMA_API_TOKEN=你的token npx -y figma-developer-mcp --stdio --figma-api-key=你的token

它最大的作用是干这么几件事：从设计稿里提取颜色、字体、间距变量，生成 Tailwind 配置或者 CSS Variables；分析图层结构，辅助生成 React 组件骨架；检查前端还原稿和设计稿的视觉差异。很多人拿它做“设计稿转代码”，目前真实的可靠性一般，但做“样式 token 提取”和“结构分析”这两件事很稳。

5. 进阶玩法：自建 MCP Server 和行业工具接入

5.1 用 Python 写一个属于自己的 MCP Server

当现成的 Server 满足不了需求时，就该自己动手了。搞一个 MCP Server 没有想象中那么难，官方给了现成的 Python SDK。核心就两步：定义工具函数，然后把它暴露成一个 MCP Server。

比如给 Claude Code 加一个“查询本地 Excel 里某个 sheet 的行数”的工具：

from mcp.server.fastmcp import FastMCP import pandas as pd mcp = FastMCP("excel-helper") @mcp.tool() def get_row_count(file_path: str, sheet_name: str) -> int: """返回 Excel 文件中指定 sheet 的行数""" df = pd.read_excel(file_path, sheet_name=sheet_name) return len(df) if __name__ == "__main__": mcp.run(transport="stdio")

保存为 excel_server.py，然后在 Claude Code 的配置里把它挂上：

claude mcp add excel-helper -e python /你的绝对路径/excel_server.py

你就获得了“让 Claude Code 直接帮你分析 Excel 文件”的能力。原理明白了之后，你可以自己扩展出任何奇奇怪怪的工具——读取内部系统的接口、跑一段定时任务、操作某个内部管理后台，都能变成 MCP 能力给 Claude Code 调用。

5.2 Java 生态怎么接：Spring Boot 也能暴露 MCP

如果你是 Java 程序员，别觉得 MCP 跟自己没关系。官方有 spring-boot-starter-mcp 这个包，你可以在 Spring Boot 里直接定义工具方法，然后自动变成 MCP Server 暴露出去。大概的姿势是：

<dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server</artifactId> </dependency>

然后写一个工具类：

@Component public class OrderTools { @Tool(description = "根据订单号查询订单状态") public String getOrderStatus(String orderId) { return orderService.getStatus(orderId); } }

应用跑起来后，这个服务本身可以作为 MCP Server 接入 Claude Code。这样你内部的订单系统、库存系统都能以标准协议的形式暴露给 AI。对于很多“AI Agent + 企业内部系统”的落地场景，这个玩法是很有实际意义的。

5.3 股票数据、蓝湖切图、API 调试这些垂直工具

社区里已经有很多人把奇奇怪怪的业务工具接进来了：

通达信本地数据 MCP：把通达信导出的本地数据文件通过 MCP 暴露给 AI，用来做行情分析和策略回测的数据预处理，省得每天手动导 CSV。
蓝湖 MCP：类似 Figma 的思路，不过面向的是国内设计协作流程，能拿蓝湖上的标注信息辅助写样式。
APIPost MCP / Apifox MCP：把你 API 文档里的接口定义变成工具的调用说明，Claude Code 可以直接调用你现成的接口做联调测试。
12306 类查询 MCP：把余票、车次信息查回来再让 AI 做归总。

这些东西的配置方法基本一样：找到对应的 npm 包或 Python 包，填好必要的 token 或路径，加进配置里。尝试的时候不用慌，失败了大不了就把这个 Server 从配置里删掉，完全不影响 Claude Code 本身的使用。

6. 常见问题与排查技巧实录

6.1 配置了但 /mcp 里看不到工具

这是被问得最多的一个问题。最常见的原因是加完 Server 之后没有重启会话。MCP 工具列表是在会话启动时加载的，你在会话中途加配置，当前会话不一定会刷新过来。重启一个新会话（退出重新进或者敲/clear）基本能解决 90% 的问题。

如果重启还看不到，看状态和日志：

claude mcp list claude mcp test

list会显示每个 Server 当前是否 healthy，test会逐个测试所有已配置的 Server，能连通会明确告诉你。哪一步挂了按提示改哪一步。

6.2 npx 能找到但 Server 起不来

一个非常典型的报错：spawn npx ENOENT。这不是 npm 的问题，是 MCP 配置里的command用的是npx，而 Claude Code 启动子进程时根本没找到你的 npx 在哪。常见于 Windows 环境或者通过 IDE 启动 Claude Code 时环境变量没对齐。

解决方式：用where npx（Windows）或which npx（macOS/Linux）找到 npx 的完整路径，然后把配置里的command从npx改成完整的路径，例如/usr/local/bin/npx或C:\Program Files\nodejs\npx.cmd。改完再重启就能好，这一招能治绝大多数“起不来”的问题。

6.3 工具能加载但调用时就报错

这个问题更隐蔽。比如 filesystem Server 显示 healthy，但你让它读一个目录里的文件时它一直报权限拒绝。回忆一下：你在配置 Server 时给它指定了根目录，它只能操作根目录范围内的文件。你想让它读D:/work，但配置里只给了D:/work/project-a，那它访问不了外面。

再比如 GitHub Server 已加载但一查 Issue 就 401，十有八九是环境变量里 token 写错了。可以用命令行重新挂载并比对 env：

claude mcp get github claude mcp remove github claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=你的token npx -y @modelcontextprotocol/server-github

这类问题不复杂，耐心看报错信息基本都能定位。

7. 最后再分享几个我自己的使用体会

玩了大半年 Claude Code 和 MCP，最大的体会是：这套配置真正厉害的地方在于你可以自由组合，把 AI 的能力和本地工作流粘起来。我现在的日常流程是：用 filesystem 读项目文件、用 context7 查最新文档、用 playwright 做页面预览、再用自建的内部工具 Server 对接公司的数据接口，写代码、改 bug、跑测试基本就都拢在一起了。

最后提醒两个容易被忽视的坑。第一，MCP Server 挂多了真的会拖慢响应，因为 Claude Code 在每次对话时都需要把已加载的工具列表发给模型做决策，工具越多，模型思考越慢，上下文占用的空间也越多，建议只挂高频使用的 Server。第二，处理敏感仓库或者生产环境时，权限确认什么都别跳过，也别把 token 写死在项目级的 .mcp.json 里然后传到公开仓库，这类事故我见得太多了。

如果你还没试过 MCP，我建议先拿 filesystem 和 context7 练手，是整个链路里最稳、最有感知的两个 Server，等理解了这个模式之后再慢慢往里面加东西。

Claude Code + MCP 配置实战：从安装到进阶玩法全指南