Easy-Vibe高级开发篇阅读笔记（二）——CC教程之Claude Code MCP 完全指南

码途漫谈2026-05-06 11:15

阅读原文：Claude Code MCP 完全指南

一、本章核心学习目标

  • 理解 MCP（模型上下文协议）的核心定位，搞懂它如何扩展 Claude Code 的能力边界
  • 掌握 MCP 的配置方式，区分用户级和项目级配置的差异
  • 学会用自然语言管理 MCP 服务器，不用手动编辑配置文件
  • 掌握实战场景的用法，比如 GitHub 自动化、数据库查询、浏览器自动化
  • 了解 MCP 的最佳实践，以及常见问题的排查方法

二、什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是让 Claude Code 能够连接外部工具和服务的开放标准协议。

简单来说，它让 Claude Code 从一个「只能读写本地文件」的 AI 助手，变成一个「能访问 GitHub、数据库、API、云服务」的超级助手！

2.1 能力对比：加不加 MCP 的差距

能力 没有 MCP 的 Claude Code 有了 MCP 的 Claude Code
文件操作 ✓ 读取本地文件 ✓ 所有原有功能
代码编辑 ✓ 编辑代码 ✓ 编辑代码
命令执行 ✓ 运行命令 ✓ 运行命令
外部服务 ✗ 无法访问 GitHub ✓ 查看 / 创建 GitHub Issues 和 PR
数据访问 ✗ 无法访问数据库 ✓ 查询 SQLite、PostgreSQL 数据库
工具集成 ✗ 无法调用外部 API ✓ 访问 Notion、Slack 等外部服务
自动化 ✗ 有限的本地操作 ✓ 浏览器自动化、网络搜索、实时数据获取

三、5 分钟快速上手

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

MCP 支持两种级别的配置，满足不同场景：

级别 配置文件路径 作用范围
用户级 ~/.claude.json 所有项目全局生效
项目级 .claude/mcp.json 当前项目专属（推荐）

推荐优先使用项目级配置，让不同项目使用不同的 MCP 服务，团队协作也能共享配置。

3.2 步骤 2：用自然语言添加 MCP 服务器

你完全不需要手动编辑 JSON 配置文件，直接用自然语言告诉 Claude Code 你想要什么：

Plain 复制代码 
你：帮我添加 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.3 步骤 3：验证配置

配置完成后，直接询问 Claude Code 来验证：

Plain 复制代码 
你：现在有哪些可用的 MCP 服务器？
Claude：当前已配置的 MCP 服务器：
• github - GitHub 集成
• sqlite - SQLite 数据库
• filesystem - 文件系统访问

或者使用内置的诊断命令：

Plain 复制代码 
/doctor

3.4 步骤 4：开始使用

配置成功后，直接用自然语言调用 MCP 功能即可，Claude 会自动帮你调用对应的工具。

四、配置方式详解

4.1 配置级别对比

用户级配置（全局）

编辑 ~/.claude.json，对所有项目生效，适合个人通用的工具：

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，只对当前项目生效，团队可以共享：

json 复制代码 
{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "--db-path", "./data/app.db"]
    }
  }
}

项目级配置的优势：

  • 团队成员可以共享配置，提交到 Git 即可
  • 不同项目使用不同的 MCP 服务，互不干扰
  • 配置更灵活，不会污染全局设置

4.2 三种传输方式

Claude Code 支持三种传输方式，适配不同的部署场景：

传输方式 适用场景 说明
STDIO 本地进程 运行在你本地机器上的服务，比如 npx 启动的工具
HTTP 远程服务 部署在公网的远程 MCP 服务，通过 HTTP 调用
SSE 流式服务 支持服务器推送事件的流式服务，适合长连接场景

五、实战场景示例

5.1 示例 1：GitHub 工作流自动化

Plain 复制代码 
你：帮我把当前的修改推送到 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

5.2 示例 2：数据库查询

Plain 复制代码 
你：查询数据库中最近注册的 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
...

5.3 示例 3：网页截图分析

