Claude Code MCP Complete Guide: Extending AI Coding Capabilities with the Model Context Protocol

教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载本篇指南以 easy-vibe 仓库 中 docs/en/stage-3/core-skills/mcp/index.md 为核心骨架结合仓库内的协议原理文档、真实 MCP 配置示例与配套课程进行纵深扩充。你将掌握 MCP 的定位与原理、Claude Code 中两级配置文件的使用、三种传输方式的配置、自然语言管理、调试技巧与工程化最佳实践并能在自己的项目中按需接入 GitHub、SQLite、文件系统、浏览器自动化等外部能力。什么是 Claude Code MCPClaude Code是 Anthropic 官方推出的 AI 命令行工具而MCPModel Context Protocol模型上下文协议则是让 Claude Code 能够连接外部工具和服务的开放协议。简单来说MCP 让 Claude Code 从一个「只能读写本地文件」的 AI 助手变成一个「能访问 GitHub、数据库、API、云服务」的超级助手。它解决的核心问题是大模型不能总把海量上下文硬塞进 Prompt而是应该让 AI按需动态获取上下文信息——这正是 MCP 名字里 Context 一词的含义。在 easy-vibe 的课程体系中MCP 被定位为 Stage 3 进阶开发 中「核心技能」的关键一环与 Claude Code Skills、Agent Teams 并列是让 AI 编码工具突破本地文件边界、接入真实工程环境的核心手段。为什么需要在 Claude Code 中使用 MCP没有 MCP 的 Claude Code你能做的 ✓ 读取本地文件 ✓ 编辑代码 ✓ 运行命令 ✓ 使用 Bash 工具 你不能做的 ✗ 查看你的 GitHub Issues ✗ 访问云数据库 ✗ 调用外部 API ✗ 获取实时天气有了 MCP 的 Claude Code你能做的 ✓ 所有原来的功能 ✓ 查看/创建 GitHub Issues 和 PR ✓ 查询 SQLite、PostgreSQL 数据库 ✓ 访问 Notion、Slack 等外部服务 ✓ 获取实时天气、地图数据 ✓ 浏览器自动化 ✓ ...以及更多底层视角MCP 在 Agent 协议栈中的位置仓库附录文档 AI Agent 协议原理MCP 与 A2A 给出了更系统的分层视角便于你理解 MCP 到底解决哪一层的问题层级协议解决的问题类比1Function CallAI 如何调用本地函数大脑下发指令2MCPAI 如何连接外部工具与数据源USB-C 接口3A2AAgent 之间如何协作通信企业微信MCPModel Context Protocol由 Anthropic 于 2024 年 11 月 25 日发布MIT 许可标准化了「AI 连接外部工具与数据源」的方式正如 USB-C 统一了各类设备的充电接口——工具开发者只需实现一次 MCP Server所有兼容 MCP 的 AI 应用Claude、Cursor、Windsurf 等即可直接使用。A2AAgent-to-Agent Protocol由 Google 于 2025 年 4 月发布Apache 2.0 许可解决的是「多个 Agent 之间如何发现、通信与协作」。两者不是竞争关系而是互补关系选型上调用第三方工具用 MCP构建多 Agent 协作系统用 A2A两者都需要则 MCP A2A。MCP 规范基于JSON-RPC 2.0通信格式提供三类核心能力能力描述示例ToolsAI 可调用的函数查天气、发邮件ResourcesAI 可读取的数据文件内容、数据库记录Prompts预定义的提示词模板代码评审模板、写作模板快速开始步骤 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诊断问题当遇到问题时Claude Code 会自动运行诊断、分析配置文件并检查服务器状态你检查一下 MCP 连接有什么问题 Claude[会自动运行诊断分析配置文件检查服务器状态]配置方式详解用户级配置全局编辑~/.claude.jsonmcpServers对象中的每个 key 即一个服务器名通过commandargs启动本地进程env传入环境变量{ 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 服务互不干扰配置更灵活不会污染全局设置一个仓库内的真实示例easy-vibe 仓库本身也携带了一份 MCP 服务器配置config/mcporter.json。它采用与.claude/mcp.json一致的mcpServers顶层结构注册了一个autoglm-browser-agent本地服务器并通过command指定可执行文件路径与启动参数{ 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: [] }可以从中提取两个要点服务器名 → 完整启动命令配置的实质是把「一个外部能力」映射为「一条可执行的启动命令」。浏览器代理这类服务器往往需要多个启动参数起始 URL、窗口尺寸、最大步数、日志目录等它们都会体现在command中。imports字段部分客户端如 mcporter支持通过imports引用其他配置文件或共享服务器集合便于在多项目间复用 MCP 配置。传输方式配置Claude Code 支持三种传输方式STDIO本地进程最常用的本地传输方式通过commandargs启动一个子进程客户端与服务器通过标准输入输出通信{ mcpServers: { local-tool: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path] } } }HTTP远程服务面向远程服务的传输方式通过url指定 MCP 端点transport: http显式声明传输类型headers用于携带鉴权信息{ mcpServers: { remote-api: { url: https://api.example.com/mcp, transport: http, headers: { Authorization: Bearer your-token } } } }SSE服务器推送基于 Server-Sent Events 的流式传输适合服务器主动推送事件的场景只需声明url与transport: sse{ mcpServers: { streaming: { url: https://api.example.com/sse, transport: sse } } }三种方式的选择原则本地工具、数据库文件优先 STDIO已部署的远程 MCP 服务用 HTTP需要服务端持续推送事件流用 SSE。实战示例示例 1GitHub 工作流自动化你帮我把当前的修改推送到 GitHub然后创建一个 PR标题是添加新功能 Claude 1. 检查当前 git 状态... 2. 创建新分支 feature/new-feature... 3. 提交更改... 4. 推送到远程... 5. 调用 github_create_pull_request 创建 PR... 6. PR 已创建https://github.com/owner/repo/pull/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. 已保存https://notion.so/page/xxx调试技巧使用自然语言诊断遇到问题时直接告诉 Claude Code让它代为排查你我的 MCP 服务器连接不上了帮我检查一下 你GitHub MCP 工具调用失败是什么原因 你为什么 sqlite 服务器一直显示连接中Claude Code 会自动检查配置文件格式验证环境变量测试服务器连接提供具体的修复建议常见问题排查问题可能原因解决方案服务器未连接配置文件格式错误检查 JSON 语法工具无法调用权限不足检查环境变量连接超时网络问题检查 URL 或网络进程崩溃服务器代码错误查看服务器日志手动诊断命令/doctor输出示例系统诊断报告 Claude Code: v2.5.0 ✓ Node.js: v20.0.0 ✓ MCP 服务器状态 • github: ✓ 已连接 (12 tools) • sqlite: ✗ 连接失败 - Database file not found • puppeteer: ✓ 已连接 (8 tools) 建议 1. 检查 sqlite 数据库路径是否正确 2. 确保 .claude/mcp.json 格式正确/doctor报告的价值在于它一次性给出运行时版本、每个服务器的连接状态与可用工具数量并把最常见的两类故障路径错误、格式错误直接翻译成可执行的修复建议是排查 MCP 问题的第一手段。最佳实践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 // ✗ 不好 - 硬编码密钥 } }注意 JSON 标准不允许重复键实际编写时同一变量只保留一行——上面示例意在对比两种写法的差异第一种引用环境变量安全第二种硬编码明文 Token泄露风险极高。3. 版本锁定为什么需要锁定版本默认情况下npx -y会总是使用最新版本的 MCP 服务器。这可能导致问题新版本可能引入不兼容的更改或者某个服务器突然被下架/改名。通过在包名后添加版本号可以确保始终使用经过验证的特定版本避免因自动更新导致的意外问题{ command: npx, args: [-y, modelcontextprotocol/server-github1.2.3] // 固定版本 }4. 文档化你的 MCP 配置让团队成员快速理解 MCP 配置当项目中有多个 MCP 服务器时新成员可能不清楚每个服务器的用途和配置要求。在.claude/目录下创建一个README.md文件说明每个服务器的用途、所需的配置项以及获取方式可以大大降低团队的沟通成本。在项目中创建.claude/README.md# MCP 配置说明 本项目使用的 MCP 服务器 ## github 用于自动化 GitHub 操作需要配置 GITHUB_TOKEN。 ## sqlite 连接到 ./data/app.db用于查询和修改数据。 ## puppeteer 用于 E2E 测试。Claude Code vs Claude Desktop特性Claude CodeClaude Desktop配置文件~/.claude.json或.claude/mcp.jsonclaude_desktop_config.json项目级配置✓ 支持✗ 不支持自然语言管理✓ 支持✗ 需手动编辑诊断工具✓/doctor✗ 无热重载✓ 自动重载✗ 需重启应用适用场景开发工作流、CI/CD日常使用、办公如果你主要做开发工作Claude Code 是更合适的选择项目级配置 自然语言管理 /doctor诊断 配置热重载四个能力组合起来构成了高效的开发期 MCP 管理闭环。常用 MCP 服务器 完整的 MCP 服务器列表与 MCP/A2A 协议原理请参考附录 AI Agent 协议原理MCP 与 A2A。GitHub 服务器功能Issues、PR、仓库管理{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your-token } } } }需要在 GitHub 个人设置页面创建 Personal Access Token并通过环境变量注入而非写死在配置文件里。SQLite 服务器功能查询和管理 SQLite 数据库{ mcpServers: { sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, ./data/database.db] } } }--db-path指定数据库文件路径注意路径是相对于服务器进程的工作目录而言排查「Database file not found」类报错时优先检查这里。文件系统服务器功能访问指定目录的文件{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents] } } }文件系统服务器通过参数限定可访问的根目录是一种最小权限的目录沙箱——只暴露你授权的路径避免 AI 漫游到整个磁盘。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 } } } }在modelcontextprotocol官方命名空间下还提供 PostgreSQL、Fetch网页抓取、Git 操作等服务器覆盖了开发工作流中最常见的工具类型。Skills 与 MCP一个常见的混淆点MCP 常与 Claude Code Skills 混淆但两者解决的是完全不同的问题。仓库配套课程 Claude Code Skills 完全指南 中给出了清晰的对比维度SkillsMCP本质知识与工作流工具与接口提供什么告诉 AI「怎么做」给 AI「能用什么」存储位置skills/目录MCP 服务器配置格式Markdown 文件JSON 配置文件触发方式/skill-name或自动识别通过配置自动加载直观类比如果 Claude 是一名「工人」——MCP 是发给工人的工具扳手、电脑、权限Skills 是给工人的操作手册如何做代码评审、如何提交代码。两者不是竞争而是互补协作链路如下用户任务 - Claude 识别需求 ↓ 加载相关 Skills知道怎么做 ↓ 通过 MCP 调用工具有工具可用 ↓ 完成任务选型建议需要定义工作流用 Skills需要访问外部数据用 MCP两者都需要就组合使用。在 easy-vibe 中继续深入MCP 是 easy-vibe Stage 3「核心技能」模块的一部分围绕它可以继续学习AI Agent 协议原理MCP 与 A2AMCP 的诞生背景、JSON-RPC 2.0 规范、Tools/Resources/Prompts 三类能力以及 MCP 与 A2A 的对比与选型。Claude Code Skills 完全指南理解 Skills 与 MCP 的分工协作用技能包沉淀团队经验。Claude Agent Teams 完全指南Agent Teams 可与 MCP 组合使用——不同成员通过不同 MCP 服务器访问外部资源例如队友 B 通过 GitHub MCP 处理 PR 管理队友 C 通过数据库 MCP 做数据分析。Claude Agent SDK在自有应用中通过 SDK 编程化使用 Agent 能力MCP 服务器可作为其中一环被编排。仓库自带的 config/mcporter.json一个真实的 MCP 服务器配置样例可作为理解mcpServers结构与启动参数的参考。小结主题一句话要点MCP 是什么「AI 连接工具的 USB-C」由 Anthropic 于 2024 年 11 月发布基于 JSON-RPC 2.0配置文件用户级~/.claude.json全局与项目级.claude/mcp.json推荐传输方式STDIO本地进程、HTTP远程服务、SSE服务器推送使用方式全程自然语言添加、列出、删除、诊断配合/doctor兜底工程化要点项目级配置优先、密钥环境变量化、版本锁定、.claude/README.md文档化MCP 的价值不在于「多一个配置项」而在于它把外部世界的工具统一成了 AI 可理解、可调用的标准接口。掌握本文的配置、调试与工程化方法后你可以让 Claude Code 真正接入 GitHub、数据库、浏览器与各类云服务把 AI 编码工具从「本地编辑器」升级为「连接整个开发环境的超级助手」。赞分享教程文档【免费下载链接】easy-vibe从 0 到 1 学会 vibe coding项目制学习项目地址https://gitcode.com/datawhalechina/easy-vibe点击查看免费下载相关推荐Spec Coding with Claude Code in Easy-Vibe: From Vibe Coding to Specifications as the New Source CodeSpec Coding with Claude Code in Easy Vibe: From Vibe Coding to Specifications as教程文档MCP(model context protocol)动态分析MCP model context protocol 动态分析 Mcp Tools 以下是你所需要生成测试用例的对象的描述也即来自远程MCP服务器的工具描述。人工智能AI 安全治理红蓝对抗AI Agent模型安全Semantica MCP Server 完整指南用 Model Context Protocol 将知识图谱接入 Claude Code、Cursor 与任意 AI 工具Semantica MCP Server 完整指南用 Model Context Protocol 将知识图谱接入 Claude Code、Cursor 与任人工智能大模型知识图谱RAGAI 可解释性后端MCP 服务创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考