Claude Code MCP 使用教程

MCP（Model Context Protocol）是 Claude Code 官方推出的开源标准协议，核心作用是搭建 Claude Code 与外部工具、API、数据库、设计平台等系统的安全连接桥梁，打破 AI 与外部资源的协作壁垒。通过 MCP，开发者无需切换多个工具，即可用自然语言让 Claude Code 调用外部能力，完成跨系统自动化工作流，大幅提升 AI 辅助开发的效率与场景覆盖度。

本教程将从核心概念、接入方式、配置管理、实战场景到问题排查，结合具体代码示例，手把手教你掌握 MCP 的完整使用流程，所有操作均经过实测验证，兼顾易用性与专业性，总字数控制在3000字以内，适合各类开发场景参考。

一、MCP 核心概述与价值

简单来说，MCP 就是 Claude Code “连接外部世界的 USB 接口”——它定义了统一的通信标准，让 Claude Code 能够无缝对接各类外部服务，无需关注不同工具的接口差异，实现“一次配置，全程复用”。截至2026年4月，MCP 生态已拥有4000+ 可用服务器，每月 SDK 下载量超9700万，半年增长率达232%，成为 Claude Code 扩展能力的核心支撑。

1.1 核心价值

• 打通工具壁垒：无需切换界面，即可让 Claude Code 调用 GitHub、JIRA、Sentry、PostgreSQL、Figma 等工具，实现“自然语言操作全流程”。

• 提升协作效率：支持团队共享 MCP 配置，统一工具环境，避免重复配置，尤其适合多人协作开发场景。

• 扩展 AI 边界：让 Claude Code 突破内置能力限制，实现实时数据查询、报错分析、代码生成、工单管理等复杂操作。

• 安全可控：提供三级作用域隔离、企业级权限管控，支持白名单/黑名单配置，兼顾灵活性与安全性。

1.2 与 Agent Skills 的区别

很多开发者会混淆 MCP 与 Agent Skills，两者核心定位不同，搭配使用可最大化 Claude Code 能力，具体区别如下：

对比维度	MCP	Agent Skills
核心本质	外部工具连接协议	AI 能力扩展包（预设工作流）
工作方式	实时调用外部服务	加载预设知识/流程指导 AI 行为
典型场景	连接 GitHub、数据库、Sentry	代码优化、性能调试、流程标准化
配置复杂度	需配置服务器、认证、环境变量	安装即用，零配置或简单配置

一句话总结：Skills 让 Claude Code 更“聪明”（懂方法），MCP 让 Claude Code 更“能干”（能操作外部工具）。

1.3 MCP 服务器接入与使用流程图

二、三种 MCP 服务器接入方式

MCP 支持三种传输方式，覆盖远程云服务与本地进程两种核心场景，其中 SSE 方式已被官方弃用，优先推荐 HTTP 和 stdio 方式，以下是详细接入步骤与示例。

2.1 HTTP 远程服务器（推荐）

适用于云端 MCP 服务（如 GitHub、Notion、Sentry 官方 MCP 服务），是官方推荐的远程接入方式，支持请求头授权、环境变量配置，稳定性高、适配性广。

基础语法

claude mcp add --transport http <server-name> <url>

实操示例

# 示例1：连接 Notion MCP 服务器
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 示例2：连接 Sentry MCP 服务器（带 Bearer 令牌授权）
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp \
  --header "Authorization: Bearer your-token"

# 示例3：连接 Context7（查询最新框架文档，内置可直接使用）
claude mcp add --transport http context7 https://mcp.context7.com/mcp

Context7 是 Claude Code 常用的 MCP 服务器，可实时查询 React、Next.js、Tailwind 等框架的最新官方文档，解决 AI 训练数据过时的问题。

2.2 SSE 远程服务器（已弃用）

SSE（Server-Sent Events）传输方式已被官方弃用，现有配置建议尽快迁移至 HTTP 方式，仅保留兼容旧配置的示例，不推荐新配置使用。

