MCP集成完整指南：从配置到开发的实战手册
课程信息
⠀
-
作者：老金
-
GitHub：https://github.com/KimYx0207
-
公众号：老金带你玩AI
-
X（Twitter）：老金带你玩AI
-
个人博客：https://aiking.dev
-
预计学时：4-6小时
-
难度等级：⭐⭐ 入门级（有Claude Code基础即可）
-
更新日期：2026年5月30日
-
适用版本：MCP规范 2025-11-25 / Claude Code v2.1.158（验证于 2026-05-30）
-
前置要求：已完成Claude Code安装和基础使用
本课学习目标
⠀
完成本课学习后，你将能够：
⠀
-
理解MCP的核心价值：掌握MCP协议与传统AI工具集成方式的本质区别
-
配置常用MCP服务器：独立完成Filesystem、GitHub、数据库等10+核心服务器配置
-
掌握三作用域配置体系：理解Local/Project/User作用域的优先级和适用场景
-
排查MCP连接问题：独立解决90%的常见配置和连接故障
-
理解MCP工作原理：掌握STDIO/HTTP传输层和JSON-RPC通信机制
-
开发自定义MCP服务器：从零创建一个可用的MCP服务器（TypeScript）
-
安全使用MCP：正确管理API密钥和敏感配置
学习路径导航（先看这里！）
⠀
根据你的情况选择学习路径：这是一篇3000+行的长教程，不用全看！根据你的目标选择路径。
⠀
路径A：快速上手（60分钟）
⠀
适合人群：急着用MCP，想快速配一个看效果
⠀
只看这些章节（其他跳过）：
⠀
✅ 术语表（5分钟） - 快速了解MCP核心概念
✅ 第一部分：MCP简介（10分钟） - 理解MCP是什么
✅ 第二部分：5分钟快速开始（15分钟） - 配置第一个MCP服务器
✅ 第三部分3.1-3.3：配置GitHub和数据库MCP（30分钟）
⠀
60分钟后你能达到：成功配置2-3个MCP服务器，Claude Code能调用外部工具
路径B：完整学习（4-6小时）
⠀
适合人群：想深入理解MCP，掌握配置和开发
⠀
学习顺序：从头到尾所有章节
⠀
建议分段学习：
-
第1天（2小时）：第1-3部分（理解+配置）
-
第2天（2小时）：第4-5部分（原理+开发）
-
第3天（1小时）：第6-7部分（故障排查+FAQ）
路径C：问题排查（10分钟）
⠀
适合人群：MCP配置出问题，需要快速解决
⠀
直接跳到这些章节：
⠀
🔧 第六部分：故障排查 - 按错误类型查找解决方案
🔧 第七部分：FAQ - 20个常见问题解答
⠀
使用方法：
-
按 Ctrl + F 搜索你的错误信息关键词
-
找到对应的Q&A
-
按步骤解决
路径D：专项学习（30-60分钟/主题）
⠀
适合人群：已经会配置MCP，想学习特定功能
⠀
想学什么
看哪几节
预计时间
自定义MCP开发
第五部分
1.5小时
三作用域配置
第三部分3.4节
30分钟
MCP工作原理
第四部分
45分钟
安全最佳实践
第三部分3.5节
20分钟
术语表（小白必读）
⠀
在开始之前，先了解这些关键术语。用生活类比帮助理解：
⠀
术语
英文全称
通俗解释
生活类比
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简介（5分钟快速理解）
⠀
1.1 MCP是什么
⠀
一句话理解：MCP（Model Context Protocol）是AI工具的"USB接口标准"，让任何AI应用都能即插即用地连接各种外部服务。
⠀
为什么需要MCP？
⠀
没有MCP之前（混乱的世界）：
⠀
问题：每个AI工具都要单独对接，重复造轮子
Claude Desktop → [自定义代码] → GitHub
Claude Desktop → [自定义代码] → 数据库
Claude Desktop → [自定义代码] → 文件系统
VS Code + AI → [另一套代码] → GitHub
VS Code + AI → [另一套代码] → 数据库
...无限重复...
⠀
有了MCP之后（标准化的世界）：
⠀
解决方案：统一接口，一次开发到处使用
Claude Desktop ──┐
VS Code + AI ────┼── MCP协议 ── GitHub MCP Server
Cursor ──────────┤ 数据库 MCP Server
任何AI工具 ──────┘ 文件系统 MCP Server
⠀
生活类比：
-
没有USB标准：每个品牌的键盘、鼠标都需要专用接口，换电脑就要换设备
-
有USB标准后：任何USB键盘都能插任何电脑，即插即用
⠀
MCP的核心价值
⠀
对比维度
传统集成方式
MCP方式
开发成本
每个工具单独对接，重复开发
一次开发，多处复用
兼容性
各平台接口不兼容
开放标准，跨平台通用
安全性
安全边界模糊
明确的权限控制和隔离
维护成本
高（每个集成都要维护）
低（社区共建，生态复用）
学习成本
高（每个工具API不同）
低（统一协议，学一次用到处）
⠀
1.2 MCP的发展历程
⠀
📌 信息来源：MCP官方文档 | GitHub公告 | 验证日期：2026-02-25
⠀
时间
里程碑事件
意义
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版本
当前最新稳定版本
2025年12月9日
MCP捐赠给Linux基金会AAIF
成为行业标准，OpenAI/Google/Microsoft等巨头支持
⠀
💡 重要事件：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服务器，让你立即看到效果！
⏱️ 预计时间：5-10分钟
⠀
2.1 配置第一个MCP服务器（Filesystem）
⠀
为什么选Filesystem？
⠀
-
✅ 最简单，不需要任何API Key
-
✅ 最常用，文件操作是开发基础
-
✅ 效果直观，立即看到结果
⠀
步骤1：创建配置文件
⠀
这一步要做什么：在项目根目录创建 .mcp.json 文件
⠀
💡 你有两种选择：
选择A：在Claude Code对话框里说人话（推荐新手）
帮我创建项目MCP配置文件 .mcp.json，配置一个filesystem服务器，允许访问当前目录
（换行用 Shift + Enter，最后按 Enter 发送）
Claude Code会自动帮你创建正确格式的配置文件！
选择B：在终端里用命令行（熟悉命令行的用户）
见下方PowerShell/Bash代码
⠀
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（注意开头有个点）
-
复制粘贴以下内容：
⠀
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
"env": {}
}
}
}
⠀
💡 配置说明：
-
"filesystem"：服务器名称，你可以自己起名
-
"command": "npx"：使用npx运行
-
"-y"：自动同意安装
-
"@modelcontextprotocol/server-filesystem"：官方Filesystem MCP包名
-
"."：允许访问的目录（当前目录）
⠀
步骤2：验证配置文件
⠀
验证方法：
⠀
# 查看配置文件内容
cat .mcp.json
# 预期输出：你刚才写入的JSON内容
# 验证JSON格式是否正确（需要安装jq，可选）
cat .mcp.json | jq .
# 如果格式正确，会输出格式化的JSON
# 如果格式错误，会报错
⠀
如果没有jq工具，可以用在线JSON验证器：https://jsonlint.com/
⠀
步骤3：启动Claude Code
⠀
这一步要做什么：重新启动Claude Code，让它读取新配置
⠀
# 在项目目录启动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工作正常
⠀
完整验证清单：
⠀
⠀
2.3 第一个MCP工具调用
⠀
恭喜你！ 如果上面的测试都成功了，你已经完成了MCP的基础配置。
⠀
你刚才完成了什么？
⠀
-
✅ 创建了MCP配置文件
-
✅ 连接了Filesystem MCP服务器
-
✅ 通过Claude Code调用了MCP工具
-
✅ 验证了MCP正常工作
⠀
接下来可以：
⠀
-
继续学习更多MCP服务器（第三部分）
-
了解MCP工作原理（第四部分）
-
开发自己的MCP服务器（第五部分）
第三部分：常用MCP服务器配置（实战为主）
⠀
本节目的：学会配置10+最常用的MCP服务器
⏱️ 预计时间：1-2小时
⠀
3.1 配置方式详解
⠀
方式1：JSON配置文件（推荐）
⠀
创建 .mcp.json 文件：
⠀
{
"mcpServers": {
"服务器名称1": {
"command": "启动命令",
"args": ["参数1", "参数2"],
"env": {
"环境变量名": "值"
}
},
"服务器名称2": {
...
}
}
}
⠀
配置字段说明：
⠀
字段
必需
说明
示例
command
✅
启动命令
"npx", "node", "python"
args
✅
命令参数数组
["-y", "@modelcontextprotocol/server-xxx"]
env
❌
环境变量对象
{"API_KEY": "xxx"}
timeout
❌
超时时间(毫秒)
60000
⠀
方式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命令
适合场景
团队项目、版本控制
快速测试、个人配置
可读性
高（结构清晰）
中
批量配置
方便（一个文件）
不便（逐个添加）
版本控制
支持
不支持
推荐度
⭐⭐⭐⭐⭐
⭐⭐⭐
⠀
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
# 应显示你的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
⠀
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字段
你：插入一条记录：张三，[email protected]
你：查询所有用户
⠀
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
⠀
💡 说明：query 是唯一的Tool。表结构信息（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）：
⠀
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_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 服务器可在运行时通过交互对话框向用户请求结构化输入
⠀
Elicitation 是 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 事件进行拦截和自定义处理。
⠀
远程 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格式。
⠀
三种消息类型
⠀
- 请求（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：方法参数（可选）
⠀
- 响应（Response）
⠀
成功响应：
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "文件内容..."
}
]
}
}
⠀
错误响应：
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Invalid Request",
"data": "详细错误信息"
}
}
⠀
- 通知（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 连接生命周期
⠀
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: 清理资源
第五部分：自定义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
⠀
修改 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);
⠀
验证开发环境
⠀
测试编译：
⠀
# 编译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 添加更多功能
⠀
添加第二个工具
⠀
在 src/index.ts 的工具列表中添加：
⠀
// 在 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": {}
}
}
}
第六部分：故障排查
⠀
本节目的：帮助你快速定位和解决MCP配置问题
⏱️ 预计时间：按需查阅
⠀
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
⠀
⠀
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：
-
MCP Server Finder：https://www.mcpserverfinder.com/
总结与检查清单
⠀
学习成果检查
⠀
完成本课后，你应该能够：
⠀
⠀
配置检查清单
⠀
在项目中使用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：资源链接
⠀
官方资源：
-
MCP官方文档：https://modelcontextprotocol.io/
-
MCP规范：https://modelcontextprotocol.io/specification/2025-11-25
-
Claude Code MCP文档：https://code.claude.com/docs/en/mcp
-
TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk
-
Python SDK：https://github.com/modelcontextprotocol/python-sdk
⠀
社区资源：
-
Awesome MCP Servers：https://github.com/punkpeye/awesome-mcp-servers
-
MCP Server Finder：https://www.mcpserverfinder.com/
-
MCP中文站：https://mcpcn.com/
📌 信息来源：
-
MCP官方文档 | 验证日期：2026-05-30
-
GitHub MCP Server仓库 | 验证日期：2026-05-30
-
Claude Code文档 | 验证日期：2026-05-30
⠀
作者：老金
更新日期：2026年5月30日
版本：V1.5（v2.1.158 release 摘录入差量）
字数统计：约3,500行 / 28,000字
适用版本：MCP规范 2025-11-25 / Claude Code v2.1.158