easy-vibe 实战Claude Code MCP 完全指南——从协议原理到自然语言驱动外部工具【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibeMCPModel Context Protocol是让 AI 编程助手突破「本地文件读写」边界的核心协议本指南以 easy-vibe 进阶课程 Stage-3 核心技能 中的 MCP 专题为主体系统讲解 Claude Code 中 MCP 的配置、使用、调试与最佳实践。读完本文你将掌握用户级/项目级两种配置方式、STDIO/HTTP/SSE 三种传输模式、自然语言管理 MCP 服务器以及一套可直接复用的 GitHub、SQLite、文件系统、浏览器自动化等常见服务器配置模板。什么是 Claude Code MCPClaude Code是 Anthropic 官方推出的 AI 命令行工具而MCPModel Context Protocol则是让 Claude Code 能够连接外部工具和服务的标准协议。简单来说MCP 让 Claude Code 从一个「只能读写本地文件」的 AI 助手变成一个「能访问 GitHub、数据库、API、云服务」的超级助手。结合仓库附录 docs/de-de/appendix/8-artificial-intelligence/ai-protocols.md 中对协议体系的梳理可以更完整地理解 MCP 的定位通信层级协议解决的问题类比第 1 层Function CallAI 如何调用本地函数大脑下达指令第 2 层MCPAI 如何连接外部工具与数据源USB-C 接口第 3 层A2AAgent 之间如何协作通信企业 IM 工具MCP 由 Anthropic 于 2024 年 11 月 25 日发布采用 MIT 开源许可其核心思想是AI 应当能动态获取所需的上下文信息而不是把全部信息硬塞进 Prompt。它定义了三大核心能力能力英文作用示例工具ToolsAI 可以调用的函数查天气、发邮件资源ResourcesAI 可以读取的数据文件内容、数据库记录提示词Prompts预定义的提示词模板代码评审模板、写作模板正如附录中「USB-C 接口」的类比过去每个设备有自己的充电口而 MCP 统一了 AI 与所有工具的连接方式。工具开发者只需实现一次 MCP 服务器所有支持 MCP 的 AI 应用Claude Desktop、Cursor、Windsurf、Zed 等都能直接使用。为什么需要在 Claude Code 中使用 MCP没有 MCP 的 Claude Code你能做的 ✓ 读取本地文件 ✓ 编辑代码 ✓ 运行命令 ✓ 使用 Bash 工具 你不能做的 ✗ 查看你的 GitHub Issues ✗ 访问云数据库 ✗ 调用外部 API ✗ 获取实时天气有了 MCP 的 Claude Code你能做的 ✓ 所有原来的功能 ✓ 查看/创建 GitHub Issues 和 PR ✓ 查询 SQLite、PostgreSQL 数据库 ✓ 访问 Notion、Slack 等外部服务 ✓ 获取实时天气、地图数据 ✓ 浏览器自动化 ✓ ...以及更多从本质上看MCP 解决的正是 AI Agent 应用落地时最核心的「能力获取」问题让大模型能够安全、标准地调用外部世界。快速开始步骤 1了解配置文件位置Claude Code 的 MCP 配置文件位于级别配置文件路径作用范围用户级~/.claude.json所有项目项目级.claude/mcp.json当前项目推荐优先使用项目级配置让不同项目使用不同的 MCP 服务。项目级配置可以提交到 Git 仓库随项目分发团队成员克隆后即可直接使用同一套 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 支持三种传输方式STDIO本地进程本地 MCP 服务器以子进程方式启动通过标准输入/输出与 Claude Code 通信。适合文件系统、数据库等需要直接访问本机资源的场景{ mcpServers: { local-tool: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /path] } } }HTTP远程服务通过 HTTP 协议连接远程 MCP 服务可用headers携带认证信息如Authorization: Bearer token{ 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 } } }真实仓库中的配置形态在 easy-vibe 仓库中config/mcporter.json 提供了一个真实可对照的 MCP 服务器配置示例使用 mcporter 工具加载{ 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: [] }这个配置直观地展示了 MCP 配置的本质每个服务器条目就是一个「服务器名称 → 启动命令及参数」的 JSON 映射。浏览器自动化 Agent 通过--start_url、--window_width、--max_steps等命令行参数完成启动行为定制这与npx -y modelcontextprotocol/server-xxx的标准写法在结构上完全一致——都遵循commandargs的启动模型。实战示例示例 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 格式正确最佳实践1. 项目级配置优先为什么推荐项目级配置不同的项目往往需要不同的 MCP 服务。例如前端项目可能需要浏览器测试工具而后端项目则需要数据库连接。使用项目级配置可以让每个项目拥有自己专属的 MCP 服务器集合避免全局配置的混乱。更重要的是项目级配置可以提交到 Git 仓库团队成员克隆项目后就能直接使用相同的 MCP 服务无需重复配置项目 A前端项目→ .claude/mcp.json 包含浏览器测试 MCP 项目 B后端项目→ .claude/mcp.json 包含数据库 MCP2. 敏感信息环境变量化永远不要在配置文件中硬编码密钥配置文件可能会被意外提交到 Git 仓库导致密钥泄露。正确的做法是将敏感信息存储在环境变量中配置文件只引用变量名。这样即使配置文件被公开也不会暴露实际的密钥。{ env: { GITHUB_TOKEN: $GITHUB_TOKEN } }上面的写法是正确的$GITHUB_TOKEN从当前环境变量中读取配置文件本身不包含任何明文密钥。{ env: { GITHUB_TOKEN: ghp_abc123 } }这种写法是危险的密钥被硬编码进配置文件一旦文件被提交到公开仓库即造成泄露。始终选择前者拒绝后者。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日常使用、办公任务如果你主要在开发流程中使用 AI 编程助手Claude Code 是更合适的选择如果只是日常办公辅助Claude Desktop 则更轻量。常见 MCP 服务器提示完整的 MCP 服务器目录、协议原理MCP 与 A2A 的关系、JSON-RPC 2.0 数据格式可查阅仓库附录 docs/de-de/appendix/8-artificial-intelligence/ai-protocols.md。GitHub 服务器功能Issues、PR、仓库管理{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: your-token } } } }需要先在 GitHub 账户设置中生成 Personal Access Token填入GITHUB_PERSONAL_ACCESS_TOKEN环境变量。SQLite 服务器功能查询和管理 SQLite 数据库{ mcpServers: { sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, ./data/database.db] } } }--db-path参数指定数据库文件路径可写相对路径或绝对路径。文件系统服务器功能访问指定目录下的文件{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents] } } }注意该服务器只允许访问args中显式列出的目录这是 MCP 的权限边界设计——AI 只能触及你授权的范围。Puppeteer 浏览器自动化功能浏览器控制、截图、自动化测试{ mcpServers: { puppeteer: { command: npx, args: [-y, modelcontextprotocol/server-puppeteer] } } }适用于网页截图分析、E2E 测试、页面交互验证等场景。Brave Search 服务器功能网络搜索{ mcpServers: { brave-search: { command: npx, args: [-y, modelcontextprotocol/server-brave-search], env: { BRAVE_API_KEY: your-brave-api-key } } } }为 Claude Code 补上实时信息检索能力BRAVE_API_KEY需在 Brave 开发者平台申请同样建议通过环境变量注入。小结MCP 是 AI-native 开发者的核心基础设施之一。掌握本指南后你已经具备理解能力知道 MCP 是什么、解决什么问题、在协议体系中的位置可对照附录 ai-protocols.md 深入学习 MCP 与 A2A 的分工配置能力熟练使用用户级/项目级配置按需选择 STDIO、HTTP、SSE 三种传输方式并能在 config/mcporter.json 这类真实配置文件中读懂服务器启动模型使用与调试能力用自然语言完成服务器的增删改查借助/doctor和常见问题对照表快速排障工程化能力落实项目级配置优先、密钥环境变量化、版本钉扎、配置文档化四大最佳实践。把这套能力带入你的日常开发工作流Claude Code 将从「本地代码编辑器」升级为真正能触达 GitHub、数据库与外部世界的超级助手。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考