# 仅兼容旧配置，不推荐新使用
claude mcp add --transport sse asana https://mcp.asana.com/sse

2.3 stdio 本地服务器

适用于本地进程、自定义脚本、本地数据库等需要访问系统资源的场景，通过本地命令启动 MCP 服务器，与 Claude Code 进行进程间通信，安全性高，适合本地开发调试。

基础语法

claude mcp add [选项] <server-name> -- <command> [args...]

关键规则

• --transport/--env/--header 等选项必须在服务器名称之前，否则会报错。

• -- 用于分隔 Claude 参数与服务器命令，避免命令冲突，不可省略。

• Windows 系统必须用 cmd /c 包装命令，否则会出现连接失败问题。

实操示例

# 示例1：连接 Airtable 本地服务器（带环境变量）
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# 示例2：连接本地文件系统 MCP（限制访问目录）
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

# 示例3：Windows 系统连接本地服务器（必须加 cmd /c）
claude mcp add --transport stdio my-local-server -- cmd /c npx -y @some/package

# 示例4：连接 PostgreSQL 本地数据库
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres "postgresql://user:password@localhost:5432/mydb"

本地文件系统 MCP 是前端开发者常用的功能，可让 Claude Code 直接读取、修改、创建项目文件，实现“说话就能改代码”的高效开发体验。

三、MCP 服务器管理命令

配置 MCP 服务器后，可通过一系列 CLI 命令进行管理，包括查看、删除、重置等，所有命令简洁易懂，以下是高频命令汇总，可直接复制使用。

# 1. 列出所有已配置的 MCP 服务器（显示作用域、传输方式、状态）
claude mcp list

# 2. 查看指定服务器的详细配置（如查看 github 服务器）
claude mcp get github

# 3. 删除指定服务器（如删除 airtable 服务器）
claude mcp remove airtable

# 4. 会话内查看 MCP 状态与认证信息（常用，用于解决认证失败问题）
> /mcp

# 5. 重置项目范围服务器的授权（解决项目级服务器无法使用的问题）
claude mcp reset-project-choices

# 6. 检查 MCP 连接状态（排查连接失败）
claude-code --mcp-status

# 7. 查看 MCP 调试日志（定位连接失败原因）
claude-code --mcp-debug

补充说明：Claude Code 支持 MCP list_changed 通知，当 MCP 服务器的工具、资源更新时，会自动刷新配置，无需手动重连。

四、MCP 作用域与配置存储

MCP 支持三级作用域（scope），用于控制服务器配置的适用范围，优先级为：local（本地） > project（项目） > user（用户），同名服务器高优先级会覆盖低优先级配置，灵活适配个人与团队使用场景。

4.1 三级作用域详细说明

作用域类型	适用范围	存储位置	典型场景
local（默认）	仅当前项目	~/.claude.json	个人实验、敏感凭据配置、临时测试
project（项目级）	当前项目所有成员	项目根目录 .mcp.json（可提交 Git）	团队共享工具（如项目数据库、Sentry）
user（用户级）	当前用户所有项目	~/.claude.json	个人高频工具（如 Notion、个人邮箱）

4.2 作用域配置示例

# 1. 配置 local 作用域（默认，仅当前项目可用）
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# 2. 配置 project 作用域（团队共享，提交 Git）
claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp

# 3. 配置 user 作用域（全局可用，所有项目均可调用）
claude mcp add --transport http notion --scope user https://mcp.notion.com/mcp

4.3 环境变量扩展

项目级配置文件 .mcp.json 支持环境变量替换，可适配不同设备、不同环境的配置差异，避免敏感凭据明文写入配置文件，提升安全性。

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp", // 默认值 fallback
      "headers": {"Authorization": "Bearer ${API_KEY}"} // 环境变量注入凭据
    }
  }
}

