MCP集成完整指南：从配置到开发的实战手册

课程信息

作者：老金
GitHub：https://github.com/KimYx0207
公众号：老金带你玩AI
X（Twitter）：老金带你玩AI
个人博客：https://aiking.dev
预计学时：4-6小时
难度等级：⭐⭐ 入门级（有Claude Code基础即可）
更新日期：2026年10月3日
适用版本：MCP规范 2026-07-28 / Claude Code v2.1.270 为 2026-09-14 的历史参考；截至 2026-10-03 的新增行为按正文标注版本与官方文档
前置要求：已完成Claude Code安装和基础使用

本课学习目标

我讲 MCP 时会优先讲边界和证据来源，因为外部工具越强，越不能靠感觉授权。

完成本课学习后，你将能够：

理解MCP的核心价值：掌握MCP协议与传统AI工具集成方式的本质区别
配置常用MCP服务器：独立完成Filesystem、GitHub、数据库等10+核心服务器配置
掌握三作用域配置体系：理解Local/Project/User作用域的优先级和适用场景
排查MCP连接问题：解决大多数常见配置和连接故障
理解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.2：学习配置方式并连接GitHub MCP（30分钟）；3.3的数据库服务器已归档，仅作旧项目参考

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.2节的密钥配置 + 第七部分安全问题

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 版本说明 | 规范正式发布记录 | 核查日：2026-09-14

时间

里程碑事件

意义

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，以官方 versioning 页为准）