Plain 复制代码 
你：打开 https://example.com 并截图，分析一下页面设计
Claude：
1. 启动浏览器...
2. 导航到 https://example.com...
3. 截取屏幕...
4. 页面设计分析：
- 布局采用居中设计，最大宽度 1200px
- 主色调为蓝色 (#3b82f6)
- 导航栏固定在顶部
...

5.4 示例 4：与 Notion 集成

Plain 复制代码 
你：把我刚才的笔记保存到 Notion
Claude：
1. 使用 Notion MCP 服务器...
2. 创建新页面...
3. 已保存：https://notion.so/page/xxx

六、调试与问题排查

6.1 自然语言诊断

遇到问题时，不用自己查日志，直接用自然语言告诉 Claude Code：

Plain 复制代码 
你：我的 MCP 服务器连接不上了，帮我检查一下
你：GitHub MCP 工具调用失败，是什么原因？
你：为什么 sqlite 服务器一直显示连接中？

Claude Code 会自动：

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

6.2 常见问题排查表

问题 可能原因 解决方案
服务器未连接 配置文件格式错误 检查 JSON 语法
工具无法调用 权限不足 检查环境变量和 Token
连接超时 网络问题 检查 URL 或网络连通性
进程崩溃 服务器代码错误 查看服务器日志

6.3 手动诊断命令

使用 /doctor 命令可以生成完整的系统诊断报告，查看每个 MCP 服务器的连接状态。

七、最佳实践

7.1 项目级配置优先

不同的项目往往需要不同的 MCP 服务。前端项目可能需要浏览器测试工具，后端项目则需要数据库连接。使用项目级配置可以让每个项目拥有自己专属的 MCP 服务器集合，避免全局配置的混乱。

更重要的是，项目级配置可以提交到 Git 仓库，团队成员克隆项目后就能直接使用相同的 MCP 服务，无需重复配置。

7.2 敏感信息环境变量化

永远不要在配置文件中硬编码密钥！配置文件可能会被意外提交到 Git 仓库，导致密钥泄露。

正确的做法是将敏感信息存储在环境变量中，配置文件只引用变量名：

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

7.3 版本锁定

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

通过在包名后添加 @版本号，可以确保始终使用经过验证的特定版本：

json 复制代码 
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-github@1.2.3"]  // 固定版本
}

7.4 文档化你的 MCP 配置

当项目中有多个 MCP 服务器时，新成员可能不清楚每个服务器的用途。在 .claude/ 目录下创建一个 README.md 文件，说明每个服务器的用途、所需的配置项，可以大大降低团队的沟通成本。

八、Claude Code vs Claude Desktop

特性 Claude Code Claude Desktop
配置文件 ~/.claude.json 或 .claude/mcp.json claude_desktop_config.json
项目级配置 ✓ 支持 ✗ 不支持
自然语言管理 ✓ 支持 ✗ 需手动编辑
诊断工具 ✓ /doctor 命令 ✗ 无
热重载 ✓ 自动重载 ✗ 需重启应用
适用场景 开发工作流、CI/CD 日常使用、办公

九、常用 MCP 服务器速查

服务器 功能 适用场景
GitHub Issues、PR、仓库管理 代码协作、自动化
SQLite 本地数据库查询 后端项目、数据处理
文件系统 指定目录文件访问 安全的文件操作
Puppeteer 浏览器自动化、截图 E2E 测试、网页分析
Brave Search 网络搜索 获取最新信息
PostgreSQL 远程数据库连接 企业级后端项目

本章总结

MCP 是 AI 编码时代的能力扩展协议，它让 Claude Code 从一个本地的代码助手，变成了能连接整个数字世界的超级助手：

  1. 核心价值：通过标准化的协议，让 AI 能够安全地访问外部工具和服务，打破本地文件的限制

  2. 零学习成本：你完全不用手动编辑复杂的配置，用自然语言就能完成所有配置和调用

  3. 灵活配置：支持全局和项目级两种配置，适配个人和团队的不同需求

  4. 无限扩展：从 GitHub 到数据库，从浏览器到外部 API，几乎可以集成任何工具

掌握了 MCP，你就能把 Claude Code 的能力提升一个档次，真正实现用自然语言完成从开发到部署、从本地到云端的全流程自动化。

相关推荐
游乐码1 小时前
c#反射笔记二
笔记·c#
唐叔在学习2 小时前
TodoList：我的待办助手
python·程序员·ai编程·待办应用
青山师2 小时前
【大模型提示词工程深度解析：从原理到工业级实践、实践案例】
大模型·prompt·aigc·ai编程·llama·claude·agi
xmdy58662 小时前
Flutter+开源鸿蒙实战｜校园易生活Day1 项目初始化搭建+开发环境校验+工程目录规范+第三方库集成+多端屏幕适配+全局底部导航
flutter·开源·harmonyos
yjfkpyu2 小时前
让 AI 不再按过期文档写代码：AgentLockDoc 开源了
人工智能·ai编程
lazy熊2 小时前
初学者如何快速入门学会 Claude Code？
人工智能·gpt·ai编程
流年似水～2 小时前
Copilot已死，Agent当立：2026年，程序员从“码字工“到“AI指挥官“的生存指南
人工智能·程序人生·语言模型·ai编程
Peter·Pan爱编程2 小时前
第六篇：VS Code + Continue 插件：开源爱好者的低成本高自由度方案
ide·开源·ai编程
Peter·Pan爱编程2 小时前
第五篇：Windsurf（Codeium）解析 —— Cascade 与 “Flow” 状态的工作流对比
人工智能·ai编程
热门推荐
01要裂开了！ChatGPT要手机号验证了？注册Codex要求验证电话号码怎么办？2026年登陆Codex要手机号验证的解决办法02GitHub 镜像站点03Codex 接入 DeepSeek API 完整配置文档04零基础教你claude code 接入 deepseek V405【AI】2026 年具身智能模型和世界模型总结06Linux 核弹级高危漏洞 CVE-2026-31431 完整修复指南07CVE-2026-31431 (Copy Fail) 漏洞复现与验证记录08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09几个好用的ip纯净度检测网站102026年AI前瞻：量子AI、具身智能与科学发现的新纪元