Claude Code MCP 集成完整指南:从协议原理到自定义服务器开发实战
Claude Code MCP 集成完整指南:从协议原理到自定义服务器开发实战
本篇技术指南以 Claude Code 官方编程 CLI 的 MCP(Model Context Protocol)集成为主线,系统讲解 MCP 协议的价值、Filesystem/GitHub/数据库等 10+ 核心服务器的配置方法、Local/Project/User 三作用域配置体系、STDIO/HTTP 传输与 JSON-RPC 通信机制,以及从零开发并发布自定义 MCP 服务器的完整流程。读完本篇,你将能独立完成 MCP 服务器配置、问题排查与自定义开发,并掌握 API 密钥等敏感信息的安全管理方法。
适用版本:MCP 规范 2026-07-28 / Claude Code v2.1.270(本仓库 README 记录教程基线为 Claude Code v2.1.270,核查日 2026-09-14)。预计学时 4-6 小时,难度入门级(有 Claude Code 基础即可)。
学习路径导航(先看这里)
这是一篇长教程,不必全看。请根据自己的目标选择路径:
- 路径 A:快速上手(60 分钟)——适合急着配一个看效果的用户。只看术语表(5 分钟)、MCP 简介(10 分钟)、5 分钟快速开始(15 分钟)、第三部分 3.1-3.3 的 GitHub 和数据库 MCP 配置(30 分钟)。完成后可配置 2-3 个 MCP 服务器,让 Claude Code 调用外部工具。
- 路径 B:完整学习(4-6 小时)——适合想深入理解并掌握开发的用户。建议分段:第 1 天学第 1-3 部分(理解+配置),第 2 天学第 4-5 部分(原理+开发),第 3 天学第 6-7 部分(故障排查+FAQ)。
- 路径 C:问题排查(10 分钟)——直接跳到第六部分按错误类型查找,或第七部分 FAQ,用
Ctrl + F搜索错误信息关键词。 - 路径 D:专项学习(30-60 分钟/主题)——自定义开发看第五部分(1.5 小时)、三作用域配置看 3.4 节(30 分钟)、MCP 工作原理看第四部分(45 分钟)、安全最佳实践看 3.5 节(20 分钟)。
本教程属于本仓库 Claude Code 系列教程 的第四篇,前置要求是已完成 Claude Code 安装 和 基础使用。
术语表(小白必读)
| 术语 | 英文全称 | 通俗解释 | 生活类比 |
|---|---|---|---|
| JSON | JavaScript Object Notation | 通用的数据格式,MCP 配置文件就是 JSON 格式 | 标准化的表格模板 |
~(波浪号) |
Home Directory | 用户的"家目录",macOS 是 /Users/用户名,Linux 是 /home/用户名,Windows 对应 C:\Users\用户名 |
"我的文档"的上级目录 |
| MCP | Model Context Protocol | AI 工具的"USB 接口标准",让 AI 连接各种外部工具 | USB 接口标准 |
| MCP Server | - | 符合 MCP 标准的"工具包",提供特定功能 | USB 设备(U盘、键盘) |
| MCP Client | - | 连接和使用 MCP Server 的程序 | 电脑的 USB 接口 |
| MCP Host | - | 运行 MCP Client 的宿主程序(如 Claude Code) | 电脑主机 |
| Tools | - | MCP Server 提供的"工具函数",AI 可以调用 | 工具箱里的锤子、螺丝刀 |
| Resources | - | MCP Server 提供的"数据资源",AI 可以读取 | 参考书、资料库 |
| Prompts | - | MCP Server 提供的"预设模板",标准化交互 | 填空表格、问卷模板 |
| STDIO | Standard Input/Output | "直连线"传输方式,本地进程通信 | USB 直连线 |
| HTTP | Hypertext Transfer Protocol | "网线"传输方式,支持远程通信 | 网线/WiFi |
| JSON-RPC | JSON Remote Procedure Call | MCP 的通信协议,用 JSON 格式传递消息 | 对讲机的通话格式 |
| 作用域 | Scope | 配置的生效范围(Local/Project/User) | 房间/楼层/整栋楼 |
| npx | Node Package eXecute | 临时运行 npm 包的工具 | 租借工具(用完还) |
| 环境变量 | Environment Variable | 系统级配置,存储敏感信息 | 保险柜里的密码本 |
第一部分:MCP 简介
1.1 MCP 是什么
一句话理解:MCP(Model Context Protocol)是 AI 工具的"USB 接口标准",让任何 AI 应用都能即插即用地连接各种外部服务。
没有 MCP 之前(混乱的世界):每个 AI 工具都要单独对接外部服务,重复造轮子——Claude Desktop、VS Code + AI、Cursor 各自都要写一套自定义代码对接 GitHub、数据库、文件系统,且互不兼容。
有了 MCP 之后(标准化的世界):统一接口,一次开发到处使用——Claude Desktop、VS Code + AI、Cursor 等任何 AI 工具通过 MCP 协议统一连接 GitHub MCP Server、数据库 MCP Server、文件系统 MCP Server。
生活类比:没有 USB 标准时,每个品牌的键盘、鼠标都需要专用接口,换电脑就要换设备;有 USB 标准后,任何 USB 键盘都能插任何电脑,即插即用。
MCP 的核心价值:
| 对比维度 | 传统集成方式 | MCP 方式 |
|---|---|---|
| 开发成本 | 每个工具单独对接,重复开发 | 一次开发,多处复用 |
| 兼容性 | 各平台接口不兼容 | 开放标准,跨平台通用 |
| 安全性 | 安全边界模糊 | 明确的权限控制和隔离 |
| 维护成本 | 高(每个集成都要维护) | 低(社区共建,生态复用) |
| 学习成本 | 高(每个工具 API 不同) | 低(统一协议,学一次用到处) |
1.2 MCP 的发展历程
| 时间 | 里程碑事件 | 意义 |
|---|---|---|
| 2024年11月 | Anthropic 发布 MCP 1.0 规范 | 开创 AI 工具标准化先河 |
| 2025年3月 | 发布 2025-03-26 版本 | 引入 Streamable HTTP 传输,废弃 SSE |
| 2025年6月 | 发布 2025-06-18 版本 | 进一步完善协议规范 |
| 2025年11月 | 发布 2025-11-25 版本 | 沿用初始化握手协商;2026-07-28 版仍提供与这一代的兼容路径 |
| 2025年12月9日 | MCP 捐赠给 Linux 基金会 AAIF | 成为行业标准,OpenAI/Google/Microsoft 等巨头支持 |
| 2026年7月28日 | 发布 2026-07-28 版本 | 当前协议版本(核查日:2026-09-14) |
重要事件:2025 年 12 月 9 日,Anthropic 将 MCP 捐赠给 Linux 基金会下的 Agentic AI Foundation(AAIF)。这意味着 MCP 从"Anthropic 的协议"变成了"行业标准",OpenAI、Google DeepMind、Microsoft 等主流 AI 厂商都已表态支持。
1.3 MCP 能做什么(5 个实际案例)
案例1:文件系统操作
你:帮我在data目录下创建一个config.json文件
Claude Code(通过Filesystem MCP):
1. [调用] list_directory("./data") - 检查目录存在
2. [调用] write_file("./data/config.json", "{}") - 创建文件
3. [返回] 文件创建成功!路径:./data/config.json
案例2:GitHub 仓库管理
你:帮我创建一个Issue,标题是"修复登录bug"
Claude Code(通过GitHub MCP):
1. [调用] create_issue(owner, repo, title, body) - 创建Issue
2. [返回] Issue创建成功!链接:https://github.com/xxx/xxx/issues/123
案例3:数据库查询
你:查一下用户表有多少条记录
Claude Code(通过SQLite MCP):
1. [调用] read_query("SELECT COUNT(*) FROM users")
2. [返回] 用户表共有 1,234 条记录
案例4:获取最新技术文档
你:帮我查一下Next.js 15的App Router怎么用
Claude Code(通过Context7 MCP):
1. [调用] resolve_library_id("next.js")
2. [调用] get_library_docs("/vercel/next.js", "app router")
3. [返回] 这是Next.js 15 App Router的最新文档...
案例5:网页搜索
你:搜一下2025年最新的AI编程工具
Claude Code(通过Brave Search MCP):
1. [调用] brave_web_search("2025 AI编程工具", count=5)
2. [返回] 搜索结果:1. xxx 2. xxx 3. xxx ...
第二部分:5分钟快速开始(立即见效)
本部分用最快速度配置第一个 MCP 服务器(Filesystem),预计 5-10 分钟。
为什么选 Filesystem? 最简单(不需要任何 API Key)、最常用(文件操作是开发基础)、效果直观(立即看到结果)。
2.1 配置第一个 MCP 服务器(Filesystem)
步骤1:创建配置文件——在项目根目录创建 .mcp.json 文件。
你有两种选择:
选择 A:在 Claude Code 对话框里说人话(推荐新手)
帮我创建项目MCP配置文件 .mcp.json,配置一个filesystem服务器,允许访问当前目录
(换行用 Shift + Enter,最后按 Enter 发送,Claude Code 会自动创建正确格式的配置文件)
选择 B:在终端里用命令行
Windows 系统(PowerShell 终端):
# 进入你的项目目录
cd C:\你的项目路径
# 创建.mcp.json文件(PowerShell 7推荐)
@'
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"env": {}
}
}
}
'@ | Out-File -FilePath ".mcp.json" -Encoding utf8
macOS/Linux 系统(终端):
# 进入你的项目目录
cd ~/你的项目路径
# 创建.mcp.json文件
cat > .mcp.json << 'EOF'
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"env": {}
}
}
}
EOF
手动创建(适合所有平台):在项目根目录新建文件命名为 .mcp.json(注意开头有个点),复制粘贴上面的 JSON 内容。
配置字段说明:
| 字段 | 必需 | 说明 | 示例 |
|---|---|---|---|
command |
✅ | 启动命令 | "npx", "node", "python" |
args |
✅ | 命令参数数组 | ["-y", "@modelcontextprotocol/server-xxx"] |
env |
❌ | 环境变量对象 | {"API_KEY": "xxx"} |
timeout |
❌ | 超时时间(毫秒) | 60000 |
关于
"filesystem"配置:服务器名称可自定义;"command": "npx"表示用 npx 运行;"-y"表示自动同意安装;"@modelcontextprotocol/server-filesystem"是官方 Filesystem MCP 包名;"."是允许访问的目录(当前目录)。补充说明(仓库佐证):本仓库 10-综合实战完整指南 明确指出,
.mcp.json中 MCP 服务器的标准字段只有command、args和env,不存在trust、network、limits之类的虚构字段——配置时应避免写入非标准字段。
步骤2:验证配置文件
# 查看配置文件内容
cat .mcp.json
# 验证JSON格式是否正确(需要安装jq,可选)
cat .mcp.json | jq .
# 如果格式正确,会输出格式化的JSON;如果格式错误,会报错
步骤3:启动 Claude Code——重新启动,让它读取新配置:
claude
启动时会看到类似输出:
Claude Code v2.1.92
Working directory: /你的项目路径
MCP servers connected:
✓ filesystem (3 tools available)
You: █
✅ 关键确认:看到
✓ filesystem说明 MCP 服务器连接成功!如果看不到 MCP 服务器列表:确认
.mcp.json在项目根目录、文件名正确(开头有点、后缀是 json)、JSON 格式正确,然后退出 Claude Code 重新启动。
步骤4:测试 MCP 功能
测试命令:你:列出当前目录下的所有文件
预期响应:
Claude Code:
[调用 filesystem.list_directory]
路径: .
目录内容:
- .mcp.json (配置文件)
- package.json
- src/
- node_modules/
...
更多测试:
你:读取package.json文件内容
你:在src目录下创建一个test.txt文件,内容是"Hello MCP"
你:搜索所有.js文件
2.2 验证 MCP 工作正常
完整验证清单:
- [ ]
.mcp.json文件存在且格式正确 - [ ] Claude Code 启动时显示 MCP 服务器已连接
- [ ] 能成功执行
list_directory工具 - [ ] 能成功执行
read_file工具 - [ ] 能成功执行
write_file工具(会请求确认)
2.3 第一个 MCP 工具调用
你刚才完成了:创建了 MCP 配置文件、连接了 Filesystem MCP 服务器、通过 Claude Code 调用了 MCP 工具、验证了 MCP 正常工作。接下来可以继续学习更多 MCP 服务器(第三部分)、了解 MCP 工作原理(第四部分)或开发自己的 MCP 服务器(第五部分)。
第三部分:常用 MCP 服务器配置(实战为主)
3.1 配置方式详解
方式1:JSON 配置文件(推荐)——创建 .mcp.json 文件:
{
"mcpServers": {
"服务器名称1": {
"command": "启动命令",
"args": ["参数1", "参数2"],
"env": {
"环境变量名": "值"
}
},
"服务器名称2": {
...
}
}
}
方式2:CLI 命令(快速添加)
# 添加MCP服务器
claude mcp add <服务器名> <命令> [参数...]
# 示例:添加filesystem服务器
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem ./data
# 列出所有MCP服务器
claude mcp list
# 查看特定服务器详情
claude mcp get filesystem
# 删除服务器
claude mcp remove filesystem
CLI 添加的作用域:
# 默认添加到local作用域
claude mcp add my-server npx -y xxx
# 指定添加到project作用域
claude mcp add --scope project my-server npx -y xxx
# 指定添加到user作用域(全局)
claude mcp add --scope user my-server npx -y xxx
方式对比:
| 对比维度 | JSON 配置文件 | CLI 命令 |
|---|---|---|
| 适合场景 | 团队项目、版本控制 | 快速测试、个人配置 |
| 可读性 | 高(结构清晰) | 中 |
| 批量配置 | 方便(一个文件) | 不便(逐个添加) |
| 版本控制 | 支持 | 不支持 |
| 推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ |
仓库佐证:在 Claude Code 交互界面中,也可通过
/mcp命令管理 MCP 连接,详见本仓库 03-Commands 系统完整指南 的命令速览表。
3.2 GitHub MCP 服务器
功能:完整的 GitHub 仓库管理能力,包括创建仓库、管理 Issue、PR 等。
步骤1:获取 GitHub Token
- 登录 GitHub.com
- 点击右上角头像 → Settings
- 左侧菜单最下方 → Developer settings
- Personal access tokens → Tokens (classic)
- Generate new token (classic)
- 勾选权限:✅
repo(完整仓库访问)、✅workflow(如需管理 Actions) - 点击 Generate token
- 立即复制保存 Token(只显示一次!)
⚠️ 安全提醒:Token 只显示一次,关闭页面就看不到了!
步骤2:配置环境变量
Windows(PowerShell 7):
# 永久设置环境变量
[System.Environment]::SetEnvironmentVariable('GITHUB_PERSONAL_ACCESS_TOKEN', 'ghp_你的Token', 'User')
# 验证
$env:GITHUB_PERSONAL_ACCESS_TOKEN
macOS/Linux:
# 添加到shell配置文件
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_你的Token"' >> ~/.zshrc
source ~/.zshrc
# 验证
echo $GITHUB_PERSONAL_ACCESS_TOKEN
步骤3:添加 MCP 配置——在 .mcp.json 中添加:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
}
}
}
💡 说明:
${GITHUB_PERSONAL_ACCESS_TOKEN}会自动读取环境变量,不用把 Token 直接写在配置文件里。
步骤4:验证配置
# 重启Claude Code
claude
# 测试
你:查看我的GitHub仓库列表
你:创建一个Issue到xxx仓库,标题是"测试MCP"
提供的工具:
| 工具名 | 功能 | 参数 |
|---|---|---|
create_repository |
创建仓库 | name, description, private |
get_file_contents |
获取文件内容 | owner, repo, path |
push_files |
推送文件 | owner, repo, branch, files |
create_issue |
创建 Issue | owner, repo, title, body |
create_pull_request |
创建 PR | owner, repo, title, head, base |
fork_repository |
Fork 仓库 | owner, repo |
create_branch |
创建分支 | owner, repo, branch |
search_repositories |
搜索仓库 | query |
search_code |
搜索代码 | query |
search_issues |
搜索 Issues | query |
仓库佐证:Claude Code 中 MCP 工具以
mcp__服务器名__工具名的命名规则暴露,例如mcp__github__create_issue;这一命名规则同样可用于权限配置,见 03-Commands 系统完整指南 与 10-综合实战完整指南。
3.3 数据库 MCP 服务器
SQLite(本地数据库)
功能:本地 SQLite 数据库的完整访问,无需安装数据库软件。
配置方法:
{
"mcpServers": {
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./data/app.db"],
"env": {}
}
}
}
💡 说明:最后的参数是数据库文件路径,不存在会自动创建。SQLite MCP 是 Python 包,需要用
uvx而非npx。
提供的工具:
| 工具名 | 功能 | 参数 |
|---|---|---|
read_query |
执行 SELECT 查询 | query |
write_query |
执行 INSERT/UPDATE/DELETE | query |
create_table |
创建表 | query |
list_tables |
列出所有表 | - |
describe_table |
获取表结构 | table_name |
append_insight |
添加分析洞察 | insight |
使用示例:
你:创建一个users表,包含id、name、email字段
你:插入一条记录:张三,zhangsan@example.com
你:查询所有用户
PostgreSQL(生产数据库)
功能:连接 PostgreSQL 数据库,支持查询和结构检查。
配置方法:
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:password@localhost:5432/database"]
}
}
}
⚠️ 安全建议:使用只读数据库用户;不要在配置文件中硬编码密码;连接字符串通过
args传递,可使用环境变量替代硬编码:"postgresql://${PGUSER}:${PGPASSWORD}@localhost:5432/database"。
提供的工具:query(执行 SQL 查询,参数 sql)。表结构信息(schemas、tables、columns)通过 MCP 的 Resources 机制自动暴露,无需手动调用工具即可获取。
3.4 三作用域配置体系
理解配置的作用域和优先级,是正确使用 MCP 的关键。
三大作用域:
| 作用域 | 存储位置 | 优先级 | 适用场景 |
|---|---|---|---|
| Local | ~/.claude.json 项目条目 |
最高 | 个人私有配置、含 API Key |
| Project | 项目根目录 .mcp.json |
中等 | 团队共享、版本控制 |
| User | ~/.claude.json 全局部分 |
最低 | 个人常用工具 |
💡 Windows 用户路径说明:
~/.claude.json在 Windows 上对应C:\Users\你的用户名\.claude.json,可在资源管理器地址栏输入%USERPROFILE%快速跳转。作用域名称说明:
- Local(本地):虽然叫"本地",但实际是"项目级个人私有配置"——只对当前项目生效,且不提交到 Git
- Project(项目):项目级共享配置,整个团队都能看到
- User(用户):全局个人配置,所有项目都能用
优先级合并规则:
Local > Project > User
示例场景——假设三个作用域都配置了 github 服务器:
User作用域:GITHUB_PERSONAL_ACCESS_TOKEN = "user-token"
Project作用域:GITHUB_PERSONAL_ACCESS_TOKEN = "${GITHUB_PERSONAL_ACCESS_TOKEN}"
Local作用域:GITHUB_PERSONAL_ACCESS_TOKEN = "local-override-token"
最终生效:Local作用域的配置(local-override-token)
作用域选择建议:
| 场景 | 推荐作用域 | 原因 |
|---|---|---|
| 包含 API 密钥的配置 | Local | 安全,不会提交到 Git |
| 团队必需的工具 | Project | 团队共享,可版本控制 |
| 个人常用工具 | User | 全局可用 |
| 临时测试配置 | Local | 不影响其他配置 |
| CI/CD 使用 | Project | 可自动化部署 |
配置方法:
Local 作用域(修改 ~/.claude.json):
{
"mcpServers": {
"/Users/me/project1": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx_local_override"
}
}
}
}
}
Project 作用域(项目根目录 .mcp.json):沿用前面 GitHub MCP 的 .mcp.json 写法,把配置放到项目根目录,适合团队共享服务器声明;密钥仍然通过环境变量注入,不要把 token 写进仓库。
User 作用域(使用 CLI):
claude mcp add --scope user github npx -y @modelcontextprotocol/server-github
3.5 更多常用服务器配置
Brave Search(网页搜索)
功能:隐私优先的 Web 搜索,免费层每月 2000 次查询。
获取 API Key:注册后创建 API Key(免费层 2000 次/月)。
配置方法:
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}"
}
}
}
}
Context7(技术文档)
功能:获取 1000+ 流行框架的最新文档,解决 AI 训练数据过时问题。
配置方法(无需 API Key):
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {}
}
}
}
使用示例:
你:查一下React 19的新特性
Claude Code:
1. [调用] resolve_library_id("react")
2. [调用] get_library_docs("/facebook/react", "react 19", 5000)
3. [返回] React 19新特性包括:...
注意:Context7 免费额度为每月 1,000 次请求(2026 年 1 月从 6,000 次下调),每小时限 60 次。超出需配置 API Key。
MCP Apps(交互式界面)
功能:MCP 服务器可提供交互式用户界面,直接在聊天中渲染图表、表单、仪表盘。这是 2026 年初新增的能力——MCP 服务器不再只是返回文本数据,还可以返回可交互的 UI 组件,让你在 Claude Code 的对话中直接操作第三方工具的界面,无需切换到外部应用。
MCP 工具懒加载(当前标准行为)
功能:延迟加载 MCP 工具定义,减少上下文占用高达 95%。当你配置了大量 MCP 服务器时,旧版本会把所有工具描述一次性加载到上下文窗口,浪费大量 token。这个 ToolSearch 懒加载机制 早在 v2.1.52 引入,到当前版本已经是默认行为:只有在需要时才加载对应工具。
使用方式(自动生效,无需配置):
你:帮我查一下Slack里的消息
Claude Code:
1. [ToolSearch] 搜索 "slack" → 找到 mcp__slack__read_channel
2. [加载] 按需加载 slack 工具定义
3. [调用] mcp__slack__read_channel(...)
v2.1.121+ 新增:alwaysLoad 跳过懒加载——如果你的某个 MCP 服务器提供的工具几乎每次会话都会用到(比如 GitHub MCP),可以设 alwaysLoad: true 让它的工具跳过 ToolSearch 延迟,始终立即可用:
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"alwaysLoad": true
}
}
}
alwaysLoad: true:工具定义直接注入上下文,无需 ToolSearch 搜索- 不设或
alwaysLoad: false:走标准 ToolSearch 懒加载(默认)
适用场景:高频使用的核心 MCP(如 GitHub、数据库),设 alwaysLoad 可省去每次搜索的开销;低频 MCP 保持默认懒加载即可。
MCP Elicitation(交互式信息请求,v2.1.69+)
功能:MCP 服务器可在运行时通过交互对话框向用户请求结构化输入。这是 MCP 协议的一项扩展能力——当 MCP 工具在执行过程中需要额外信息时,可以主动向用户发起交互请求,而不是直接报错或猜测参数。
工作流程:
1. Claude Code 调用 MCP 工具
2. MCP 服务器发现需要额外信息(如选择数据库、确认操作等)
3. MCP 服务器发起 elicitation 请求
4. Claude Code 向用户显示交互对话框(表单、选择框等)
5. 用户填写/选择后,结果返回 MCP 服务器
6. MCP 服务器继续执行操作
典型场景:数据库 MCP 需要用户选择目标数据库或确认破坏性操作;部署工具需要用户确认环境(staging / production);API 集成需要用户选择账户或填写缺失的必要参数。
⚠️ 版本要求:需要 Claude Code v2.1.69+ 支持。Elicitation 请求可在 Hooks 系统中通过
Elicitation/ElicitationResult事件进行拦截和自定义处理——本仓库 05-Hooks 系统完整指南 详细讲解了这两个 Hook 事件:Elicitation在 MCP 服务器请求额外交互输入时触发(可接受、拒绝或取消请求),ElicitationResult在用户响应后、返回 MCP 前触发(可验证或修改响应)。
远程 MCP 服务器
功能:支持连接远程运行的 MCP 服务器(HTTP 传输),不限于本地进程。
配置远程 MCP 服务器:
claude mcp add --transport http my-remote-server https://your-server.com/mcp
适用于团队共享的 MCP 服务(如共享数据库、内部 API 网关等)。
Memory(持久化记忆)
功能:跨会话保存信息,记住用户偏好和项目上下文。
配置方法:
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": {}
}
}
}
Fetch(网页获取)
功能:获取网页内容,转换为 Markdown 格式。
配置方法:
{
"mcpServers": {
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {}
}
}
}
Sequential Thinking(顺序思考)
功能:结构化的顺序思考过程,用于分解复杂问题。
配置方法:
{
"mcpServers": {
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
"env": {}
}
}
}
Puppeteer(浏览器自动化)
功能:无头浏览器自动化,网页截图、表单填写、数据采集。
配置方法:
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"env": {}
}
}
}
3.6 完整配置示例
一个功能完整的项目配置(.mcp.json):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./docs", "./data"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
},
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./data/app.db"],
"env": {}
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {}
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}"
}
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": {}
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {}
}
}
}
3.7 服务器分类速查表
| 分类 | 服务器 | 用途 | 需要 API Key | 重要 |
|---|---|---|---|---|
| 数据 | filesystem | 文件读写 | ❌ | ⭐ |
| 数据 | sqlite | SQLite 数据库 | ❌ | ⭐ |
| 数据 | postgres | PostgreSQL 数据库 | ❌(需连接串) | |
| 数据 | memory | 持久化记忆 | ❌ | |
| 搜索 | brave-search | 网页搜索 | ✅ | ⭐ |
| 搜索 | fetch | 网页获取 | ❌ | |
| 开发 | github | GitHub 仓库管理 | ✅ | ⭐ |
| 开发 | gitlab | GitLab 仓库管理 | ✅ | |
| 开发 | git | 本地 Git 操作 | ❌ | |
| 知识 | context7 | 技术文档 | ❌ | ⭐ |
| 思考 | sequential-thinking | 顺序推理 | ❌ | |
| 自动化 | puppeteer | 浏览器自动化 | ❌ |
第四部分:MCP 工作原理(可选深入)
理解 MCP 底层工作机制,帮助排查问题和开发自定义服务器。预计 30-45 分钟。可跳过:如果只是想使用 MCP,不打算开发自定义服务器,可以跳过本节。
4.1 传输层详解
STDIO 传输(标准输入输出)
这是什么? STDIO 是最基础的传输方式,MCP 客户端和服务器通过进程间的标准输入输出流通信。
工作原理:
┌──────────────────┐ ┌──────────────────┐
│ MCP Client │ │ MCP Server │
│ (Claude Code) │ │ (subprocess) │
├──────────────────┤ ├──────────────────┤
│ │ stdin │ │
│ 发送请求 ────────┼────────►│ 接收并处理 │
│ │ │ │
│ │ stdout │ │
│ 接收响应 ◄───────┼─────────│ 发送响应 │
│ │ │ │
│ │ stderr │ │
│ 查看日志 ◄───────┼─────────│ 输出日志 │
└──────────────────┘ └──────────────────┘
生活类比:STDIO 就像两个人面对面对话——stdin = 听(接收信息),stdout = 说(发送回复),stderr = 旁白(日志信息)。
优势:简单直接无需网络配置、性能最优无网络开销、安全性高进程级隔离、最适合单客户端场景。
适用场景:本地工具(filesystem、sqlite)、单用户使用、不需要远程访问。
Streamable HTTP 传输(远程通信)
这是什么? HTTP 传输让 MCP 服务器可以运行在远程机器上,通过网络通信。
工作原理:
┌──────────────────┐ HTTP ┌──────────────────┐
│ MCP Client │ POST │ MCP Server │
│ │────────►│ (Remote) │
│ │ │ │
│ │ SSE │ │
│ 接收流式响应 ◄───┼─────────│ 流式返回 │
└──────────────────┘ └──────────────────┘
生活类比:HTTP 传输就像打电话——可以在不同地点通话,但需要电话线(网络)连接。
优势:支持远程访问、可多客户端共享、适合分布式部署。
适用场景:远程服务器、多用户共享、分布式系统。
传输方式对比
| 特性 | STDIO | HTTP |
|---|---|---|
| 部署位置 | 本地 | 本地或远程 |
| 网络需求 | 无 | 需要 HTTP |
| 性能 | 最优 | 略有开销 |
| 安全性 | 进程隔离 | 需要认证 |
| 适用场景 | 单客户端本地工具 | 分布式/远程服务 |
| 复杂度 | 简单 | 中等 |
| 推荐度 | ⭐⭐⭐⭐⭐(本地) | ⭐⭐⭐⭐(远程) |
4.2 JSON-RPC 通信机制
这是什么? JSON-RPC 是 MCP 使用的通信协议,所有消息都是 JSON 格式。
三种消息类型
1. 请求(Request)
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "read_file",
"arguments": {
"path": "/path/to/file.txt"
}
}
}
字段说明:jsonrpc 协议版本(必须是 "2.0");id 请求标识符(用于匹配响应);method 要调用的方法名;params 方法参数(可选)。
2. 响应(Response)
成功响应:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "文件内容..."
}
]
}
}
错误响应:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid Request",
"data": "详细错误信息"
}
}
3. 通知(Notification)
{
"jsonrpc": "2.0",
"method": "notifications/progress",
"params": {
"progressToken": "token-123",
"progress": 50,
"total": 100
}
}
💡 通知 vs 请求:通知没有
id字段,不需要响应。
标准错误码
| 错误码 | 含义 | 说明 |
|---|---|---|
| -32700 | Parse error | JSON 解析失败 |
| -32600 | Invalid Request | 请求格式无效 |
| -32601 | Method not found | 方法不存在 |
| -32602 | Invalid params | 参数无效 |
| -32603 | Internal error | 服务器内部错误 |
4.3 三大组件详解
1. Tools(工具)
这是什么? Tools 是 MCP 服务器提供的"函数",AI 可以调用它们执行操作。
工具定义示例:
{
"name": "read_file",
"description": "读取指定路径的文件内容",
"inputSchema": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "文件的绝对路径"
}
},
"required": ["path"]
}
}
生活类比:Tools = 工具箱里的工具,每个工具有特定用途,AI 选择合适的工具完成任务。
2. Resources(资源)
这是什么? Resources 是 MCP 服务器提供的"数据",AI 可以读取它们。
资源定义示例:
{
"uri": "file:///project/README.md",
"name": "项目说明文档",
"mimeType": "text/markdown"
}
生活类比:Resources = 参考书架,提供只读数据,AI 可以查阅但不能修改。
3. Prompts(提示词)
这是什么? Prompts 是 MCP 服务器提供的"模板",预定义的交互方式。
提示词定义示例:
{
"name": "code_review",
"description": "代码审查提示词模板",
"arguments": [
{
"name": "code",
"description": "要审查的代码",
"required": true
}
]
}
生活类比:Prompts = 填空表格,预定义好结构,AI 按模板填写。
4.4 连接生命周期
协议版本说明(核查日:2026-09-14):2026-07-28 版改为按请求声明协议版本。请求在 _meta 的 io.modelcontextprotocol/protocolVersion 中带版本;Streamable HTTP 还会在 MCP-Protocol-Version 请求头中带同一值。服务器逐条接受或拒绝请求,不再要求先完成旧版初始化握手。
客户端可以先调用 server/discover,取得服务器支持的版本、能力和身份信息;服务器必须实现这个 RPC,但客户端可以直接发业务请求。如果收到 UnsupportedProtocolVersionError,再根据返回的版本列表选双方支持的版本重试。
下面是 2025-11-25 及更早协议的兼容流程。旧客户端、旧 SDK 仍可能走这条路径,不能只把 initialize 中的日期替换成 2026-07-28 就算完成升级:
1. 初始化阶段
Client → Server: initialize请求(发送客户端能力)
Server → Client: initialize响应(发送服务器能力)
Client → Server: initialized通知(确认初始化完成)
2. 操作阶段
Client → Server: 发送各种请求(tools/call, resources/read等)
Server → Client: 返回响应或错误
Server → Client: 可选发送通知(进度更新等)
3. 关闭阶段
Client/Server: 关闭连接
Server: 清理资源
后续开发示例展示 SDK 封装的工具注册与 stdio 启动。实际使用的协议版本取决于客户端和所装 SDK 的兼容范围;规范的最新版本不代表所有客户端已经默认采用它。实现新协议或维护旧握手时,分别对照版本协商与向后兼容说明。本仓库 README 亦提示:Claude Code 教程基线为 v2.1.270,而
stable通道仍为 2.1.236,两者是不同发布通道,使用时以本机claude --version为准。
第五部分:自定义 MCP 开发(进阶可选)
学会开发自己的 MCP 服务器。预计 1.5-2 小时。前置要求:熟悉 TypeScript/JavaScript 基础。
5.1 开发环境搭建
技术栈选择:
| 技术栈 | 适用场景 | 优势 | 劣势 |
|---|---|---|---|
| Node.js + TypeScript | 通用工具、API 集成 | 生态丰富,开发快速 | 性能略低 |
| Python | 数据处理、AI 模型集成 | 库丰富,语法简洁 | 打包复杂 |
本教程选择:Node.js + TypeScript(官方推荐,生态最成熟)。
环境要求:
Windows(PowerShell):
# 检查Node.js版本(需要18+)
node --version
# 预期输出:v18.x.x 或更高
# 检查npm版本
npm --version
# 预期输出:9.x.x 或更高
# 安装TypeScript(如果没有)
npm install -g typescript
tsc --version
# 预期输出:Version 5.x.x
macOS/Linux:
# 检查Node.js版本
node --version
# 预期输出:v18.x.x 或更高
# 检查npm版本
npm --version
# 安装TypeScript
npm install -g typescript
tsc --version
创建 MCP 项目:
步骤1:初始化项目
# 创建项目目录
mkdir my-first-mcp
cd my-first-mcp
# 初始化npm项目
npm init -y
# 安装MCP SDK
npm install @modelcontextprotocol/sdk
# 安装开发依赖
npm install -D typescript @types/node ts-node
步骤2:配置 TypeScript——创建 tsconfig.json:
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"resolveJsonModule": true,
"declaration": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
步骤3:配置 package.json:
{
"name": "my-first-mcp",
"version": "1.0.0",
"type": "module",
"description": "我的第一个MCP服务器",
"main": "dist/index.js",
"types": "dist/index.d.ts",
"bin": {
"my-first-mcp": "dist/index.js"
},
"scripts": {
"build": "tsc",
"dev": "ts-node --esm src/index.ts",
"start": "node dist/index.js",
"watch": "tsc --watch"
},
"keywords": ["mcp", "claude", "ai-tools"],
"author": "Your Name",
"license": "MIT",
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.0"
},
"devDependencies": {
"@types/node": "^20.0.0",
"ts-node": "^10.9.0",
"typescript": "^5.0.0"
}
}
关键配置说明:
| 配置项 | 说明 |
|---|---|
"type": "module" |
启用 ES 模块支持 |
"bin" |
定义命令行入口(用于 npx my-first-mcp) |
"build" |
编译 TypeScript 到 dist/ |
"dev" |
开发模式运行 |
步骤4:创建项目结构
# 创建源代码目录
mkdir -p src/tools src/resources src/types
项目结构:
my-first-mcp/
├── src/
│ ├── index.ts # 入口文件
│ ├── tools/ # 工具定义
│ │ └── hello.ts
│ ├── resources/ # 资源定义
│ │ └── config.ts
│ └── types/ # 类型定义
│ └── index.ts
├── dist/ # 编译输出(自动生成)
├── .gitignore
├── package.json
└── tsconfig.json
创建 .gitignore:
node_modules/
dist/
*.log
.DS_Store
.env
5.2 Hello World MCP
最小可用的 MCP 服务器——创建 src/index.ts:
#!/usr/bin/env node
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
CallToolRequestSchema,
ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// 创建MCP服务器实例
const server = new Server(
{
name: "my-first-mcp",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
// 定义工具列表
server.setRequestHandler(ListToolsRequestSchema, async () => {
return {
tools: [
{
name: "hello_world",
description: "一个简单的Hello World工具,返回问候语",
inputSchema: {
type: "object",
properties: {
name: {
type: "string",
description: "要问候的名字",
},
},
required: ["name"],
},
},
],
};
});
// 处理工具调用
server.setRequestHandler(CallToolRequestSchema, async (request) => {
const { name, arguments: args } = request.params;
if (name === "hello_world") {
const userName = args?.name as string || "World";
return {
content: [
{
type: "text",
text: `Hello, ${userName}! 这是来自my-first-mcp的问候!`,
},
],
};
}
throw new Error(`未知工具: ${name}`);
});
// 启动服务器
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("my-first-mcp 服务器已启动"); // 日志输出到stderr
}
main().catch(console.error);
代码结构解读:
Server实例声明服务器名称、版本和能力(capabilities.tools声明支持工具能力);ListToolsRequestSchema处理器返回工具清单(含inputSchema参数校验定义);CallToolRequestSchema处理器根据工具名分发调用并返回content结果;StdioServerTransport以 stdio 方式连接——对应第四部分讲解的 STDIO 传输机制;- 启动日志输出到 stderr(stdout 专用于与客户端通信)。
验证开发环境:
# 编译TypeScript
npm run build
# 检查dist目录
ls dist/
# 应该看到:index.js index.d.ts
测试运行:
# 直接运行
npm start
# 或使用开发模式
npm run dev
# 预期输出(到stderr):
# my-first-mcp 服务器已启动
💡 说明:服务器启动后会等待 stdin 输入,这是正常的。按
Ctrl+C退出。
5.3 配置和测试自定义 MCP
在 Claude Code 中使用:
步骤1:在项目的 .mcp.json 中添加:
{
"mcpServers": {
"my-first-mcp": {
"command": "node",
"args": ["/path/to/my-first-mcp/dist/index.js"],
"env": {}
}
}
}
⚠️ 注意:替换
/path/to/my-first-mcp为你的实际路径。
步骤2:测试
# 启动Claude Code
claude
# 测试
你:用hello_world工具问候"老金"
预期响应:
Claude Code:
[调用 my-first-mcp.hello_world]
参数: {"name": "老金"}
Hello, 老金! 这是来自my-first-mcp的问候!
5.4 使用 MCP Inspector 调试
这是什么? MCP Inspector 是官方提供的调试工具,可以交互式测试 MCP 服务器。
使用方法:
# 调试自己的MCP服务器
npx @modelcontextprotocol/inspector node /path/to/my-first-mcp/dist/index.js
# 调试官方服务器
npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem ./
访问调试界面:启动后访问 http://127.0.0.1:6274
Inspector 功能:交互式工具测试、请求/响应查看、资源浏览、协议一致性检查。
5.5 添加更多功能
添加第二个工具——在 ListToolsRequestSchema 处理器中添加:
// 在 ListToolsRequestSchema 处理器中添加
{
name: "get_current_time",
description: "获取当前时间",
inputSchema: {
type: "object",
properties: {
timezone: {
type: "string",
description: "时区(如 'Asia/Shanghai')",
},
},
},
},
在 CallToolRequestSchema 处理器中添加:
if (name === "get_current_time") {
const timezone = args?.timezone as string || "Asia/Shanghai";
const now = new Date().toLocaleString("zh-CN", { timeZone: timezone });
return {
content: [
{
type: "text",
text: `当前时间(${timezone}):${now}`,
},
],
};
}
添加 Resources:
import {
ListResourcesRequestSchema,
ReadResourceRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
// 在Server配置中启用resources
const server = new Server(
{ name: "my-first-mcp", version: "1.0.0" },
{
capabilities: {
tools: {},
resources: {}, // 添加这行
},
}
);
// 定义资源列表
server.setRequestHandler(ListResourcesRequestSchema, async () => {
return {
resources: [
{
uri: "config://app-settings",
name: "应用配置",
mimeType: "application/json",
},
],
};
});
// 处理资源读取
server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
const { uri } = request.params;
if (uri === "config://app-settings") {
return {
contents: [
{
uri,
mimeType: "application/json",
text: JSON.stringify({ version: "1.0.0", debug: false }, null, 2),
},
],
};
}
throw new Error(`未知资源: ${uri}`);
});
5.6 发布 MCP 服务器
发布到 npm:
步骤1:确保 package.json 配置正确:
{
"name": "@your-username/my-first-mcp",
"version": "1.0.0",
"description": "我的第一个MCP服务器",
"main": "dist/index.js",
"bin": {
"my-first-mcp": "dist/index.js"
},
"repository": {
"type": "git",
"url": "https://github.com/your-username/my-first-mcp"
},
"keywords": ["mcp", "claude", "ai-tools"],
"license": "MIT"
}
步骤2:登录 npm:
npm login
步骤3:发布:
# 构建
npm run build
# 发布
npm publish --access public
步骤4:使用已发布的服务器:
{
"mcpServers": {
"my-first-mcp": {
"command": "npx",
"args": ["-y", "@your-username/my-first-mcp"],
"env": {}
}
}
}
第六部分:故障排查
6.1 常见问题排查流程
问题出现
│
▼
1. 检查配置文件 ─── JSON格式错误?→ 修复JSON
│
▼
2. 检查服务器状态 ─── 服务器启动失败?→ 查看日志
│
▼
3. 检查环境变量 ─── API Key缺失?→ 配置环境变量
│
▼
4. 检查网络 ─── 无法下载包?→ 配置镜像/代理
│
▼
5. 检查版本 ─── 版本不兼容?→ 更新Node.js/SDK
6.2 按错误类型排查
错误1:服务器无法启动
错误信息示例:
Error: MCP server 'xxx' failed to start
排查步骤:
# 1. 检查Node.js版本
node --version
# 需要 v18.x.x 或更高
# 2. 检查npx是否可用
npx --version
# 3. 手动运行服务器命令
npx -y @modelcontextprotocol/server-filesystem ./
# 4. 如果报错,查看具体错误信息
常见原因和解决方案:
| 原因 | 解决方案 |
|---|---|
| Node.js 版本过低 | 升级到 v18+ |
| npx 不可用 | 重装 npm 或使用 npm 安装 |
| 网络无法访问 npm | 配置国内镜像 |
| 包名写错 | 检查包名拼写 |
错误2:配置文件格式错误
错误信息示例:
SyntaxError: Unexpected token in JSON
排查步骤:
# 1. 验证JSON格式
cat .mcp.json | jq .
# 2. 使用在线工具验证
# 访问 https://jsonlint.com/
常见 JSON 错误:
| 错误 | 示例 | 修复 |
|---|---|---|
| 缺少逗号 | "a": 1 "b": 2 |
"a": 1, "b": 2 |
| 多余逗号 | "a": 1,} |
"a": 1} |
| 使用单引号 | 'key': 'value' |
"key": "value" |
| 未闭合的引号 | "key: "value" |
"key": "value" |
错误3:环境变量未设置
错误信息示例:
Error: GITHUB_PERSONAL_ACCESS_TOKEN is required
Error: Missing required environment variable
Windows(PowerShell):
# 检查环境变量
$env:GITHUB_PERSONAL_ACCESS_TOKEN
# 如果为空,说明未设置
# 设置环境变量
[System.Environment]::SetEnvironmentVariable('GITHUB_PERSONAL_ACCESS_TOKEN', 'your-token', 'User')
# 重启终端后验证
$env:GITHUB_PERSONAL_ACCESS_TOKEN
macOS/Linux:
# 检查环境变量
echo $GITHUB_PERSONAL_ACCESS_TOKEN
# 如果为空,添加到shell配置
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="your-token"' >> ~/.zshrc
source ~/.zshrc
错误4:网络超时
错误信息示例:
npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org failed
解决方案:
# 方案1:使用国内镜像
npm config set registry https://registry.npmmirror.com
# 方案2:配置代理(如果有代理工具)
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890
# 方案3:增加超时时间
npm config set timeout 60000
6.3 查看日志
Claude Code 日志:
macOS:
tail -f ~/Library/Logs/Claude/mcp*.log
Windows:
Get-Content "$env:LOCALAPPDATA\Claude\logs\mcp*.log" -Wait
Linux:
tail -f ~/.local/share/claude/logs/mcp*.log
调试模式启动:
# 开启MCP调试日志
claude --mcp-debug
6.4 重置 MCP 配置
如果配置混乱,可以重置:
# 删除项目级配置
rm .mcp.json
# 删除用户级配置(谨慎!)
# macOS/Linux
rm ~/.claude.json
# Windows
del %USERPROFILE%\.claude.json
第七部分:FAQ(20 个常见问题)
基础问题
Q1:MCP 和普通 API 有什么区别?
A:MCP 是协议标准,API 是具体实现。
| 对比 | MCP | 普通 API |
|---|---|---|
| 定位 | 通用协议标准 | 具体服务接口 |
| 兼容性 | 跨平台、跨 AI | 仅特定服务 |
| 学习成本 | 学一次用到处 | 每个 API 都不同 |
| 类比 | USB 标准 | 某品牌的 USB 设备 |
Q2:MCP 服务器需要一直运行吗?
A:不需要。Claude Code 会在需要时自动启动 MCP 服务器,使用完毕后自动关闭。
Q3:配置多个 MCP 服务器会影响性能吗?
A:不会。MCP 服务器是按需启动的,只有被调用时才会运行。配置 10 个服务器但只用 1 个,不会有额外开销。
Q4:MCP 服务器的数据安全吗?
A:取决于配置。Filesystem MCP 只能访问你指定的目录;所有操作都需要你确认;但 API Key 等敏感信息要妥善保管,不要把敏感 Token 写在配置文件里。
配置问题
Q5:.mcp.json 放在哪里?
A:项目根目录。和 package.json、.git 目录同级。
Q6:Local、Project、User 作用域怎么选?
A:
| 情况 | 选择 |
|---|---|
| 包含 API Key | Local(不会提交 Git) |
| 团队共享 | Project |
| 个人常用 | User |
| 临时测试 | Local |
Q7:环境变量 ${VAR} 语法不生效?
A:检查以下几点:环境变量名正确(区分大小写)、环境变量已导出、终端已重启、使用 echo $VAR 验证。
Q8:可以同时用多个数据库 MCP 吗?
A:可以,用不同名称:
{
"mcpServers": {
"sqlite-app": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./app.db"]
},
"sqlite-analytics": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./analytics.db"]
}
}
}
故障问题
Q9:MCP 服务器启动失败怎么办?
A:按以下步骤排查:检查 Node.js 版本(需要 18+)、手动运行 npx 命令看报错、检查网络是否能访问 npm、查看 Claude Code 日志。
Q10:为什么 Claude Code 看不到 MCP 服务器?
A:确认 .mcp.json 在项目根目录、确认 JSON 格式正确、确认在项目目录启动 Claude Code、退出后重新启动 Claude Code。
Q11:工具调用返回错误怎么办?
A:检查参数是否正确、检查 API Key 是否有效、查看 MCP 服务器日志、使用 MCP Inspector 调试。
Q12:如何更新 MCP 服务器?
A:npx 会自动获取最新版本。如需强制更新:
# 清除npx缓存
npx clear-npx-cache
# 或删除缓存目录
# macOS/Linux
rm -rf ~/.npm/_npx
# Windows
rd /s /q %LOCALAPPDATA%\npm-cache\_npx
开发问题
Q13:用 TypeScript 还是 Python 开发 MCP?
A:
| 选择 | 适合场景 |
|---|---|
| TypeScript | 通用工具、API 集成、Web 相关 |
| Python | 数据处理、AI 模型、科学计算 |
官方推荐 TypeScript,生态更成熟。
Q14:如何调试自己开发的 MCP?
A:使用 MCP Inspector:
npx @modelcontextprotocol/inspector node ./dist/index.js
然后访问 http://127.0.0.1:6274。
Q15:如何发布 MCP 到 npm?
A:
npm login
npm run build
npm publish --access public
安全问题
Q16:API Key 泄露了怎么办?
A:立即删除泄露的 Key、创建新 Key、更新环境变量、检查使用记录是否异常。
Q17:如何安全管理 API Key?
A:使用环境变量,不硬编码;使用 ${VAR} 语法引用;.mcp.json 只放引用,不放值;敏感配置放 Local 作用域;不要提交包含 Key 的文件到 Git。
Q18:MCP 服务器能访问我的所有文件吗?
A:不能。Filesystem MCP 只能访问你在配置中指定的目录。
其他问题
Q19:MCP 支持哪些 AI 工具?
A:已支持:Claude Desktop、Claude Code、VS Code + Continue、Cursor、Zed,以及更多支持 MCP 协议的工具。
Q20:哪里找更多 MCP 服务器?
A:官方服务器仓库、Awesome 列表、MCP Server Finder 等社区资源(本仓库 10-综合实战完整指南 的安全章节也给出了 MCP 服务器选择的实践建议)。
MCP 安全深度补充(仓库源码佐证)
MCP 服务器的信任管理通过 Claude Code 的权限系统(settings.json 的 permissions)控制,而非 MCP 配置本身。本仓库 10-综合实战完整指南 给出了企业级落地的关键实践:
- 标准字段约束:
.mcp.json中 MCP 服务器配置的标准字段只有command、args和env,不要使用虚构字段(如trust、network、limits)。 - 权限规则控制:使用
settings.json的permissions规则控制 MCP 工具的使用范围,如"mcp__context7__get_library_docs"精确允许、"mcp__*__delete_*"与"mcp__*__drop_*"通配禁止危险操作。permissions采用扁平的allow/deny列表结构,未出现在任一列表中的工具和命令默认需要用户确认(ask),deny列表支持通配符匹配。 - 环境变量注入密钥:敏感信息一律通过
${MCP_API_KEY}、${DB_URL}等环境变量引用注入,不硬编码。 - Hooks 监控调用:可通过
PreToolUseHook(matcher 设为^mcp__.*)记录即将发起的 MCP 工具调用,实现审计日志。
这一补充印证了"外部工具越强,越不能靠感觉授权"的边界原则——配置 MCP 之后,还要用权限系统和 Hooks 把"能用什么、不能用什么"落实到可执行的规则上。
总结与检查清单
学习成果检查
完成本课后,你应该能够:
- [ ] 理解 MCP 价值:能向他人解释 MCP 是什么、为什么重要
- [ ] 配置基础 MCP:成功配置 Filesystem MCP 并调用工具
- [ ] 配置 GitHub MCP:正确设置 Token 并管理仓库
- [ ] 配置数据库 MCP:连接 SQLite 或 PostgreSQL
- [ ] 理解三作用域:知道 Local/Project/User 的区别和使用场景
- [ ] 排查常见问题:能独立解决配置和连接错误
- [ ] 开发简单 MCP:能创建包含 Tool 的 MCP 服务器(可选)
配置检查清单
在项目中使用 MCP 前,确认:
- [ ]
.mcp.json文件存在且格式正确 - [ ] 所需环境变量已配置
- [ ] API Key 安全存储(不在配置文件中硬编码)
- [ ] Claude Code 启动时显示 MCP 服务器已连接
- [ ] 至少测试过一个 MCP 工具调用
推荐下一步
- 配置更多服务器:根据你的开发需求,配置 Context7、Brave Search 等
- 深入学习:阅读 MCP 官方文档了解更多高级特性
- 开发自定义 MCP:将你的常用工具封装成 MCP 服务器
- 参与社区:在 GitHub 上分享你开发的 MCP 服务器
附录
附录A:完整 .mcp.json 模板
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./docs"],
"env": {}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
},
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./data/app.db"],
"env": {}
},
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"],
"env": {}
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}"
}
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"],
"env": {}
},
"fetch": {
"command": "uvx",
"args": ["mcp-server-fetch"],
"env": {}
},
"sequential-thinking": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
"env": {}
},
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"env": {}
}
}
}
附录B:MCP 命令速查表
| 命令 | 功能 | 示例 | 重要 |
|---|---|---|---|
claude mcp list |
列出所有 MCP 服务器 | claude mcp list |
⭐ |
claude mcp add |
添加 MCP 服务器 | claude mcp add fs npx -y @.../server-filesystem ./ |
⭐ |
claude mcp get |
查看服务器详情 | claude mcp get github |
|
claude mcp remove |
删除服务器 | claude mcp remove github |
|
claude --mcp-debug |
调试模式启动 | claude --mcp-debug |
⭐ |
⚠️ 重要澄清:
claude mcp test和claude mcp restart命令不存在。如需测试服务器,使用claude mcp get <name>查看状态;如需重启,退出并重新启动 Claude Code。
附录C:官方 MCP 服务器列表
| 服务器 | 包名 | 功能 | 重要 |
|---|---|---|---|
| Filesystem | @modelcontextprotocol/server-filesystem |
文件系统操作 | ⭐ |
| GitHub | @modelcontextprotocol/server-github |
GitHub 仓库管理 | ⭐ |
| GitLab | @modelcontextprotocol/server-gitlab |
GitLab 仓库管理 | |
| Git | mcp-server-git(Python/uvx) |
本地 Git 操作 | |
| SQLite | mcp-server-sqlite(Python/uvx) |
SQLite 数据库 | ⭐ |
| PostgreSQL | @modelcontextprotocol/server-postgres |
PostgreSQL 数据库 | |
| Memory | @modelcontextprotocol/server-memory |
持久化记忆 | |
| Fetch | mcp-server-fetch(Python/uvx) |
网页获取 | |
| Time | mcp-server-time(Python/uvx) |
时间服务 | |
| Sequential Thinking | @modelcontextprotocol/server-sequential-thinking |
顺序思考 | |
| Puppeteer | @modelcontextprotocol/server-puppeteer |
浏览器自动化 | |
| Brave Search | @modelcontextprotocol/server-brave-search |
网页搜索 | ⭐ |
| Context7 | @upstash/context7-mcp |
技术文档 | ⭐ |
附录D:本仓库相关资源
- Claude Code 完整安装指南——MCP 学习的前置环境
- Claude Code 基础使用完整指南——MCP 调用前的 CLI 基础
- Claude Code Commands 系统完整指南——
/mcp命令与mcp__服务器__工具命名规则 - Claude Code Hooks 系统完整指南——
Elicitation/ElicitationResultHook 与 MCP 交互输入拦截 - Claude Code 综合实战完整指南——MCP 服务器安全管理、权限规则与 Hooks 监控
- Claude Code 快速导航卡——MCP 速查入口
版本说明:本教程对应 MCP 规范 2026-07-28 / Claude Code v2.1.270(验证于 2026-09-14)。版本号会随上游更新而失效,遇到界面、命令或参数不一致时,优先查官方更新日志、官方文档和 CLI 帮助(
--help),并以本机claude --version输出为准。