Claude Code MCP 集成完整指南:从协议原理到自定义服务器开发实战

原创2026-10-09 10:15:161,713 阅读
文章标签:人工智能教程文档示例工程

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

  1. 登录 GitHub.com
  2. 点击右上角头像 → Settings
  3. 左侧菜单最下方 → Developer settings
  4. Personal access tokens → Tokens (classic)
  5. Generate new token (classic)
  6. 勾选权限:✅ repo(完整仓库访问)、✅ workflow(如需管理 Actions)
  7. 点击 Generate token
  8. 立即复制保存 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 监控调用:可通过 PreToolUse Hook(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 工具调用

推荐下一步

  1. 配置更多服务器:根据你的开发需求,配置 Context7、Brave Search 等
  2. 深入学习:阅读 MCP 官方文档了解更多高级特性
  3. 开发自定义 MCP:将你的常用工具封装成 MCP 服务器
  4. 参与社区:在 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 规范 2026-07-28 / Claude Code v2.1.270(验证于 2026-09-14)。版本号会随上游更新而失效,遇到界面、命令或参数不一致时,优先查官方更新日志、官方文档和 CLI 帮助(--help),并以本机 claude --version 输出为准。

登录后查看全文
AI-Coding-Guide-Zh