五、MCP 核心功能：资源引用与斜杠命令

配置好 MCP 服务器后，可通过资源引用（@ 语法）和 MCP 斜杠命令，快速调用外部工具能力，无需复杂指令，自然语言即可触发。

5.1 资源引用（@ 语法）

MCP 资源可像本地文件一样用 @ 符号引用，格式为：@服务器名:资源类型://路径，支持直接关联外部数据，让 Claude Code 快速获取外部信息。

实操示例

# 示例1：分析 GitHub Issue #123，提出修复建议
> Can you analyze @github:issue://123 and suggest a fix?

# 示例2：查询 React useEffect 的最新用法（通过 Context7）
> @context7 查询 React useEffect 的最新用法

# 示例3：对比数据库 users 表结构与文档
> Compare @postgres:schema://users with @docs:file://database/user-model

# 示例4：读取本地组件文件（通过 filesystem MCP）
> 读取 @filesystem:file://src/components/Button.tsx 的内容

其中，Context7 的资源引用的是前端开发者常用功能，可实时获取框架最新文档，避免依赖 AI 过时的训练数据。

5.2 MCP 斜杠命令

MCP 服务器的预设提示会自动转为斜杠命令，格式为：/mcp__服务器名__命令名，可直接在 Claude Code 会话中调用，快速执行特定操作。

实操示例（GitHub MCP）

# 1. 列出所有 PR
> /mcp__github__list_prs

# 2. 查看 PR #456 详情
> /mcp__github__get_pr 456

# 3. 审查 PR #456 并提出改进建议
> /mcp__github__review_pr 456

# 4. 创建新 PR
> /mcp__github__create_pr "feat: 添加暗色模式"

这些命令可大幅减少开发者在 GitHub 网页与 Claude Code 之间的切换成本，提升 PR 管理效率。

六、插件内置 MCP 服务器与企业托管配置

MCP 支持插件内置配置与企业级管控，适配团队协作与企业安全需求，无需手动配置即可使用插件自带的 MCP 服务器，同时企业可集中管控权限，防止未授权工具接入。

6.1 插件内置 MCP 服务器

很多 Claude Code 插件会捆绑 MCP 服务器，启用插件后会自动加载对应的 MCP 配置，无需手动添加，极大简化配置流程。

插件配置示例

# 示例1：插件根目录 .mcp.json 配置
{
  "database-tools": {
    "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
    "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
    "env": {"DB_URL": "${DB_URL}"}
  }
}

