教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载本文以 easy-vibe 开源仓库中 MCP 与 Claude Code 完全指南 为核心骨架结合仓库内真实的 MCP 配置文件与协议原理附录为你系统讲解MCPModel Context Protocol是什么、为什么要在 Claude Code 中使用它、如何完成从入门到生产级的配置与排错。读完本文你将掌握用户级/项目级配置的差异、三种传输模式STDIO / HTTP / SSE的适用场景、用自然语言管理 MCP 服务器的完整工作流以及环境变量加密、版本锁定等工程化最佳实践并能在自己的 vibe coding 项目中立刻落地一套可复用的 MCP 配置。什么是 Claude Code MCPClaude Code是 Anthropic 官方的命令行 AI 编程工具而MCPModel Context Protocol模型上下文协议是让 Claude Code 连接外部工具与服务的开放协议。简单来说MCP 把 Claude Code 从一个只能读写本地文件的 AI 助手升级为可以访问 GitHub、数据库、外部 API 与云服务的超级助手。它是当前 vibe coding 工作流中扩展 AI 编程工具能力边界的核心技术之一在 easy-vibe 的第三阶段高级进阶课程中被列为核心技能与 Claude Code 基础、Skills、Agent Teams 等主题并列参见 docs/ar-sa/stage-3/index.md。从仓库附录 AI 智能体协议原理MCP 与 A2A 中可以了解到 MCP 的关键事实背景发起方Anthropic发布日期2024 年 11 月 25 日开源许可MIT License核心价值让工具开发者一次编写处处使用——只要实现一次 MCP Server所有兼容 MCP 的 AI 应用Claude、Cursor、Windsurf 等都能直接调用。MCP 之所以叫上下文Context协议核心思路是让 AI 按需动态获取完成任务所需的上下文信息而不是把所有信息都硬塞进 Prompt。例如当 AI 需要读取文件时无需你复制粘贴文件内容它可以直接通过 MCP 访问文件系统。附录中给出了协议的分层定位层级协议解决的问题类比1Function CallAI 如何调用本地函数大脑下达指令2MCPAI 如何连接外部工具与数据源充电口的 USB-C 标准3A2A多个 Agent 之间如何通信协作企业微信MCP 就像一个AI 世界的 USB-C 接口过去每个设备都有自己的充电口每种工具都要单独写集成代码而 MCP 统一了 AI 连接所有工具的接口标准。附录中还总结了 MCP 的三大核心能力Tools工具AI 可以调用的函数如查天气、发邮件Resources资源AI 可以读取的数据如文件内容、数据库记录Prompts提示词模板预先定义的提示词模板如代码审查模板、写作模板。为什么在 Claude Code 中使用 MCP没有 MCP 的 Claude Code你能做的事 ✓ 读取本地文件 ✓ 修改代码 ✓ 运行命令 ✓ 使用 Bash 工具 你不能做的事 ✗ 查看你的 GitHub Issues ✗ 访问云数据库 ✗ 调用外部 API ✗ 获取实时天气有 MCP 的 Claude Code你能做的事 ✓ 以上所有原生功能 ✓ 查看 / 创建 GitHub Issues 和 PRs ✓ 查询 SQLite、PostgreSQL 数据库 ✓ 访问 Notion、Slack 等外部服务 ✓ 获取实时天气与地图数据 ✓ 浏览器自动化 ✓ ……以及更多两者的差距正是 vibe coding 从写代码走向做产品的关键接入 MCP 后AI 不再只是一个代码编辑器而是一个能操作真实开发工作流的 Agent。快速上手第 1 步弄清配置文件的位置Claude Code 的 MCP 配置文件位于两个层级层级配置文件路径作用范围用户级~/.claude.json所有项目项目级.claude/mcp.json当前项目建议优先使用项目级配置这样不同项目可以使用不同的 MCP 服务互不干扰。第 2 步用自然语言添加 MCP 服务器在 Claude Code 中你不需要手动编辑配置文件或死记命令直接用自然语言描述你的需求即可你帮我添加一个 GitHub MCP 服务器我的 token 是 ghp_xxx Claude我来帮你配置 GitHub MCP 服务器…… [自动更新 .claude/mcp.json]你添加一个 SQLite 数据库服务器数据库文件在 ./data/app.db Claude好的我来配置 SQLite MCP 服务器……你添加一个 HTTP 类型的 MCP 服务器地址是 https://api.example.com/mcp Claude我来添加这个远程 MCP 服务器……第 3 步验证配置直接向 Claude Code 询问当前可用的服务器你现在有哪些可用的 MCP 服务器 Claude当前已配置的 MCP 服务器 • github - GitHub 集成 • sqlite - SQLite 数据库 • filesystem - 文件系统访问也可以使用诊断命令/doctor第 4 步开始使用配置成功后即可直接用自然语言调用 MCP 功能你帮我在 GitHub 上创建一个 Issue Claude我可以帮你创建 GitHub Issue请告诉我 - 仓库地址例如 owner/repo - Issue 标题 - Issue 描述在 Claude Code 中用自然语言管理 MCP你可以全程用自然语言与 Claude Code 交互来管理服务器无需记住任何子命令你列出所有已配置的 MCP 服务器 你检查 MCP 服务器的连接状态 你删除名为 notion 的 MCP 服务器 你更新 github 服务器的 token当遇到问题时同样可以直接求助你检查一下 MCP 连接出了什么问题 Claude[会自动运行诊断分析配置文件检查服务器状态]配置方式详解用户级配置全局编辑~/.claude.json对所有项目生效{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents] }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your-token } } } }项目级配置推荐编辑项目根目录下的.claude/mcp.json仅对当前项目生效{ mcpServers: { project-db: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, ./data/app.db] } } }项目级配置的优势团队成员可以通过 Git 提交共享配置不同项目可以使用不同的 MCP 服务配置更灵活不会污染全局设置。三种传输模式Claude Code 支持三种 MCP 传输模式STDIO本地进程通过commandargs启动本地子进程适合本地工具{ mcpServers: { local-tool: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path] } } }HTTP远程服务通过url连接远程 HTTP 服务适合部署在服务器上的共享服务可通过headers携带鉴权信息{ mcpServers: { remote-api: { url: https://api.example.com/mcp, transport: http, headers: { Authorization: Bearer your-token } } } }SSE服务器推送事件通过 Server-Sent Events 建立单向服务端推送连接适合流式事件场景{ mcpServers: { streaming: { url: https://api.example.com/sse, transport: sse } } }仓库内的真实 MCP 配置easy-vibe 的 config/mcporter.json为了印证上述配置理论easy-vibe 仓库自身就携带了一份真实的 MCP 配置config/mcporter.json。它使用了基于command的 STDIO 传输模式即本地进程类型注册了一个浏览器 Agent 服务{ mcpServers: { autoglm-browser-agent: { command: /Users/sanbu/.agents/skills/autoglm-browser-agent/dist/mcp_server --start_url https://www.bing.com --window_width 1456 --window_height 819 --resize_width 1456 --resize_height 819 --max_steps 100 --log_dir /Users/sanbu/.agents/skills/autoglm-browser-agent/mcp_output --if_subagent } }, imports: [] }这份配置与上文项目级配置的 JSON 结构完全一致mcpServers对象下以服务器名为键值包含启动命令与参数。各启动参数的含义从命名可以推断--start_url浏览器代理启动后打开的首个页面地址--window_width/--window_height浏览器窗口的宽高--resize_width/--resize_height浏览器视口调整后的目标宽高--max_steps单次任务允许执行的最大步数上限100 步--log_dir运行日志的输出目录--if_subagent是否以子代理模式运行imports: []空数组表示不导入其他配置来源仅使用当前文件声明的服务器。需要注意两点该配置中的command直接指向本机绝对路径/Users/sanbu/.agents/...属于个人机器上的环境依赖换机使用需要同步调整路径同时--start_url指向的外部站点仅为该浏览器代理工具的启动参数与本仓库文档内容无关。这正好印证了原指南不要硬编码、要可移植的实践主张——将路径与密钥交给环境管理才能让团队共享配置而无需逐人手工修改。实战示例示例 1自动化 GitHub 工作流你帮我把当前改动推送到 GitHub然后创建一个标题为 Add new feature 的 PR Claude 1. 检查当前 git 状态…… 2. 创建新分支 feature/new-feature…… 3. 提交改动…… 4. 推送到远端…… 5. 调用 github_create_pull_request 创建 PR…… 6. PR 已创建owner/repo 的 pull request #123示例 2数据库查询你查询数据库中最近注册的 10 个用户 Claude 1. 连接 SQLite 数据库…… 2. 执行查询SELECT * FROM users ORDER BY created_at DESC LIMIT 10 3. 返回结果 - 张三 (zhangexample.com) - 2025-02-28 - 李四 (liexample.com) - 2025-02-27 ……示例 3网页截图分析你打开 https://example.com截图并分析页面设计 Claude 1. 启动浏览器…… 2. 导航到 https://example.com…… 3. 截取屏幕…… 4. [返回截图] 5. 页面设计分析 - 布局采用居中设计最大宽度 1200px - 主色调为蓝色 (#3b82f6) - 导航栏固定于顶部 ……示例 4与 Notion 集成你把刚才写的笔记保存到 Notion Claude 1. 调用 Notion MCP 服务器…… 2. 创建新页面…… 3. 已保存notion.so 页面 xxx调试技巧用自然语言诊断当出错时直接告诉 Claude Code你我的 MCP 服务器连不上帮我检查一下 你GitHub MCP 工具调用失败了是什么原因 你为什么 sqlite 服务器一直显示 connectingClaude Code 会自动执行以下步骤检查配置文件格式校验环境变量测试服务器连接给出具体的修复建议。常见问题排查问题可能原因解决方案服务器未连接配置文件格式错误检查 JSON 语法工具无法调用权限不足检查环境变量连接超时网络问题检查 URL 或网络进程崩溃服务器代码缺陷检查服务器日志手动诊断命令/doctor示例输出系统诊断报告 Claude Code: v2.5.0 ✓ Node.js: v20.0.0 ✓ MCP 服务器状态 • github: ✓ 已连接12 个工具 • sqlite: ✗ 连接失败 - 数据库文件不存在 • puppeteer: ✓ 已连接8 个工具 建议 1. 检查 sqlite 数据库路径是否正确 2. 确认 .claude/mcp.json 格式是否正确最佳实践1. 优先使用项目级配置不同项目往往需要不同的 MCP 服务前端项目可能需要浏览器测试工具后端项目可能需要数据库连接。使用项目级配置每个项目都可以拥有自己专属的 MCP 服务器集合避免一个庞大全局配置造成的混乱。更重要的是项目级配置可以提交到 Git。团队成员克隆项目后无需重新配置即可直接使用相同的 MCP 服务。项目 A前端项目 - .claude/mcp.json 中包含浏览器测试 MCP 项目 B后端项目 - .claude/mcp.json 中包含数据库 MCP2. 敏感信息存入环境变量切勿在配置文件中硬编码密钥。配置文件可能被误提交到 Git 导致密钥泄露。正确做法是将敏感值存入环境变量配置文件中只引用变量名{ env: { GITHUB_TOKEN: $GITHUB_TOKEN, GITHUB_TOKEN: ghp_abc123 } }第一种写法从环境变量读取是正确的第二种写法直接硬编码密钥是错误示范。即便配置文件公开真正的密钥仍然隐藏在环境变量中。3. 锁定服务器版本默认情况下npx -y总是使用 MCP 服务器的最新版本。这可能带来问题新版本可能引入破坏性变更或某个包突然被移除、改名。通过在包名后追加version可以确保始终使用已验证的版本减少自动升级带来的意外{ command: npx, args: [-y, modelcontextprotocol/server-github1.2.3] }4. 为 MCP 配置写文档当项目包含多个 MCP 服务器时新成员可能不清楚每个服务器的用途和所需配置。在.claude/目录下创建README.md说明每个服务器的用途、所需配置以及如何获取凭据可以大幅降低沟通成本# MCP 配置说明 本项目使用的 MCP 服务器 ## github 用于 GitHub 自动化需要 GITHUB_TOKEN。 ## sqlite 连接 ./data/app.db用于查询和修改数据。 ## puppeteer 用于 E2E 测试。Claude Code 与 Claude Desktop 对比特性Claude CodeClaude Desktop配置文件~/.claude.json或.claude/mcp.jsonclaude_desktop_config.json项目级配置✓ 支持✗ 不支持自然语言管理✓ 支持✗ 需手动编辑诊断能力✓/doctor✗ 无热重载✓ 自动✗ 需重启应用适用场景开发工作流、CI/CD日常使用、办公任务常用 MCP 服务器 完整的 MCP 协议原理、内部实现与 A2A 对比请参阅仓库附录AI 智能体协议原理MCP 与 A2AGitHub 服务器功能Issues、PRs、仓库管理{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your-token } } } }获取 Token在 GitHub 账户设置的 Token 管理页面生成 Personal Access Token建议按最小权限原则分配权限。SQLite 服务器功能查询和管理 SQLite 数据库{ mcpServers: { sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, ./data/database.db] } } }文件系统服务器功能访问指定目录内的文件{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents] } } }Puppeteer 浏览器自动化功能浏览器控制、截图、自动化测试{ mcpServers: { puppeteer: { command: npx, args: [-y, modelcontextprotocol/server-puppeteer] } } }Brave 搜索服务器功能网络搜索{ mcpServers: { brave-search: { command: npx, args: [-y, modelcontextprotocol/server-brave-search], env: { BRAVE_API_KEY: your-brave-api-key } } } }参考资源协议原理深度阅读仓库附录 AI 智能体协议原理MCP 与 A2A涵盖 MCP 的发布背景、内部实现、与 Function Call / A2A 的层级关系以及典型应用场景本地文件操作、数据库查询、API 调用、开发工具集成官方资源MCP 官方文档、官方规范文档与官方开源组织modelcontextprotocol以及官方参考服务器实现GitHub、SQLite、PostgreSQL、Filesystem、Puppeteer、Fetch、Brave Search、Git生态资源社区维护的 Awesome MCP Servers 清单、官方 MCP Registry 目录、MCP.so、Smithery 等社区服务器市场以及地图/天气类 MCP 服务器高德、腾讯位置服务、彩云天气、OpenWeatherMap等均可作为扩展选型参考。至此你已经完整掌握了 MCP 从协议原理到生产级配置的全链路知识理解了 MCP 为什么被称为AI 世界的 USB-C学会了用户级与项目级两种配置方式与三种传输模式见证了 easy-vibe 仓库中真实 MCP 配置文件的写法并掌握了自然语言管理、/doctor排错、环境变量保护密钥与版本锁定等工程实践。接下来你可以在自己的 vibe coding 项目中按先项目级配置、再锁定版本、后写文档的顺序为 AI 编程工具接上第一组外部能力。赞分享教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载相关推荐easy-vibe 实战Claude Code MCP 完全指南——从协议原理到自然语言驱动外部工具easy vibe 实战Claude Code MCP 完全指南——从协议原理到自然语言驱动外部工具 MCPModel Context Protocol是教程文档人工智能Vibe Codingeasy-vibe 教程Claude Code MCP 完整配置实战指南easy vibe 教程Claude Code MCP 完整配置实战指南 MCPModel Context Protocol是当前 AI 编程工具链中的关教程文档人工智能Vibe CodingClaude Code MCP 完全指南从自然语言配置到生产级实战Claude Code MCP 完全指南从自然语言配置到生产级实战 导读 本文基于 Datawhale easy vibe 开源仓库中的德语版核心技能文档系教程文档创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考