Claude Code MCP 使用教程

MCP，全称Model Context Protocol，本质上就是Claude Code的一根“通用数据线”。有了它，你只需要用自然语言跟Claude Code说句话，就能直接操作GitHub、Sentry、PostgreSQL、Figma这些外部服务，再也不用在各个工具之间来回切换。到了2026年4月，MCP生态已经长出了超过4000个可用服务器，SDK的月下载量逼近1亿次——这个数字本身就说明了它的价值。

这篇指南会从核心概念讲到接入方式、配置管理，再到实战场景和问题排查，每个环节都会配具体的代码示例。希望帮你彻底吃透MCP的完整用法。

一、MCP 核心概述与价值

说白了，MCP就是Claude Code连接外部世界的标准接口。它定义了一套统一的通信规则，让Claude Code跟谁都能好沟通，不用关心背后的工具接口有多复杂。一次配置，到处复用。

1.1 核心价值

• 打通工具壁垒：不需要切换界面，Claude Code就能直接调动GitHub、JIRA、Sentry、PostgreSQL、Figma这些工具，实现“用自然语言操控整条工作流”。

• 提升协作效率：团队可以共享MCP配置，大家用统一的环境，不用每个人重复配置一遍，这在多人协作的项目里尤其省心。

• 扩展AI边界：MCP能让Claude Code突破内置能力的局限，做到实时数据查询、报错分析、代码生成、工单管理这些更复杂的操作。

• 安全可控：提供了三级作用域隔离、企业级权限管控，还支持白名单和黑名单配置。灵活和安全性之间可以找到不错的平衡。

1.2 与 Agent Skills 的区别

很多开发者容易把MCP和Agent Skills搞混。其实两者定位完全不同，搭配起来用才能把Claude Code的能力发挥到最大。区别是这样的：

简单说就是：Skills让Claude Code更“聪明”，懂方法；MCP让Claude Code更“能干”，能直接操作外部工具。

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

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

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

搞清楚MCP是做什么的之后，第一个问题就是——怎么接进去？MCP支持三种传输方式，覆盖远程云服务和本地进程两种核心场景。SSE方式已经被官方弃用了，现在优先推荐HTTP和stdio方式。

2.1 HTTP 远程服务器（推荐）

这种方式适用于云端MCP服务，比如GitHub、Notion、Sentry的官方MCP服务器。是官方最推荐的远程接入方案，支持请求头授权和环境变量配置，稳定性高，适配性好。

基础语法

claude mcp add --transport http

实操示例

# 示例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 [选项] -- [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服务器之后，日常管理也很关键——查看状态、删除配置、重置授权，这几个命令覆盖了最高频的管理场景。

# 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 三级作用域详细说明

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

很多Claude Code插件会捆绑MCP服务器，启用插件后会自动加载对应的MCP配置，不需要手动添加。同时企业可以集中管控权限，防止未授权的工具接入。

6.1 插件内置 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 FilesClaudeCodemanaged-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可以实现批量组件重构、代码溯源、自动生成测试这些功能，对前端开发效率的提升非常明显。

九、常见问题与优化配置

实战中难免会遇到连接失败、认证过期这些问题。下面整理了一些高频故障的排查方法和优化配置，也涵盖了Windows系统特有的问题。

9.1 常见故障排查

# 1. 检查 MCP 协议版本（Claude Code 0.48+ 要求 v2.0）npm ls @modelcontextprotocol/sdknpm 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和策略管控，把数据安全和团队协作规范守住。