企业官网建设流程全解析

• 教程
• 文档

本篇指南以 easy-vibe 仓库 中 docs/en/stage-3/core-skills/mcp/index.md 为核心骨架，结合仓库内的协议原理文档、真实 MCP 配置示例与配套课程进行纵深扩充。你将掌握 MCP 的定位与原理、Claude Code 中两级配置文件的使用、三种传输方式的配置、自然语言管理、调试技巧与工程化最佳实践，并能在自己的项目中按需接入 GitHub、SQLite、文件系统、浏览器自动化等外部能力。

什么是 Claude Code MCP？

Claude Code是 Anthropic 官方推出的 AI 命令行工具，而MCP（Model 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 到底解决哪一层的问题：

• MCP（Model Context Protocol）：由 Anthropic 于 2024 年 11 月 25 日发布，MIT 许可，标准化了「AI 连接外部工具与数据源」的方式，正如 USB-C 统一了各类设备的充电接口——工具开发者只需实现一次 MCP Server，所有兼容 MCP 的 AI 应用（Claude、Cursor、Windsurf 等）即可直接使用。
• A2A（Agent-to-Agent Protocol）：由 Google 于 2025 年 4 月发布，Apache 2.0 许可，解决的是「多个 Agent 之间如何发现、通信与协作」。两者不是竞争关系而是互补关系，选型上：调用第三方工具用 MCP，构建多 Agent 协作系统用 A2A，两者都需要则 MCP + A2A。

MCP 规范基于JSON-RPC 2.0通信格式，提供三类核心能力：

快速开始

步骤 1：了解配置文件位置

Claude Code 的 MCP 配置文件位于：

推荐优先使用项目级配置，让不同项目使用不同的 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.json，mcpServers对象中的每个 key 即一个服务器名，通过command+args启动本地进程，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": [] }

可以从中提取两个要点：

1. 服务器名 → 完整启动命令：配置的实质是把「一个外部能力」映射为「一条可执行的启动命令」。浏览器代理这类服务器往往需要多个启动参数（起始 URL、窗口尺寸、最大步数、日志目录等），它们都会体现在command中。
2. imports字段：部分客户端（如 mcporter）支持通过imports引用其他配置文件或共享服务器集合，便于在多项目间复用 MCP 配置。

传输方式配置

Claude Code 支持三种传输方式：

STDIO（本地进程）

最常用的本地传输方式，通过command+args启动一个子进程，客户端与服务器通过标准输入输出通信：

{ "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。

实战示例

示例 1：GitHub 工作流自动化

你：帮我把当前的修改推送到 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. 返回结果： - 张三 (zhang@example.com) - 2025-02-28 - 李四 (li@example.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 会自动：

1. 检查配置文件格式
2. 验证环境变量
3. 测试服务器连接
4. 提供具体的修复建议

常见问题排查

手动诊断命令

/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 包含数据库 MCP

2. 敏感信息环境变量化

永远不要在配置文件中硬编码密钥！

配置文件可能会被意外提交到 Git 仓库，导致密钥泄露。正确的做法是将敏感信息存储在环境变量中，配置文件只引用变量名。这样即使配置文件被公开，也不会暴露实际的密钥。

{ "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN", // ✓ 好 - 从环境变量读取 "GITHUB_TOKEN": "ghp_abc123" // ✗ 不好 - 硬编码密钥 } }

注意 JSON 标准不允许重复键，实际编写时同一变量只保留一行——上面示例意在对比两种写法的差异：第一种引用环境变量，安全；第二种硬编码明文 Token，泄露风险极高。

3. 版本锁定

为什么需要锁定版本？

默认情况下，npx -y会总是使用最新版本的 MCP 服务器。这可能导致问题：新版本可能引入不兼容的更改，或者某个服务器突然被下架/改名。

通过在包名后添加@版本号，可以确保始终使用经过验证的特定版本，避免因自动更新导致的意外问题：

{ "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github@1.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 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 完全指南 中给出了清晰的对比：

直观类比：如果 Claude 是一名「工人」——MCP 是发给工人的工具（扳手、电脑、权限），Skills 是给工人的操作手册（如何做代码评审、如何提交代码）。

两者不是竞争而是互补，协作链路如下：

用户任务 -> Claude 识别需求 ↓ 加载相关 Skills（知道怎么做） ↓ 通过 MCP 调用工具（有工具可用） ↓ 完成任务

选型建议：需要定义工作流用 Skills；需要访问外部数据用 MCP；两者都需要就组合使用。

在 easy-vibe 中继续深入

MCP 是 easy-vibe Stage 3「核心技能」模块的一部分，围绕它可以继续学习：

• AI Agent 协议原理（MCP 与 A2A）：MCP 的诞生背景、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 可理解、可调用的标准接口。掌握本文的配置、调试与工程化方法后，你可以让 Claude Code 真正接入 GitHub、数据库、浏览器与各类云服务，把 AI 编码工具从「本地编辑器」升级为「连接整个开发环境的超级助手」。

• 教程
• 文档