💡 重要事件：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. [调用] issue_write(method="create", owner=owner, repo=repo, title=title, body=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(libraryName="next.js", query="Next.js 15 App Router怎么用")
2. [调用] query-docs(libraryId="/vercel/next.js", query="Next.js 15 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

启动后检查连接：

项目级 .mcp.json 可能先请求你批准服务器。确认来源后，在会话中输入 /mcp，查看 filesystem 的状态和工具列表；不要用某个固定版本的欢迎屏幕或固定工具数量判断是否成功。也可以在终端运行 claude mcp get filesystem 查看状态。

如果看不到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 文件存在且格式正确
已在 /mcp 核对服务器状态，并完成需要的项目批准或认证
能成功执行 list_directory 工具
能成功执行 read_file 工具
能成功执行 write_file 工具；是否询问确认取决于当前权限模式、规则和已有授权

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

❌

stdio 启动参数数组；没有参数时可省略

["-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命令

适合场景

团队项目、版本控制

快速测试、个人配置

可读性

高（结构清晰）

中

批量配置

方便（一个文件）

不便（逐个添加）

版本控制

project 配置可提交 Git

--scope project 同样写入可提交 Git 的 .mcp.json

推荐度

⭐⭐⭐⭐⭐

⭐⭐⭐

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')

# User 作用域不会刷新当前终端的环境，先同步到本次会话
$env:GITHUB_PERSONAL_ACCESS_TOKEN = [System.Environment]::GetEnvironmentVariable('GITHUB_PERSONAL_ACCESS_TOKEN', 'User')

# 只检查是否有值，避免把完整 token 打到终端
[bool]$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": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${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

issue_write

创建或更新 Issue

参数以 /mcp 中当前工具定义为准

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 MCP 服务器已移入 modelcontextprotocol/servers-archived，不再维护；包名和工具名可用来理解旧项目配置，但不应据此选作新项目的维护基线。需要安装 uv，并确认数据库目录存在。

配置方法：

{
  "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作用域（让 CLI 保存项目私有配置）：

在目标项目目录执行：

claude mcp add --scope local --transport http github https://api.githubcopilot.com/mcp/

再在交互会话的 /mcp 中完成该服务支持的认证。CLI 会把配置保存到 ~/.claude.json 的 projects[项目绝对路径].mcpServers；不要把项目路径直接放进根级 mcpServers，也不要在教程跟练时改写整个用户配置文件。

Project作用域（项目根目录 .mcp.json）：沿用前面 GitHub MCP 的 .mcp.json 写法，把配置放到项目根目录，适合团队共享服务器声明；密钥仍然通过环境变量注入，不要把 token 写进仓库。

User作用域（使用CLI）：

claude mcp add --scope user --transport http github https://api.githubcopilot.com/mcp/
# 在 /mcp 中按当前服务的认证提示完成登录

3.5 更多常用服务器配置

Brave Search（网页搜索）

功能：隐私优先的 Web 搜索；使用前在 Brave 账号面板确认当前套餐、免费额度和计费。

获取API Key：

访问 https://brave.com/search/api/
注册账号
创建API Key
核对当前套餐和免费 credits，不要按旧的固定查询次数估算费用

配置方法：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "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(libraryName="react", query="React 19有哪些新特性")
2. [调用] query-docs(libraryId="/facebook/react", query="React 19有哪些新特性")
3. [返回] React 19新特性包括：...

注意：Context7 推荐使用免费 API Key，以取得更高的请求限额。具体额度和计费以当前账号面板为准；添加 Key 也不代表可以无限调用。工具名与参数可在 /mcp 中核对。

MCP Apps（交互式界面）

功能：MCP 服务器可提供交互式用户界面，直接在聊天中渲染图表、表单、仪表盘

MCP Apps 让服务器提供可交互的 UI 资源，但界面能否显示取决于宿主客户端。当前 Claude Code MCP 文档说明，ui:// 或 text/html;profile=mcp-app 资源不会出现在 @ 建议或资源列表工具的结果里；按 URI 读取仍可用。不要把协议支持 UI 理解成终端对话会直接渲染图表和表单。

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 服务器的工具几乎每次会话都会用到，可以设 alwaysLoad: true，通常让工具定义提前进入上下文，省去搜索发现的步骤。服务器仍需成功连接；从 v2.1.285 起，单个工具声明 _meta["anthropic/alwaysLoad"]: false 时，该工具仍会延迟加载：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {"Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"},
      "alwaysLoad": true
    }
  }
}

alwaysLoad: true：通常提前加载该服务器的工具定义；单个工具显式声明 _meta["anthropic/alwaysLoad"]: false 时，仍通过工具搜索发现
不设：沿用当前工具搜索策略
alwaysLoad: false：从 v2.1.287 起，让该服务器的全部工具通过工具搜索发现

工具搜索默认开启，但模型、服务提供方、组织设置或环境变量可能关闭它；这时工具定义会提前加载。alwaysLoad 控制工具定义，不能用它推断服务器进程每次调用后是否关闭。

适用场景：高频使用的核心 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 事件进行拦截和自定义处理。

需要到浏览器完成时，用 URL 模式。服务器也可以请求你打开链接，在网页里完成登录或其他流程：

查看 Claude Code 显示的网址和用途，再决定是否打开。
在浏览器里完成操作；这一步不是在终端表单中输入答案。
如果服务器不能自动通知完成，回到 Claude Code，选择 I'm done, continue，工具调用才继续。v2.1.288 增加这段等待，避免网页还没完成就往下跑。

v2.1.281 先支持 MCP 2026-07-28 连接的 URL 请求，v2.1.287 又补了2025-11-25协议。若服务器在此次升级后无法连接，官方发布记录给出了在该服务器配置项中设置 "bareElicitationCapability": true 的兼容办法；只在确认对应协议问题时使用，不要给全部服务器盲目加开关。

普通OAuth认证也可能在一次工具调用中要求更多权限。看到重新认证提示时先检查新增 scope，再在 /mcp 中完成认证后重试；不要把所有这种情况当成 token 过期。表单与URL两种流程见官方MCP交互请求，最近的等待/兼容变化见官方2.1.287–288记录。

远程 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（浏览器自动化）

历史参考：这个 Puppeteer 参考服务器提供网页截图、表单填写等功能，但已经归档，不再维护。新项目先选择维护中的浏览器服务器，下面的包名只用于识别旧配置。

配置方法：

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
      "env": {}
    }
  }
}

3.6 完整配置示例