# 示例2：plugin.json 内联 MCP 配置
{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

补充说明：插件 MCP 服务器的生命周期与插件一致，启用插件则加载，禁用插件则停止，支持所有 MCP 传输方式。

6.2 企业托管 MCP 配置

企业可通过 managed-mcp.json 配置文件和策略管控，集中管理 MCP 服务器，限制未授权工具接入，保障企业数据安全。

6.2.1 独占管控（managed-mcp.json）

系统级配置文件，用户无法修改，用于强制固定企业内可用的 MCP 服务器列表，不同系统的存储路径如下：

• macOS：/Library/Application Support/ClaudeCode/managed-mcp.json

• Linux：/etc/claude-code/managed-mcp.json

• Windows：C:\Program Files\ClaudeCode\managed-mcp.json

{
  "mcpServers": {
    "github": {"type": "http", "url": "https://api.githubcopilot.com/mcp/"},
    "sentry": {"type": "http", "url": "https://mcp.sentry.dev/mcp"}
  }
}

6.2.2 策略管控（白名单/黑名单）

通过 allowedMcpServers（白名单）和 deniedMcpServers（黑名单），按服务器名称、命令、URL 通配符限制可用服务器，拒绝列表优先级高于白名单。

{
  "allowedMcpServers": [
    {"serverName": "github"}, // 允许名称为 github 的服务器
    {"serverCommand": ["npx", "-y", "approved-server"]}, // 允许指定命令的服务器
    {"serverUrl": "https://mcp.company.com/*"} // 允许指定域名的服务器
  ],
  "deniedMcpServers": [
    {"serverName": "dangerous-server"}, // 禁止指定名称的服务器
    {"serverUrl": "https://*.untrusted.com/*"} // 禁止指定域名的服务器
  ]
}

七、认证、导入与同步

MCP 支持 OAuth2 认证、JSON 配置导入、Claude Desktop 同步等功能，解决敏感凭据管理、配置迁移等问题，提升使用便捷性。

7.1 远程服务器 OAuth 认证

大部分远程 MCP 服务器（如 GitHub、Sentry）需要 OAuth2 认证，认证流程简单，会话内即可完成，令牌会安全存储并自动刷新。

# 1. 添加需要认证的 MCP 服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 会话内执行 /mcp 命令，按照提示完成认证
> /mcp

# 3. 清除授权（如需更换账号）
> /mcp clear-auth sentry

7.2 JSON 配置导入

可直接通过 JSON 配置快速添加 MCP 服务器，适合批量配置、迁移配置场景，支持 HTTP 和 stdio 两种传输方式。

# 示例1：导入 HTTP 服务器配置
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# 示例2：导入 stdio 服务器配置
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

7.3 从 Claude Desktop 导入

支持从 Claude Desktop 导入已配置的 MCP 服务器，仅适用于 macOS 和 WSL 系统，导入后可通过 --scope user 设为全局可用。

claude mcp add-from-claude-desktop

# 导入后设为用户级全局可用
claude mcp add-from-claude-desktop --scope user

7.4 将 Claude Code 作为 MCP 服务器

可将 Claude Code 自身作为 MCP 服务器，供其他应用（如 Claude Desktop）调用，实现跨应用协作。

# 1. 启动 Claude Code MCP 服务
claude mcp serve

# 2. Claude Desktop 配置（连接 Claude Code MCP 服务器）
{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"]
    }
  }
}

八、实战集成示例（高频场景）

结合开发高频场景，整理4个实用 MCP 集成示例，所有命令均经过实测，可直接复制实操，快速上手 MCP 功能。

8.1 接入 Sentry 分析线上报错

# 1. 添加 Sentry MCP 服务器
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 会话内完成认证
> /mcp

# 3. 自然语言查询报错
> What are the most common errors in the last 24 hours?
> 分析最近24小时最频繁的报错，并给出解决方案

8.2 接入 GitHub 管理 PR/Issue

# 1. 添加 GitHub MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 2. 会话内完成认证
> /mcp

# 3. 常用操作示例
> /mcp__github__list_prs # 列出所有 PR
> /mcp__github__review_pr 456 # 审查 PR #456
> 总结 PR #456 的变更内容，分析对前端组件库的影响

8.3 接入 PostgreSQL 查询数据

# 1. 安装 PostgreSQL MCP 服务器依赖
npm install -g @modelcontextprotocol/server-postgres

# 2. 添加本地 PostgreSQL MCP 服务器
claude mcp add --transport stdio db -- npx -y @modelcontextprotocol/server-postgres \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

# 3. 自然语言查询数据
> What's our total revenue this month?
> 查询本月用户注册量，按日期分组展示

8.4 接入本地文件系统管理代码

# 1. 添加本地文件系统 MCP 服务器
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem ./src

# 2. 常用操作示例
> 列出 src/components 下的所有文件
> 在 Button.tsx 中添加 hover 样式
> 重构 src/components 下的所有 Button 组件，将 onClick 改为 onPress
> 为 src/hooks/useLocalStorage.ts 生成测试用例

本地文件系统 MCP 可实现批量组件重构、代码溯源、自动生成测试等功能，大幅提升前端开发效率。

九、常见问题与优化配置

