以前查Bug要切5个工具，现在Claude Code MCP一句话搞定，降维打击！Claude Code MCP 使用教

Claude Code MCP 使用教程

MCP（Model Context Protocol）是 Claude Code 连接外部世界的核心协议——通过它，你可以用自然语言让 Claude Code 直接操作 GitHub、Sentry、PostgreSQL、Figma 等外部服务，无需切换工具，实现跨系统自动化工作流。截至2026年4月，MCP 生态已拥有4000+ 可用服务器，每月 SDK 下载量超9700万，成为 Claude Code 扩展能力的核心支撑。

本教程从核心概念、接入方式、配置管理、实战场景到问题排查，结合具体代码示例，帮你掌握 MCP 的完整使用流程。

一、MCP 核心概述与价值

简单来说，MCP 就是 Claude Code “连接外部世界的 USB 接口”——它定义了统一的通信标准，让 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 服务器接入与使用流程图

flowchart TD
    A[添加 MCP 服务器] --> B{选择传输方式}
    B -->|HTTP 远程| C["claude mcp add --transport http <name> <url>"]
    B -->|stdio 本地| D["claude mcp add --transport stdio <name> -- <command>"]
    
    C --> E[配置认证 OAuth/Token]
    D --> F[配置环境变量/参数]
    
    E --> G[验证连接: /mcp]
    F --> G
    
    G --> H{连接成功?}
    H -->|是| I[使用 MCP 资源]
    H -->|否| J[排查问题]
    J --> K[检查配置/网络/认证]
    K --> G
    
    I --> L["@服务器名:资源路径 引用资源"]
    I --> M["/mcp__服务器名__命令 调用命令"]

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

理解了 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 服务器后，日常管理同样重要——查看状态、删除配置、重置授权，以下命令覆盖高频管理场景。

配置 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 提供两种核心调用方式——资源引用（@ 语法）和斜杠命令，无需复杂指令，自然语言即可触发。

配置好 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 配置，以及企业级集中管控。

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 的日常使用还涉及 OAuth 认证、配置迁移等操作，本节覆盖这些实用功能。

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"]
    }
  }
}

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

以上是 MCP 的完整使用流程，接下来通过4个高频场景，将上述知识串联为可直接复用的实操方案。

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 协议版本（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

# 必须用 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 令牌触发警告，可通过环境变量扩容： bash export MAX_MCP_OUTPUT_TOKENS=50000 # 临时扩容（当前会话有效） echo "export MAX_MCP_OUTPUT_TOKENS=50000" >> ~/.bashrc # 永久扩容（Linux/macOS）
启动超时配置：默认超时时间较短，可调整超时时间： MCP_TIMEOUT=10000 claude # 超时时间设为 10 秒
中文路径问题：Windows 中文版系统默认 GBK 编码，导致中文路径解析失败，解决方案： ```bash # 切换到 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 的核心价值在于”统一协议打通外部壁垒”——通过 HTTP/stdio 两种传输方式接入外部服务，配合三级作用域灵活管控配置范围，再结合 @ 资源引用和斜杠命令快速调用能力，即可构建完整的跨系统自动化工作流。

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