组合配置示例（.mcp.json）：先安装 uv / Node.js，创建实际要访问的目录，并设置对应环境变量。SQLite 是已归档的历史示例，可删除其条目；其他服务器也应按任务挑选。已有 .mcp.json 时合并条目，不要覆盖原配置。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./docs", "./data"],
      "env": {}
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${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", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "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 连接生命周期

先看协议版本（核查日：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 的兼容范围；规范的最新版本不代表所有客户端已经默认采用它。实现新协议或维护旧握手时，分别对照版本协商与向后兼容说明。

第五部分：自定义MCP开发（进阶可选）

先区分两种服务器：这里开发的是普通 MCP 服务器，用 stdio 或 HTTP 等传输连接；Agent SDK章节的内置工具服务器则由宿主程序注册。从 v2.1.274 起，在 .mcp.json、settings、插件或agent定义文件里写 "type": "sdk" 会被跳过并给警告，不能用它代替宿主注册。

本节目的：学会开发自己的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：下面展示完整示例；安装依赖后，保留 npm 实际写入的依赖版本和 lockfile，主要合并 type、入口及 scripts。若整份替换，请再运行 npm install 同步依赖，不要只改版本声明后直接构建。

{
  "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": "npm run build && node dist/index.js",
    "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 服务器。当前 v2 需要 Node.js 22.19.0 或更高；前面 SDK 示例的 Node 18 最低要求不足以运行当前 Inspector，先检查 node --version。

使用方法：

# 调试自己的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 处理器内、throw new Error(未知工具) 那个兜底分支之前添加以下代码。修改后重新运行 npm run build，再重启自定义服务器或会话，否则 dist/index.js 仍是上一次编译的内容：

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

把两个 schema 导入合并到文件顶部；将现有 Server 的 capabilities 增加 resources: {}，不要再声明第二个同名 server。再把两个资源处理器放到 main() 调用之前，重新编译并重启服务器。下面的 const server 展示的是原有初始化代码的替换位置：

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

下面只列发布相关字段，保留5.1节的 type: "module"、scripts、dependencies 和 devDependencies。不要用这份片段替换整个文件，否则 npm run build 和运行时依赖会丢失。

{
  "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 日志

让 CLI 把本次排障日志写到你指定的文件：

claude --debug-file ./claude-mcp-debug.log

在会话里用 /mcp 查看状态，再读取这份日志定位连接错误。macOS / Linux 可用 tail -f ./claude-mcp-debug.log；PowerShell 可用 Get-Content ./claude-mcp-debug.log -Wait。这里使用 Claude Code CLI 的日志，不沿用 Claude Desktop 的 Claude/mcp*.log 路径；分享日志前检查其中的项目内容和连接信息。

调试模式启动

# 开启MCP调试日志
claude --debug=mcp

6.4 重置MCP配置

先用 claude mcp list / claude mcp get <name> 确认服务器来自哪个作用域，再只移除要重配的条目：

# 例：移除当前项目的私人配置，不影响其他服务器
claude mcp remove --scope local github

# 仅重置当前项目 .mcp.json 的批准选择
claude mcp reset-project-choices

--scope 可选 local、project 或 user，按实际来源选择。若要重配共享 .mcp.json，先备份文件并仅编辑相应条目。不要删除整个 ~/.claude.json：它还保存其他项目配置、偏好和状态，删除它并不是只重置 MCP。

第七部分：FAQ（20个常见问题）

基础问题

Q1：MCP和普通API有什么区别？

A：MCP是协议标准，API是具体实现。

对比

MCP

普通API

定位

通用协议标准

具体服务接口

兼容性

跨平台、跨AI

仅特定服务

学习成本

学一次用到处

每个API都不同

类比

USB标准

某品牌的USB设备

Q2：MCP服务器需要一直运行吗？

A：要区分连接方式。stdio 服务器通常作为 Claude Code 管理的子进程运行；HTTP 等远程服务由服务方独立运行。部分有缓存的远程服务器会显示 cached，在第一次工具调用时连接，但不能因此推断每次调用后都会关闭。用 /mcp 查看实际连接状态，结束会话与单次工具调用也不是同一个生命周期。

Q3：配置多个MCP服务器会影响性能吗？

A：可能影响。服务器连接、子进程、工具发现与加载都可能消耗时间和资源；工具搜索可以减少工具定义占用的上下文，部分缓存的远程服务也能延后连接，但这些机制不等于零开销。先看 /mcp 的状态和工具数量，再关闭本次任务不需要的服务器。

Q4：MCP服务器的数据安全吗？

A：取决于配置。

Filesystem 参考服务器限制访问它当前允许的目录；支持 Roots 的客户端提供 Roots 后，会替换启动参数中的允许目录，可用 list_allowed_directories 核对。Claude Code 的 /add-dir 等操作也会改变提供给服务器的 Roots
是否逐次询问确认取决于权限模式、规则和已有授权；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：要区分部署方式。HTTP 服务由服务方更新；本地 npx 启动的包会受版本声明、本地安装和缓存影响，不保证每次启动自动更新。若要跟随发布者的最新稳定标签，在配置里使用明确的 @latest，例如：

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem@latest", "."]
}

核对版本和变更后重新连接或重启。需要可重复部署时固定具体版本；自行开发的服务器应更新源码、安装依赖并重新构建。不要为了更新一个包就运行来源不明的清缓存包或删除整片缓存目录。

开发问题

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：MCP 协议不会统一限制所有服务器的文件权限。本课的 Filesystem 参考服务器按当前允许目录检查访问；客户端提供 Roots 时，会替换命令行配置的目录。用它的 list_allowed_directories 核对实际范围，其他服务器要看各自的实现。

其他问题

Q19：MCP支持哪些AI工具？

A：已支持：

Claude Desktop
Claude Code
VS Code + Continue
Cursor
Zed
以及更多支持MCP协议的工具

Q20：哪里找更多MCP服务器？

A：

官方仓库：https://github.com/modelcontextprotocol/servers
Awesome列表：https://github.com/punkpeye/awesome-mcp-servers
MCP Server Finder：https://www.mcpserverfinder.com/

总结与检查清单

学习成果检查

完成本课后，你应该能够：

理解MCP价值：能向他人解释MCP是什么、为什么重要
配置基础MCP：成功配置Filesystem MCP并调用工具
配置GitHub MCP：正确设置Token并管理仓库
配置数据库MCP：连接SQLite或PostgreSQL
理解三作用域：知道Local/Project/User的区别和使用场景
排查常见问题：能独立解决配置和连接错误
开发简单MCP：能创建包含Tool的MCP服务器（可选）

配置检查清单

在项目中使用MCP前，确认：

.mcp.json 文件存在且格式正确
所需环境变量已配置
API Key安全存储（不在配置文件中硬编码）
已在 /mcp 核对服务器状态，并完成需要的项目批准或认证
至少测试过一个MCP工具调用

附录

附录A：组合.mcp.json模板

先安装所需的 Node.js / uv，创建配置中实际使用的目录，并设置环境变量。SQLite 和 Puppeteer 条目是已归档的历史示例，不作为新项目推荐；按需求删去不用的服务器。已有 .mcp.json 时合并条目，不要覆盖原配置。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src", "./docs"],
      "env": {}
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${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", "@brave/brave-search-mcp-server", "--transport", "stdio"],
      "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 --debug=mcp

调试模式启动

claude --debug=mcp

⭐

⚠️ 重要澄清：claude mcp test 和 claude mcp restart 命令不存在。claude mcp get <name> 用于检查状态，实际调用一个工具才能验证功能。当前交互会话可在 /mcp 中选择 Reconnect；v2.1.284 起终端支持 /mcp reconnect all 重试失败或需认证的服务器。修改配置后按提示重连，必要时退出并重启。

附录C：参考服务器与维护者服务

这张表用于识别包名和来源。modelcontextprotocol 的参考实现用于教学，不等于生产服务保证；GitHub、GitLab、SQLite、PostgreSQL、Puppeteer 旧参考实现已归档。

服务器

包名

功能

重要

Filesystem

@modelcontextprotocol/server-filesystem

文件系统操作

⭐

GitHub

https://api.githubcopilot.com/mcp/

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

@brave/brave-search-mcp-server

Brave 维护的网页搜索服务；使用 stdio 时传 --transport stdio

⭐

Context7

@upstash/context7-mcp

技术文档

⭐

附录D：资源链接

官方资源：

MCP官方文档：https://modelcontextprotocol.io/
MCP规范（本轮教程基线）：https://modelcontextprotocol.io/specification/2026-07-28
MCP规范（上一版，保留作历史）：https://modelcontextprotocol.io/specification/2025-11-25
Claude Code MCP文档：https://code.claude.com/docs/en/mcp
官方服务器仓库：https://github.com/modelcontextprotocol/servers
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-10-03
Claude Code文档 | 验证日期：2026-05-30

作者：老金
更新日期：2026年10月3日
版本：V1.6（v2.1.270 release 摘录入差量）
字数统计：约3,500行 / 28,000字
适用版本：MCP规范 2026-07-28 / Claude Code v2.1.270