使用 MCP 过程中，可能会遇到连接失败、认证失败、输出超限等问题，以下是高频问题的排查方法与解决方案，结合真实案例优化，覆盖 Windows 系统特有问题。

9.1 常见故障排查

• 问题1：MCP 服务器连接失败原因：协议版本不匹配、配置文件冲突、端口占用、Windows 路径格式错误。解决方案：`# 1. 检查 MCP 协议版本（Claude Code 0.48+ 要求 v2.0）
  npm ls @modelcontextprotocol/sdk
  npm update @modelcontextprotocol/sdk@latest # 升级版本

2. 检查配置文件冲突（删除旧配置）

rm -rf ~/.claude/cache/*
claude-code --reset-mcp # 重置 MCP 配置

3. 检查端口占用（默认 3000-3010）

netstat -an | grep 300 # 查看端口占用

重新配置时指定端口

claude mcp add --transport http my-server --header "Port: 3100" https://api.example.com/mcp

4. Windows 路径错误（使用双反斜杠或正斜杠）

错误：C:\Users\name\project

正确：C:\\Users\\name\\project 或 C:/Users/name/project`

• 问题2：Windows stdio 连接失败原因：未用 cmd /c 包装命令，权限不足。解决方案：`# 必须用 cmd /c 包装命令
  claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

避免安装在 Program Files 目录（需管理员权限）

推荐安装路径：C:/Users/(username)/AppData/Local/claude-mcp/`

• 问题3：认证失败原因：令牌过期、认证信息错误。解决方案：会话内执行 /mcp clear-auth 服务器名，清除授权后重新登录。

• 问题4：项目级服务器无法使用解决方案：执行 claude mcp reset-project-choices，重置项目范围服务器授权。

9.2 优化配置

• 输出令牌限制：MCP 输出超 10000 令牌触发警告，可通过环境变量扩容：
  export MAX_MCP_OUTPUT_TOKENS=50000 # 临时扩容（当前会话有效） echo "export MAX_MCP_OUTPUT_TOKENS=50000" >> ~/.bashrc # 永久扩容（Linux/macOS）

• 启动超时配置：默认超时时间较短，可调整超时时间：
  MCP_TIMEOUT=10000 claude # 超时时间设为 10 秒

• 中文路径问题：Windows 中文版系统默认 GBK 编码，导致中文路径解析失败，解决方案：
  `# 切换到 UTF-8 代码页（Windows）
  chcp 65001

创建英文符号链接指向中文目录

mklink /D C:\mcp-workspace "C:\工作空间\项目"

配置中使用英文路径 C:\mcp-workspace`

9.3 安全最佳实践

• 远程服务优先使用 HTTP + OAuth 认证，避免明文密钥写入配置文件。

• 敏感凭据使用环境变量注入，不直接写入 .mcp.json 或 ~/.claude.json。

• 企业环境启用 managed-mcp.json 和策略管控，限制未授权 MCP 服务器接入。

• 本地 MCP 服务器采用最小权限运行，不分配高危系统权限。

十、总结

MCP 作为 Claude Code 连接外部工具的核心协议，通过统一的接入方式、灵活的作用域管理、丰富的实战场景，彻底打破了 AI 与外部系统的协作壁垒。本教程覆盖了 MCP 的核心功能与实操流程，从基础的服务器接入、命令管理，到高级的企业管控、实战集成，再到常见问题排查，适合各类开发者快速上手。

日常使用建议：优先选择 HTTP 远程服务器（稳定、适配广）和 project 作用域（团队共享），结合 Context7、GitHub、本地文件系统等高频 MCP 服务器，搭配 Agent Skills，可最大化提升开发效率。对于企业用户，重点关注企业托管配置与安全管控，保障数据安全与团队协作规范。

MCP 的使用没有固定标准，关键是适配自身开发场景与团队需求，持续优化配置，逐步构建属于自己的 AI 辅助开发工具链，让 Claude Code 真正成为高效开发的“得力助手”。