我第一次用 Claude Code 的时候说实话有点失望。它确实能读懂我粘贴过去的代码片段也能跑一些简单的命令但总觉得它像个被绑住手脚的实习生——你说一句它动一下让它去看数据库、翻设计稿、改配置文件它全都干不了。直到我花了半下午把 MCP 接上体验才彻底变了它开始能自己读项目目录、连数据库查表结构、把 GitHub 上的 issue 和 PR 拉进上下文真正变成了一个可以“自己动手”的结对同事。这篇文章不打算写成像官方文档那样的流水账而是围绕我从安装到二次开发这整条链路把 Claude Code 与 MCP 的配合讲透。内容包括MCP 协议到底是什么、Claude Code 怎么装、MCP Server 怎么配、本地文件和数据库怎么接、设计稿工具怎么打通、第三方模型怎么切换、以及最后手写一个自己的 MCP Server。无论你是刚听说 MCP 的新手还是已经在用但在配置上踩过坑的开发者这里都有可以直接抄作业的内容。1. 为什么说 MCP 是 Claude Code 的“第二套手脚”协议本质再理解1.1 Host、Server 与 Client一个 USB-C 接口的类比在讲配置之前我强烈建议你先花五分钟搞懂 MCP 里那几个名词。因为后面所有操作都在围绕这几层关系转搞不清的话报错的时候你连去哪看都不知道。MCP 的全称是 Model Context Protocol模型上下文协议。你可以把它理解成 AI 世界的 USB-C 接口以前每个设备都有自己的充电口现在大家统一成一个标准插上就能用。MCP 解决的是同样的问题——不同的 AI 应用要接入不同的数据源和工具如果每个都单独开发工作量巨大有了 MCPAI 应用只要实现一次协议就能接上所有实现了该协议的“外接设备”。在具体的架构里有三个角色这是最容易绕晕的地方MCP Host运行 AI 应用的主程序比如 Claude Code、Cursor、VS Code 里的 AI 插件。它是发起方负责管理会话、决定什么时候调工具。MCP ClientHost 内部与 Server 建立连接的通道组件。一个 Host 里可以启动多个 Client分别连不同的 Server。MCP Server真正干活的服务进程它暴露一组“工具”比如读文件、查数据库、搜索网页。Server 通过标准协议把工具列表告诉 HostHost 再把这个列表交给模型决策。你可以简单地理解Claude Code 是大脑MCP Server 是手和脚而 MCP Client 是神经线。大脑不直接控制手而是通过神经线发指令让手去执行具体的动作。这套解耦设计最大的好处是你不需要为了让 AI 能读 PDF 而改 Claude Code 的代码只需要加一个 PDF 相关的 MCP Server 就行。1.2 MCP 是怎么被调用的一次工具调用的完整链路很多教程直接让你复制配置命令但没说清楚背后发生了什么。这里我用一次“读取项目配置文件”的请求把整条链路拆开第一步Claude Code 启动时会读取所有已注册的 MCP Server 配置挨个启动这些服务进程并询问它们的工具列表。这些工具包括工具名、描述、参数 SchemaJSON Schema 格式。第二步当你在对话里让 AI“看一下项目的 package.json 里有没有 eslint 配置”时模型会先判断这个任务可以通过某个 MCP 工具来完成。于是它生成一个工具调用请求里面带上了具体的参数比如文件路径。第三步Claude Code 作为 Host 收到这个请求通过对应的 Client 转发给那个 MCP Server。Server 执行完读取操作把文件内容或结果原样返回。第四步Claude Code 把返回结果塞回模型上下文模型基于这些内容继续推理最终生成回答。完整链路就是模型 → 生成工具调用 → Host 转发 → Server 执行 → 结果回传 → 模型继续。这也说明了一个关键点MCP 的“智能”并不在于 Server 本身而在于模型能否在合适的时机选择合适的工具。所以工具描述写得是否清楚直接影响 AI 的使用效果后面写自定义 Server 时我会再强调这一点。1.3 为什么 Claude Code 与 MCP 的组合被反复提及其实 MCP 并不是 Claude Code 的专属功能Cursor、Trae、Codex 等很多工具都已经支持。但 Claude Code 有一个特点让它特别适合和 MCP 搭配它是 Agent 形态而不是 Chat 形态。早期 AI 编程工具是你在输入框里问一句、它答一句而 Claude Code 是一个真正的 Agent——它自己会规划任务、按顺序调用工具、中途根据结果调整策略。MCP 给了它足够多的“工具”它的 agent 能力才真正有了发挥空间。我第一次感受到这种质变是给它接上了一个本地文件系统 MCP。以前我让它“统计一下这个目录下所有 Python 文件的函数数量”它要么让我把文件内容复制进去要么用只读 shell 命令一个一个数。接上文件工具后它直接列出目录、逐个读取文件、自己写个小脚本统计完再汇总。整个过程中我不需要告诉它每一步怎么做它自己就完成了。这种“把活交给它而不是把字喂给它”的体验差异就是 MCP 带来的核心价值。2. 环境搭建三种安装路径与登录鉴权全流程2.1 前置检查Node 版本与 npm 源Claude Code 目前是通过 npm 分发的命令行工具所以第一步是确认本机有 Node.js 环境。建议 Node 版本 18 及以上太低的话 npm 安装和工具运行都可能报兼容性问题。Windows 和 macOS 的检查方式一样node -v npm -v如果没装 Node去官网下载 LTS 版本或者用 nvm 这类版本管理工具安装都行。个人建议用 nvm方便以后切换版本也避免系统全局目录权限问题。还有一个容易踩坑的点是 npm 源。如果你之前为了加速包下载把 registry 换成了国内镜像那装 anthropic-ai/claude-code 时最好先确认镜像源是否同步了最新版本。我遇到过镜像源版本滞后导致安装后启动报错的情况解决办法是临时切回官方源再装npm install -g anthropic-ai/claude-code --registryhttps://registry.npmjs.org装完之后验证一下claude --version如果输出版本号说明安装成功。2.2 全局安装、卸载与重装全局安装是最常规的路径好处是命令行里直接能敲claude命令npm install -g anthropic-ai/claude-code这个包默认安装在全局 node_modules 下命令链接到 PATH 里。不同系统的全局目录路径不一样macOS/Linux 一般在/usr/local/lib/node_modulesWindows 则取决于你的 Node 安装路径。卸载也很简单npm uninstall -g anthropic-ai/claude-code如果你发现版本行为异常想重装我的建议是先卸载再手动清理两个目录~/.claude用户级配置、历史记录、skills 等~/.claude.json用户级 MCP 配置等Windows 上路径类似在用户主目录下然后重新全局安装。注意清理~/.claude会同时清掉登录凭证和对话历史重装前想清楚。如果只是想降版本npm install -g anthropic-ai/claude-code版本号更安全。2.3 登录鉴权与第三方模型接入前的预备知识装完后直接运行claude会进入首次启动引导。你需要先登录这一步本质上是让 Claude Code 拿到调用模型 API 的凭证。Claude Code 支持的鉴权方式主要有两种Claude 账号订阅登录在启动引导中会打开浏览器完成 OAuth 登录。适合有 Claude 订阅账号的用户。API Key如果你使用 Anthropic API可以设置ANTHROPIC_API_KEY环境变量。适合按量计费的用户。如果你用的是第三方模型比如 DeepSeek那情况又不同需要的是 Anthropic 兼容 API 的接口地址和 Token通过环境变量注入。这部分我在第 5 章专门展开讲。这里有个小建议如果后面要用 MCP Server 里的某些需要 API Key 的工具比如 GitHub、Figma不要偷懒直接写死在配置里优先放到环境变量或使用env字段注入。原因后面排错章节会讲配置文件一旦提交进 Git 仓库密钥就泄露了。2.4 在 VSCode 里使用 Claude Code很多人习惯在 VSCode 里写代码Claude Code 也提供了官方扩展。安装方式很简单VSCode 扩展市场搜索 “Claude Code”安装官方发布的那个即可。安装后你可以通过侧边栏面板打开 Claude Code 的对话界面也可以在 VSCode 的终端里直接运行claude。我自己更喜欢后者因为终端里能更好地观察 Claude Code 执行命令的过程也更贴近 CLI 的完整能力。在 VSCode 中使用时有个细节终端会话默认继承当前工作目录但如果你通过面板打开它可能会基于当前打开的文件夹运行。确保你运行 Claude Code 的目录就是项目根目录否则后续 MCP 的项目级配置.mcp.json会读不到。3. 接入常用 MCP Server本地文件、GitHub、Figma 与蓝湖3.1 用 claude mcp add 注册第一个 MCP Server命令行的核心操作其实就是claude mcp这个命令族。先看几个最常用的# 查看当前所有 MCP Server 及其状态 claude mcp list # 添加一个 MCP Server用户级 claude mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem ~/projects # 删除 claude mcp remove filesystem # 查看某个 MCP Server 的详细配置 claude mcp get filesystem注意--后面跟的是真正的启动命令。也就是说MCP Server 本质上就是一个可执行进程Claude Code 负责启动它并通过标准输入输出通信。npx -y modelcontextprotocol/server-filesystem这条命令的意思是用 npx 直接拉取并运行官方文件系统 Server 包后面的~/projects是传给它的参数限定它只能访问这个目录。我建议你第一次就试这个文件系统 Server因为它最直观也最能体 MCP 的价值。跑完claude mcp add之后重启 Claude Code 让它重新加载配置然后你可以直接问它“帮我看看 ~/projects 下面有哪些 Python 项目”。如果它能报出目录列表说明链路全部打通了。3.2 用 .mcp.json 管理项目级 MCPclaude mcp add默认是把配置写到用户级但一个项目可能需要专属的工具配置。这时候用项目级配置文件更合适。在项目根目录创建.mcp.json内容格式如下{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./data], env: {} }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: 你的_GITHUB_PAT } } } }这个文件的优点是可以提交到 Git团队成员共享同一套 MCP 配置。但正因为大家共享所以里面的密钥绝不能写真实值建议用${GITHUB_TOKEN}这种占位符然后在自己的环境变量里配置或使用~/.claude/settings.json里对每个项目进行环境变量的映射。项目的本地个性化配置放在.mcp.local.json这个文件默认不进版本库适合存放个人专用的敏感配置。3.3 GitHub MCP把 issues 和 PR 拉进上下文做开源项目或者团队协作时Claude Code 需要访问 GitHub 上的 issue、PR 和代码仓库信息。虽然它本身可以通过gh命令行工具实现部分功能但通过 MCP 接入后模型获得的是更完整的结构化工具集比如搜索 issue、读取 PR 评论、创建 issue、列出分支等。GitHub 的官方 MCP Server 是modelcontextprotocol/server-github。它需要 GitHub Personal Access Token创建位置在 GitHub 的 Settings → Developer settings → Personal access tokens注意勾选repo、workflow、read:org等权限。一个比较顺手的用法是你在 Claude Code 里说“这个仓库最近的 issue 都在讨论什么问题帮我总结一下”它会通过 GitHub MCP 拉取 issue 列表和关键正文然后汇总。如果只靠传统 prompt 粘贴这个流程会很繁琐。3.4 设计稿直接进代码Figma / 蓝湖 MCP 与 token 获取AI 编程工具和设计稿之间的打通是中文社区最近一直在讨论的话题。很多人搜索“figma mcp token在哪获取”“蓝湖mcp使用”就是想知道怎么让 Claude 直接读取设计稿的标注从而生成还原度更高的代码。Figma 官方提供了 Dev Mode MCP Server包名是figma/dev-mode-mcp。它的核心工具是读取当前选中设计元素的开发资源包括样式属性、切图信息、代码片段等。Figma 的 Personal Access Token 获取路径是打开 Figma 网页 → 点击头像 → Settings → Security → Personal access tokens → Generate new token。生成后复制保存这个 token 只在创建时显示一次。注册命令示例claude mcp add figma-dev -s project -- npx -y figma/dev-mode-mcp --token你的FIGMA_TOKEN蓝湖的 MCP 接入逻辑类似通常是在蓝湖开放平台申请 API Key然后把这个 key 作为 MCP Server 的环境变量传给 Claude Code。因为蓝湖的开放接口服务商不同时期更新较快我建议以蓝湖官方文档为准思路和 Figma 是相通的注册 Server → 配置 Token → 在对话中让 Claude 读取设计稿资源。这里有一个经验设计稿 MCP 返回的原始信息往往非常冗长模型一次能塞进去的上下文有限。我的做法是先用“这个设计稿的页面主色调是什么”“按钮圆角是多少”这类小问题让模型只提取关键值然后再让它基于这些值生成 CSS而不是一上来就让它“根据设计稿写整个页面”。控制信息粒度是使用设计稿类 MCP 的关键技巧。4. 本地数据与数据库让 AI 直接读表结构和文件4.1 Postgres MCP 快速接入与授权策略开发中最常见的需求是让 AI 理解数据库的表结构。以前的做法是把建表语句粘贴给模型但表一多就没法操作了。通过 MCP 接入 Postgres 后Claude Code 能自己执行查询、读取 schema基于真实数据去分析问题。官方 Postgres MCP Server 的注册方式claude mcp add postgres -- npx -y modelcontextprotocol/server-postgres postgresql://用户名:密码localhost:5432/数据库名建议连接本地开发库而不是生产库。我当时贪图方便直接连了线上预发环境的只读账号后来发现执行效率很低因为模型发起查询时没法限制复杂度一条全表扫描就可能打满数据库。最好在数据库层面单独建一个专门给 AI 用的账号权限只放大到需要的数据库、只读模式并且设置 statement timeout。这是给 AI 开数据库权限时最重要的一条安全底线。MCP Server 暴露给模型的工具包括 execute_query、list_tables、describe_table 等。你会看到 Claude 先列出所有表、再查看目标表结构、然后写查询语句执行、最后基于结果回答整个过程完全自主。4.2 本地 CSV/文件数据 MCP 的玩法与边界除了数据库很多场景是基于本地文件的。比如你在网上下载了一份行业数据 CSV希望 AI 帮你统计并做分析。这时候用文件系统 MCP 就能解决。官方server-filesystem支持把多个目录设成白名单claude mcp add local-data -- npx -y modelcontextprotocol/server-filesystem ~/data ~/workpace/reports配置完成后Claude Code 就可以列出目录、读取文件内容、统计行数、筛选字段。我自己在本地搭过一个“个人知识库”目录里面专门放技术备忘、会议记录和调研总结然后告诉 Claude Code 这些文件都在这让它遇到问题时先查这里。它真的会先去检索相关文件然后结合内容回答效果比单纯塞 prompt 好得多。这种方式在热词里被称为“AI agent skill memory mcp”的组合玩法——用 MCP 做记忆存储用 skill 管理行为方式Claude Code 作为执行主体。边界也很明确它只能访问白名单目录目录外的文件它读不到它读取的是文本而非人的“理解”所以文件最好有清晰结构比如 Markdown 带标题、CSV 带表头这些都能显著提升 AI 的解析质量。4.3 MCP 调用顺序的优化减少无效上下文接入多个 MCP Server 后你可能会发现一个问题模型动不动就去调用某个工具但经常问一些无关紧要的东西浪费 token 和时间。这通常不是模型变笨了而是工具描述和上下文没有引导好。有两种调优手段第一种是在对话里直接约束它“不要调用数据库工具只看本地文件”。Claude Code 的 Agent 规划模块会把你这句话纳入工具选择考量。第二种是调整 MCP Server 的工具描述。如果你自己写 Server工具描述里应该写清楚“在什么场景下使用、不要在什么场景下使用”。比如你的数据库查询工具可以描述为“仅在用户明确提到订单、用户表等数据时使用”这样能显著降低误调用。在实际使用中我习惯把“探查性”的 Server如文件搜索、数据库 schema 查看和“动作类”的 Server如发请求、写文件分成两组去配置或者在同一个任务里用自然语言明确优先级让 AI 先看轻量信息再决定是否需要深入调用。上下文越短模型每一步的决策质量越高。这个经验在工具变多之后尤其重要。5. 模型路由进阶在 Claude Code 里切换 DeepSeek 等第三方模型5.1 为什么社区都在折腾 base URLClaude Code 默认调用的是 Anthropic 的模型服务但很多开发者因为账号、成本等原因选择把模型路由切到其他服务商。热门搜索里“claude code 接入 deepseek”能排到前面说明这已经是一个普遍的开发需求而不是个别玩家的玩法。原理其实不复杂Claude Code 有一套环境变量可以覆盖默认的 API 地址和鉴权信息。只要你使用的第三方服务提供了 Anthropic 兼容的 API 端点Claude Code 就能把它当成模型后端来用。DeepSeek 很早就提供了 Anthropic 兼容接口社区里的 Claude Code 接入 DeepSeek 教程基本上都是基于这一套字段配置的。我的建议是如果你只是体验一下切换没有任何心理负担如果是生产环境还是要先做小范围验证尤其是工具调用能力是否稳定而不是只看对话文本是否流畅。5.2 通过环境变量切换模型的完整配置以下配置在 Linux/macOS 的终端里可以直接用Windows PowerShell 用户请把export换成$env:变量名...的写法。export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的_DeepSeek_API_Key export ANTHROPIC_MODELdeepseek-chat claudeANTHROPIC_BASE_URL覆盖默认 API 地址指向兼容 Anthropic 协议的服务端点。ANTHROPIC_AUTH_TOKEN作为 Bearer Token 发给服务端鉴权。ANTHROPIC_MODEL指定要用的模型名。第一次切换时可能会有一种“好像没生效”的错觉因为 Claude Code 的启动页面不会明显标注当前模型。你可以直接问它“你是什么模型”它会从系统提示里读到模型名。注意这里的端点地址和模型名要以 DeepSeek 官方文档为准不同时期可能会有变化。如果你不想每次都在终端里 export可以写到~/.claude/settings.json里{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-xxxx, ANTHROPIC_MODEL: deepseek-chat } }5.3 换模型后的差异与调试建议切换模型之后最明显的差异通常不在日常聊天而在 Agent 任务执行上。Claude Code 的设计对模型的基础推理能力要求很高特别是多步骤工具调用。我实测下来不同模型在“该不该调工具、什么时候调工具、调完之后怎么归纳”这三个环节的表现差异很大这也是没办法的事Anthropic 自家模型对自家的工具协议有天然的优势。调试建议只有一条先跑一个极简任务比如“读取当前目录下 README.md 的第一行”确认基本工具调用正常再逐步提高任务复杂度。如果模型频繁在不该调用时调用或调用后不关注返回结果优先别怀疑 MCP 配置而是考虑换回原生模型或调整模型参数。不要试图用一个第三方模型完成所有高难度 agent 任务那样你会花大量时间在调试上产出却不一定理想。6. 二次开发半小时写一个自己的 MCP Server6.1 选 Python 还是 Node我的理由配置别人的 MCP Server 只是第一步真正把 Claude Code 变成自己趁手工具的关键是写自己的 MCP Server。很多人看到“自己写”就害怕但 MCP 的 SDK 已经把大部分协议细节封装好了实际代码量比你想的少得多。语言选择上Python 和 Node 是两大主流。我的建议是如果你熟悉 Python就直接用 FastMCP 库它是目前最省事的开发方式装饰器一标函数自动变成工具如果你在 Node 生态里官方 SDK 也很好用且和 npm 生态整合方便。我下面的示例用 Python因为 FastMCP 写好后直接在命令行注册调试链路最短。6.2 用 FastMCP 暴露一个真实工具先安装依赖pip install mcp[cli]然后创建一个 Python 文件比如server.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(my-dev-tools) mcp.tool() def list_ports(keyword: str ) - list[str]: 列出本机正在监听的端口keyword 用于模糊过滤。适合排查端口占用。 import subprocess result subprocess.run( [netstat, -an], capture_outputTrue, textTrue, encodingutf-8, errorsignore ) lines result.stdout.splitlines() filtered [ line.strip() for line in lines if LISTENING in line and keyword.lower() in line.lower() ] return filtered[:20] mcp.tool() def read_env(prefix: str ) - list[str]: 读取当前环境变量里前缀为 prefix 的项用于排查配置是否生效。 import os return [ f{k}{v} for k, v in os.environ.items() if k.startswith(prefix.upper()) ] if __name__ __main__: mcp.run()这里有两个工具一个是查端口一个是查环境变量。在 FastMCP 里每个函数的 docstring 就是工具的描述Claude Code 会把这段描述和参数 schema 一起发给模型。所以 docstring 一定要写清楚“这个工具是干嘛的、适合什么场景”这不是注释是给模型的说明书。6.3 注册、调试和更新自己写的 Server启动方式很简单python server.py它会启动一个 MCP Server 进程默认走 stdio 协议也就是通过标准输入输出与 Claude Code 通信。注册到 Claude Codeclaude mcp add my-dev-tools -- python /绝对路径/server.py注意这里必须使用绝对路径并且如果用了虚拟环境python要指向 venv 里的解释器否则注册之后会报找不到依赖。注册后重新启动 Claude Code输入/mcp查看 Server 状态应该能看到my-dev-tools处于 connected 状态。然后你可以直接对它说“帮我看看 8080 端口有没有被监听”看它是否会调用list_ports工具。如果调用了并返回结果那就是端到端全部打通了。以后改了 server.py 里的函数不需要重新注册配置只需要重启 Claude Code因为 Claude Code 会缓存 MCP Server 的工具列表或者用/mcp面板 reconnect。这个细节我一开始也不知道每次改代码都重新 add后来才发现重启就能生效。6.4 从工具到 Skill/Memory个人化 Agent 的进阶设计写好自己的 MCP Server 之后你会发现一个更大的可能性把 MCP 工具和 Claude Code 的 Skills、Memory 机制组合起来做一个真正个性化的 Agent。Claude Code 的 Skills 放在~/.claude/skills或项目级.claude/skills目录下每个 Skill 是一个目录里面有一个SKILL.md描述这个技能在什么场景下触发以及执行该技能时需要的步骤和规范。举个例子你可以写一个名为code-review的 Skill里面规定“每次 code review 时要先读取变更文件、再对照团队规范检查、最后输出问题清单”。当 Claude Code 检测到当前任务是 code review 时它会自动加载这个 Skill 的指令再配合 MCP Server 暴露的 Git 操作工具整个流程就自动化了。我的个人方案是用文件系统 MCP 充当长期记忆的读写层把所有项目的决策记录和常用规范写在一个memory目录里用 Skills 规定每类任务的执行模板用自定义 MCP Server 打通实际的系统操作。这样一套组合下来Claude Code 才真正像一个熟悉我工作习惯的同事而不是一个每次都要从头教的新人这也是我最近最推荐大家尝试的方向。7. 高频问题与我的排错经验7.1 会话历史存在哪--resume 与 ~/.claude/projects很多第一次用 Claude Code 的人都会问对话记录存在哪里下次打开还能恢复吗Claude Code 的会话记录默认存放在~/.claude/projects目录下每个项目对应一个以项目路径编码后的目录里面是以.jsonl格式保存的会话文件。你重新打开终端运行claude时可以用claude --continue恢复上一次对话或者用claude --resume从历史列表里选择某一次会话继续。我自己的习惯是每天工作结束前把当天有参考价值的对话内容做一次整理把结论和关键代码片段抽出来放进本地知识库目录而不仅仅是依赖 Claude Code 的历史文件。因为历史文件是流水账信息密度低过几天再回去翻你很难快速找到想要的那段内容而整理后的知识库能被文件 MCP 直接读取下次提问时 AI 能直接基于它回答价值高得多。7.2 环境变量不生效是缓存还是路径问题最经典的场景是你在终端里 export 了ANTHROPIC_BASE_URL运行claude但模型好像还是旧的那个或者 MCP Server 启动时读不到你设置的环境变量。这种情况十有八九是进程启动顺序的问题。MCP Server 是由 Claude Code 这个进程启动的子进程环境变量继承自 Claude Code 进程。如果你是在某个终端 export 的变量但 Claude Code 是从桌面图标或另一个终端启动的那它继承不到。这就是为什么我推荐把重要环境变量写进~/.claude/settings.json的env字段而不是每次临时 export。另外改完环境变量之后必须完全退出 Claude Code 再重启它启动时会把环境变量固化到上下文中间不会在运行中重新读取。我用“重启大法”解决过不下十次疑难杂症。7.3 权限白名单与控制问题文件系统 MCP 默认只允许访问你传入的目录参数这是第一道防线。但因为 MCP Server 是独立进程如果你在本地启动脚本时传了根目录或用户主目录作为白名单那 AI 理论上就能访问所有文件。我建议遵守最小权限原则给文件工具只开它真正需要的目录比如项目目录加一个输出目录而不是~或/。如果遇到“明明配了文件工具但 AI 说它读不到文件”的情况先检查 MCP 启动参数里的目录白名单对不对再用claude mcp get查看完整配置确认没有写错路径。7.4 stdio 与 SSE本地和远程服务的差异MCP Server 有两种常见的通信方式stdio 和 SSEServer-Sent Events。stdio 模式是本地进程之间的标准输入输出通信Claude Code 直接启动子进程简单、低延迟、不需要开放端口本地开发几乎都用这种。SSE 则是通过网络 HTTP 通信用于连接远程部署的 MCP Server比如团队里有一台共享的数据库查询服务你可以把它暴露成一个远程 MCP Server然后在本地的 Claude Code 里通过 URL 连接。配置远程 Server 时命令不再是指定 command而是指定 urlclaude mcp add remote-db --transport http http://your-server:port/mcp这里要格外注意认证问题。远程 MCP Server 如果没有鉴权等于把这个端口暴露给了所有能访问到它的人。实际部署时建议加一层 Token 校验并限制来源 IP。本地开发中能走 stdio 就不要用 SSE可以少一大半网络层的问题。回看我这一路折腾下来的经验MCP 真正改变我工作方式的不是某一个 Server而是让我意识到AI 编程工具的能力上限不取决于模型多聪明而取决于你给它接了多少靠谱的“手和脚”。文件系统、数据库、设计稿、GitHub、自研工具每接一个都是在扩宽它单打独斗的边界。如果你现在还在用裸奔版的 Claude Code这篇文章里随便挑一个 MCP 装上试试体验差别会非常直观。后面如果你们社区里有什么好用的 MCP Server也欢迎交流我最近也在收集更多实际项目里验证过的组合方案。 我第一次用 Claude Code 的时候说实话有点失望。它确实能读懂我粘贴过去的代码片段也能跑一些简单的命令但总觉得它像个被绑住手脚的实习生——你说一句它动一下让它去看数据库、翻设计稿、改配置文件它全都干不了。直到我花了半下午把 MCP 接上体验才彻底变了它开始能自己读项目目录、连数据库查表结构、把 GitHub 上的 issue 和 PR 拉进上下文真正变成了一个可以“自己动手”的结对同事。这篇文章不打算写成像官方文档那样的流水账而是围绕我从安装到二次开发这整条链路把 Claude Code 与 MCP 的配合讲透。内容包括MCP 协议到底是什么、Claude Code 怎么装、MCP Server 怎么配、本地文件和数据库怎么接、设计稿工具怎么打通、第三方模型怎么切换、以及最后手写一个自己的 MCP Server。无论你是刚听说 MCP 的新手还是已经在用但在配置上踩过坑的开发者这里都有可以直接抄作业的内容。1. 为什么说 MCP 是 Claude Code 的“第二套手脚”协议本质再理解1.1 Host、Server 与 Client一个 USB-C 接口的类比在讲配置之前我强烈建议你先花五分钟搞懂 MCP 里那几个名词。因为后面所有操作都在围绕这几层关系转搞不清的话报错的时候你连去哪看都不知道。MCP 的全称是 Model Context Protocol模型上下文协议。你可以把它理解成 AI 世界的 USB-C 接口以前每个设备都有自己的充电口现在大家统一成一个标准插上就能用。MCP 解决的是同样的问题——不同的 AI 应用要接入不同的数据源和工具如果每个都单独开发工作量巨大有了 MCPAI 应用只要实现一次协议就能接上所有实现了该协议的“外接设备”。在具体的架构里有三个角色这是最容易绕晕的地方MCP Host运行 AI 应用的主程序比如 Claude Code、Cursor、VS Code 里的 AI 插件。它是发起方负责管理会话、决定什么时候调工具。MCP ClientHost 内部与 Server 建立连接的通道组件。一个 Host 里可以启动多个 Client分别连不同的 Server。MCP Server真正干活的服务进程它暴露一组“工具”比如读文件、查数据库、搜索网页。Server 通过标准协议把工具列表告诉 HostHost 再把这个列表交给模型决策。你可以简单地理解Claude Code 是大脑MCP Server 是手和脚而 MCP Client 是神经线。大脑不直接控制手而是通过神经线发指令让手去执行具体的动作。这套解耦设计最大的好处是你不需要为了让 AI 能读 PDF 而改 Claude Code 的代码只需要加一个 PDF 相关的 MCP Server 就行。1.2 MCP 是怎么被调用的一次工具调用的完整链路很多教程直接让你复制配置命令但没说清楚背后发生了什么。这里我用一次“读取项目配置文件”的请求把整条链路拆开第一步Claude Code 启动时会读取所有已注册的 MCP Server 配置挨个启动这些服务进程并询问它们的工具列表。这些工具包括工具名、描述、参数 SchemaJSON Schema 格式。第二步当你在对话里让 AI“看一下项目的 package.json 里有没有 eslint 配置”时模型会先判断这个任务可以通过某个 MCP 工具来完成。于是它生成一个工具调用请求里面带上了具体的参数比如文件路径。第三步Claude Code 作为 Host 收到这个请求通过对应的 Client 转发给那个 MCP Server。Server 执行完读取操作把文件内容或结果原样返回。第四步Claude Code 把返回结果塞回模型上下文模型基于这些内容继续推理最终生成回答。完整链路就是模型 → 生成工具调用 → Host 转发 → Server 执行 → 结果回传 → 模型继续。这也说明了一个关键点MCP 的“智能”并不在于 Server 本身而在于模型能否在合适的时机选择合适的工具。所以工具描述写得是否清楚直接影响 AI 的使用效果后面写自定义 Server 时我会再强调这一点。1.3 为什么 Claude Code 与 MCP 的组合被反复提及其实 MCP 并不是 Claude Code 的专属功能Cursor、Trae、Codex 等很多工具都已经支持。但 Claude Code 有一个特点让它特别适合和 MCP 搭配它是 Agent 形态而不是 Chat 形态。早期 AI 编程工具是你在输入框里问一句、它答一句而 Claude Code 是一个真正的 Agent——它自己会规划任务、按顺序调用工具、中途根据结果调整策略。MCP 给了它足够多的“工具”它的 agent 能力才真正有了发挥空间。我第一次感受到这种质变是给它接上了一个本地文件系统 MCP。以前我让它“统计一下这个目录下所有 Python 文件的函数数量”它要么让我把文件内容复制进去要么用只读 shell 命令一个一个数。接上文件工具后它直接列出目录、逐个读取文件、自己写个小脚本统计完再汇总。整个过程中我不需要告诉它每一步怎么做它自己就完成了。这种“把活交给它而不是把字喂给它”的体验差异就是 MCP 带来的核心价值。2. 环境搭建三种安装路径与登录鉴权全流程2.1 前置检查Node 版本与 npm 源Claude Code 目前是通过 npm 分发的命令行工具所以第一步是确认本机有 Node.js 环境。建议 Node 版本 18 及以上太低的话 npm 安装和工具运行都可能报兼容性问题。Windows 和 macOS 的检查方式一样node -v npm -v如果没装 Node去官网下载 LTS 版本或者用 nvm 这类版本管理工具安装都行。个人建议用 nvm方便以后切换版本也避免系统全局目录权限问题。还有一个容易踩坑的点是 npm 源。如果你之前为了加速包下载把 registry 换成了国内镜像那装 anthropic-ai/claude-code 时最好先确认镜像源是否同步了最新版本。我遇到过镜像源版本滞后导致安装后启动报错的情况解决办法是临时切回官方源再装npm install -g anthropic-ai/claude-code --registryhttps://registry.npmjs.org装完之后验证一下claude --version如果输出版本号说明安装成功。2.2 全局安装、卸载与重装全局安装是最常规的路径好处是命令行里直接能敲claude命令npm install -g anthropic-ai/claude-code这个包默认安装在全局 node_modules 下命令链接到 PATH 里。不同系统的全局目录路径不一样macOS/Linux 一般在/usr/local/lib/node_modulesWindows 则取决于你的 Node 安装路径。卸载也很简单npm uninstall -g anthropic-ai/claude-code如果你发现版本行为异常想重装我的建议是先卸载再手动清理两个目录~/.claude用户级配置、历史记录、skills 等~/.claude.json用户级 MCP 配置等Windows 上路径类似在用户主目录下然后重新全局安装。注意清理~/.claude会同时清掉登录凭证和对话历史重装前想清楚。如果只是想降版本npm install -g anthropic-ai/claude-code版本号更安全。2.3 登录鉴权与第三方模型接入前的预备知识装完后直接运行claude会进入首次启动引导。你需要先登录这一步本质上是让 Claude Code 拿到调用模型 API 的凭证。Claude Code 支持的鉴权方式主要有两种Claude 账号订阅登录在启动引导中会打开浏览器完成 OAuth 登录。适合有 Claude 订阅账号的用户。API Key如果你使用 Anthropic API可以设置ANTHROPIC_API_KEY环境变量。适合按量计费的用户。如果你用的是第三方模型比如 DeepSeek那情况又不同需要的是 Anthropic 兼容 API 的接口地址和 Token通过环境变量注入。这部分我在第 5 章专门展开讲。这里有个小建议如果后面要用 MCP Server 里的某些需要 API Key 的工具比如 GitHub、Figma不要偷懒直接写死在配置里优先放到环境变量或使用env字段注入。原因后面排错章节会讲配置文件一旦提交进 Git 仓库密钥就泄露了。2.4 在 VSCode 里使用 Claude Code很多人习惯在 VSCode 里写代码Claude Code 也提供了官方扩展。安装方式很简单VSCode 扩展市场搜索 “Claude Code”安装官方发布的那个即可。安装后你可以通过侧边栏面板打开 Claude Code 的对话界面也可以在 VSCode 的终端里直接运行claude。我自己更喜欢后者因为终端里能更好地观察 Claude Code 执行命令的过程也更贴近 CLI 的完整能力。在 VSCode 中使用时有个细节终端会话默认继承当前工作目录但如果你通过面板打开它可能会基于当前打开的文件夹运行。确保你运行 Claude Code 的目录就是项目根目录否则后续 MCP 的项目级配置.mcp.json会读不到。3. 接入常用 MCP Server本地文件、GitHub、Figma 与蓝湖3.1 用 claude mcp add 注册第一个 MCP Server命令行的核心操作其实就是claude mcp这个命令族。先看几个最常用的# 查看当前所有 MCP Server 及其状态 claude mcp list # 添加一个 MCP Server用户级 claude mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem ~/projects # 删除 claude mcp remove filesystem # 查看某个 MCP Server 的详细配置 claude mcp get filesystem注意--后面跟的是真正的启动命令。也就是说MCP Server 本质上就是一个可执行进程Claude Code 负责启动它并通过标准输入输出通信。npx -y modelcontextprotocol/server-filesystem这条命令的意思是用 npx 直接拉取并运行官方文件系统 Server 包后面的~/projects是传给它的参数限定它只能访问这个目录。我建议你第一次就试这个文件系统 Server因为它最直观也最能体 MCP 的价值。跑完claude mcp add之后重启 Claude Code 让它重新加载配置然后你可以直接问它“帮我看看 ~/projects 下面有哪些 Python 项目”。如果它能报出目录列表说明链路全部打通了。3.2 用 .mcp.json 管理项目级 MCPclaude mcp add默认是把配置写到用户级但一个项目可能需要专属的工具配置。这时候用项目级配置文件更合适。在项目根目录创建.mcp.json内容格式如下{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./data], env: {} }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: 你的_GITHUB_PAT } } } }这个文件的优点是可以提交到 Git团队成员共享同一套 MCP 配置。但正因为大家共享所以里面的密钥绝不能写真实值建议用${GITHUB_TOKEN}这种占位符然后在自己的环境变量里配置或使用~/.claude/settings.json里对每个项目进行环境变量的映射。项目的本地个性化配置放在.mcp.local.json这个文件默认不进版本库适合存放个人专用的敏感配置。3.3 GitHub MCP把 issues 和 PR 拉进上下文做开源项目或者团队协作时Claude Code 需要访问 GitHub 上的 issue、PR 和代码仓库信息。虽然它本身可以通过gh命令行工具实现部分功能但通过 MCP 接入后模型获得的是更完整的结构化工具集比如搜索 issue、读取 PR 评论、创建 issue、列出分支等。GitHub 的官方 MCP Server 是modelcontextprotocol/server-github。它需要 GitHub Personal Access Token创建位置在 GitHub 的 Settings → Developer settings → Personal access tokens注意勾选repo、workflow、read:org等权限。一个比较顺手的用法是你在 Claude Code 里说“这个仓库最近的 issue 都在讨论什么问题帮我总结一下”它会通过 GitHub MCP 拉取 issue 列表和关键正文然后汇总。如果只靠传统 prompt 粘贴这个流程会很繁琐。3.4 设计稿直接进代码Figma / 蓝湖 MCP 与 token 获取AI 编程工具和设计稿之间的打通是中文社区最近一直在讨论的话题。很多人搜索“figma mcp token在哪获取”“蓝湖mcp使用”就是想知道怎么让 Claude 直接读取设计稿的标注从而生成还原度更高的代码。Figma 官方提供了 Dev Mode MCP Server包名是figma/dev-mode-mcp。它的核心工具是读取当前选中设计元素的开发资源包括样式属性、切图信息、代码片段等。Figma 的 Personal Access Token 获取路径是打开 Figma 网页 → 点击头像 → Settings → Security → Personal access tokens → Generate new token。生成后复制保存这个 token 只在创建时显示一次。注册命令示例claude mcp add figma-dev -s project -- npx -y figma/dev-mode-mcp --token你的FIGMA_TOKEN蓝湖的 MCP 接入逻辑类似通常是在蓝湖开放平台申请 API Key然后把这个 key 作为 MCP Server 的环境变量传给 Claude Code。因为蓝湖的开放接口服务商不同时期更新较快我建议以蓝湖官方文档为准思路和 Figma 是相通的注册 Server → 配置 Token → 在对话中让 Claude 读取设计稿资源。这里有一个经验设计稿 MCP 返回的原始信息往往非常冗长模型一次能塞进去的上下文有限。我的做法是先用“这个设计稿的页面主色调是什么”“按钮圆角是多少”这类小问题让模型只提取关键值然后再让它基于这些值生成 CSS而不是一上来就让它“根据设计稿写整个页面”。控制信息粒度是使用设计稿类 MCP 的关键技巧。4. 本地数据与数据库让 AI 直接读表结构和文件4.1 Postgres MCP 快速接入与授权策略开发中最常见的需求是让 AI 理解数据库的表结构。以前的做法是把建表语句粘贴给模型但表一多就没法操作了。通过 MCP 接入 Postgres 后Claude Code 能自己执行查询、读取 schema基于真实数据去分析问题。官方 Postgres MCP Server 的注册方式claude mcp add postgres -- npx -y modelcontextprotocol/server-postgres postgresql://用户名:密码localhost:5432/数据库名建议连接本地开发库而不是生产库。我当时贪图方便直接连了线上预发环境的只读账号后来发现执行效率很低因为模型发起查询时没法限制复杂度一条全表扫描就可能打满数据库。最好在数据库层面单独建一个专门给 AI 用的账号权限只放大到需要的数据库、只读模式并且设置 statement timeout。这是给 AI 开数据库权限时最重要的一条安全底线。MCP Server 暴露给模型的工具包括 execute_query、list_tables、describe_table 等。你会看到 Claude 先列出所有表、再查看目标表结构、然后写查询语句执行、最后基于结果回答整个过程完全自主。4.2 本地 CSV/文件数据 MCP 的玩法与边界除了数据库很多场景是基于本地文件的。比如你在网上下载了一份行业数据 CSV希望 AI 帮你统计并做分析。这时候用文件系统 MCP 就能解决。官方server-filesystem支持把多个目录设成白名单claude mcp add local-data -- npx -y modelcontextprotocol/server-filesystem ~/data ~/workpace/reports配置完成后Claude Code 就可以列出目录、读取文件内容、统计行数、筛选字段。我自己在本地搭过一个“个人知识库”目录里面专门放技术备忘、会议记录和调研总结然后告诉 Claude Code 这些文件都在这让它遇到问题时先查这里。它真的会先去检索相关文件然后结合内容回答效果比单纯塞 prompt 好得多。这种方式在热词里被称为“AI agent skill memory mcp”的组合玩法——用 MCP 做记忆存储用 skill 管理行为方式Claude Code 作为执行主体。边界也很明确它只能访问白名单目录目录外的文件它读不到它读取的是文本而非人的“理解”所以文件最好有清晰结构比如 Markdown 带标题、CSV 带表头这些都能显著提升 AI 的解析质量。4.3 MCP 调用顺序的优化减少无效上下文接入多个 MCP Server 后你可能会发现一个问题模型动不动就去调用某个工具但经常问一些无关紧要的东西浪费 token 和时间。这通常不是模型变笨了而是工具描述和上下文没有引导好。有两种调优手段第一种是在对话里直接约束它“不要调用数据库工具只看本地文件”。Claude Code 的 Agent 规划模块会把你这句话纳入工具选择考量。第二种是调整 MCP Server 的工具描述。如果你自己写 Server工具描述里应该写清楚“在什么场景下使用、不要在什么场景下使用”。比如你的数据库查询工具可以描述为“仅在用户明确提到订单、用户表等数据时使用”这样能显著降低误调用。在实际使用中我习惯把“探查性”的 Server如文件搜索、数据库 schema 查看和“动作类”的 Server如发请求、写文件分成两组去配置或者在同一个任务里用自然语言明确优先级让 AI 先看轻量信息再决定是否需要深入调用。上下文越短模型每一步的决策质量越高。这个经验在工具变多之后尤其重要。5. 模型路由进阶在 Claude Code 里切换 DeepSeek 等第三方模型5.1 为什么社区都在折腾 base URLClaude Code 默认调用的是 Anthropic 的模型服务但很多开发者因为账号、成本等原因选择把模型路由切到其他服务商。热门搜索里“claude code 接入 deepseek”能排到前面说明这已经是一个普遍的开发需求而不是个别玩家的玩法。原理其实不复杂Claude Code 有一套环境变量可以覆盖默认的 API 地址和鉴权信息。只要你使用的第三方服务提供了 Anthropic 兼容的 API 端点Claude Code 就能把它当成模型后端来用。DeepSeek 很早就提供了 Anthropic 兼容接口社区里的 Claude Code 接入 DeepSeek 教程基本上都是基于这一套字段配置的。我的建议是如果你只是体验一下切换没有任何心理负担如果是生产环境还是要先做小范围验证尤其是工具调用能力是否稳定而不是只看对话文本是否流畅。5.2 通过环境变量切换模型的完整配置以下配置在 Linux/macOS 的终端里可以直接用Windows PowerShell 用户请把export换成$env:变量名...的写法。export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的_DeepSeek_API_Key export ANTHROPIC_MODELdeepseek-chat claudeANTHROPIC_BASE_URL覆盖默认 API 地址指向兼容 Anthropic 协议的服务端点。ANTHROPIC_AUTH_TOKEN作为 Bearer Token 发给服务端鉴权。ANTHROPIC_MODEL指定要用的模型名。第一次切换时可能会有一种“好像没生效”的错觉因为 Claude Code 的启动页面不会明显标注当前模型。你可以直接问它“你是什么模型”它会从系统提示里读到模型名。注意这里的端点地址和模型名要以 DeepSeek 官方文档为准不同时期可能会有变化。如果你不想每次都在终端里 export可以写到~/.claude/settings.json里{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: sk-xxxx, ANTHROPIC_MODEL: deepseek-chat } }5.3 换模型后的差异与调试建议切换模型之后最明显的差异通常不在日常聊天而在 Agent 任务执行上。Claude Code 的设计对模型的基础推理能力要求很高特别是多步骤工具调用。我实测下来不同模型在“该不该调工具、什么时候调工具、调完之后怎么归纳”这三个环节的表现差异很大这也是没办法的事Anthropic 自家模型对自家的工具协议有天然的优势。调试建议只有一条先跑一个极简任务比如“读取当前目录下 README.md 的第一行”确认基本工具调用正常再逐步提高任务复杂度。如果模型频繁在不该调用时调用或调用后不关注返回结果优先别怀疑 MCP 配置而是考虑换回原生模型或调整模型参数。不要试图用一个第三方模型完成所有高难度 agent 任务那样你会花大量时间在调试上产出却不一定理想。6. 二次开发半小时写一个自己的 MCP Server6.1 选 Python 还是 Node我的理由配置别人的 MCP Server 只是第一步真正把 Claude Code 变成自己趁手工具的关键是写自己的 MCP Server。很多人看到“自己写”就害怕但 MCP 的 SDK 已经把大部分协议细节封装好了实际代码量比你想的少得多。语言选择上Python 和 Node 是两大主流。我的建议是如果你熟悉 Python就直接用 FastMCP 库它是目前最省事的开发方式装饰器一标函数自动变成工具如果你在 Node 生态里官方 SDK 也很好用且和 npm 生态整合方便。我下面的示例用 Python因为 FastMCP 写好后直接在命令行注册调试链路最短。6.2 用 FastMCP 暴露一个真实工具先安装依赖pip install mcp[cli]然后创建一个 Python 文件比如server.pyfrom mcp.server.fastmcp import FastMCP mcp FastMCP(my-dev-tools) mcp.tool() def list_ports(keyword: str ) - list[str]: 列出本机正在监听的端口keyword 用于模糊过滤。适合排查端口占用。 import subprocess result subprocess.run( [netstat, -an], capture_outputTrue, textTrue, encodingutf-8, errorsignore ) lines result.stdout.splitlines() filtered [ line.strip() for line in lines if LISTENING in line and keyword.lower() in line.lower() ] return filtered[:20] mcp.tool() def read_env(prefix: str ) - list[str]: 读取当前环境变量里前缀为 prefix 的项用于排查配置是否生效。 import os return [ f{k}{v} for k, v in os.environ.items() if k.startswith(prefix.upper()) ] if __name__ __main__: mcp.run()这里有两个工具一个是查端口一个是查环境变量。在 FastMCP 里每个函数的 docstring 就是工具的描述Claude Code 会把这段描述和参数 schema 一起发给模型。所以 docstring 一定要写清楚“这个工具是干嘛的、适合什么场景”这不是注释是给模型的说明书。6.3 注册、调试和更新自己写的 Server启动方式很简单python server.py它会启动一个 MCP Server 进程默认走 stdio 协议也就是通过标准输入输出与 Claude Code 通信。注册到 Claude Codeclaude mcp add my-dev-tools -- python /绝对路径/server.py注意这里必须使用绝对路径并且如果用了虚拟环境python要指向 venv 里的解释器否则注册之后会报找不到依赖。注册后重新启动 Claude Code输入/mcp查看 Server 状态应该能看到my-dev-tools处于 connected 状态。然后你可以直接对它说“帮我看看 8080 端口有没有被监听”看它是否会调用list_ports工具。如果调用了并返回结果那就是端到端全部打通了。以后改了 server.py 里的函数不需要重新注册配置只需要重启 Claude Code因为 Claude Code 会缓存 MCP Server 的工具列表或者用/mcp面板 reconnect。这个细节我一开始也不知道每次改代码都重新 add后来才发现重启就能生效。6.4 从工具到 Skill/Memory个人化 Agent 的进阶设计写好自己的 MCP Server 之后你会发现一个更大的可能性把 MCP 工具和 Claude Code 的 Skills、Memory 机制组合起来做一个真正个性化的 Agent。Claude Code 的 Skills 放在~/.claude/skills或项目级.claude/skills目录下每个 Skill 是一个目录里面有一个SKILL.md描述这个技能在什么场景下触发以及执行该技能时需要的步骤和规范。举个例子你可以写一个名为code-review的 Skill里面规定“每次 code review 时要先读取变更文件、再对照团队规范检查、最后输出问题清单”。当 Claude Code 检测到当前任务是 code review 时它会自动加载这个 Skill 的指令再配合 MCP Server 暴露的 Git 操作工具整个流程就自动化了。我的个人方案是用文件系统 MCP 充当长期记忆的读写层把所有项目的决策记录和常用规范写在一个memory目录里用 Skills 规定每类任务的执行模板用自定义 MCP Server 打通实际的系统操作。这样一套组合下来Claude Code 才真正像一个熟悉我工作习惯的同事而不是一个每次都要从头教的新人这也是我最近最推荐大家尝试的方向。7. 高频问题与我的排错经验7.1 会话历史存在哪--resume 与 ~/.claude/projects很多第一次用 Claude Code 的人都会问对话记录存在哪里下次打开还能恢复吗Claude Code 的会话记录默认存放在~/.claude/projects目录下每个项目对应一个以项目路径编码后的目录里面是以.jsonl格式保存的会话文件。你重新打开终端运行claude时可以用claude --continue恢复上一次对话或者用claude --resume从历史列表里选择某一次会话继续。我自己的习惯是每天工作结束前把当天有参考价值的对话内容做一次整理把结论和关键代码片段抽出来放进本地知识库目录而不仅仅是依赖 Claude Code 的历史文件。因为历史文件是流水账信息密度低过几天再回去翻你很难快速找到想要的那段内容而整理后的知识库能被文件 MCP 直接读取下次提问时 AI 能直接基于它回答价值高得多。7.2 环境变量不生效是缓存还是路径问题最经典的场景是你在终端里 export 了ANTHROPIC_BASE_URL运行claude但模型好像还是旧的那个或者 MCP Server 启动时读不到你设置的环境变量。这种情况十有八九是进程启动顺序的问题。MCP Server 是由 Claude Code 这个进程启动的子进程环境变量继承自 Claude Code 进程。如果你是在某个终端 export 的变量但 Claude Code 是从桌面图标或另一个终端启动的那它继承不到。这就是为什么我推荐把重要环境变量写进~/.claude/settings.json的env字段而不是每次临时 export。另外改完环境变量之后必须完全退出 Claude Code 再重启它启动时会把环境变量固化到上下文中间不会在运行中重新读取。我用“重启大法”解决过不下十次疑难杂症。7.3 权限白名单与控制问题文件系统 MCP 默认只允许访问你传入的目录参数这是第一道防线。但因为 MCP Server 是独立进程如果你在本地启动脚本时传了根目录或用户主目录作为白名单那 AI 理论上就能访问所有文件。我建议遵守最小权限原则给文件工具只开它真正需要的目录比如项目目录加一个输出目录而不是~或/。如果遇到“明明配了文件工具但 AI 说它读不到文件”的情况先检查 MCP 启动参数里的目录白名单对不对再用claude mcp get查看完整配置确认没有写错路径。7.4 stdio 与 SSE本地和远程服务的差异MCP Server 有两种常见的通信方式stdio 和 SSEServer-Sent Events。stdio 模式是本地进程之间的标准输入输出通信Claude Code 直接启动子进程简单、低延迟、不需要开放端口本地开发几乎都用这种。SSE 则是通过网络 HTTP 通信用于连接远程部署的 MCP Server比如团队里有一台共享的数据库查询服务你可以把它暴露成一个远程 MCP Server然后在本地的 Claude Code 里通过 URL 连接。配置远程 Server 时命令不再是指定 command而是指定 urlclaude mcp add remote-db --transport http http://your-server:port/mcp这里要格外注意认证问题。远程 MCP Server 如果没有鉴权等于把这个端口暴露给了所有能访问到它的人。实际部署时建议加一层 Token 校验并限制来源 IP。本地开发中能走 stdio 就不要用 SSE可以少一大半网络层的问题。回看我这一路折腾下来的经验MCP 真正改变我工作方式的不是某一个 Server而是让我意识到AI 编程工具的能力上限不取决于模型多聪明而取决于你给它接了多少靠谱的“手和脚”。文件系统、数据库、设计稿、GitHub、自研工具每接一个都是在扩宽它单打独斗的边界。如果你现在还在用裸奔版的 Claude Code这篇文章里随便挑一个 MCP 装上试试体验差别会非常直观。后面如果你们社区里有什么好用的 MCP Server也欢迎交流我最近也在收集更多实际项目里验证过的组合方案。