03_Claude Code之MCP（模型上下文协议）集成实战

03 Claude Code之MCP（模型上下文协议）集成实战

MCP（Model Context Protocol）是 Anthropic 推出的标准化 AI 与外部工具通信协议，将 M×N 的集成问题转化为 M+N 的可扩展框架。本文深度解析 Claude Code 中 MCP 的核心概念、三类服务器功能对比（Playwright、数据库、Slack 等）、工具调用机制，并提供自定义 MCP 服务器的开发指南。通过实际案例展示如何将 Claude Code 打造成真正的 AI 工作站，突破工具边界限制。

关键字：MCP协议、Model Context Protocol、Claude Code、工具集成、自定义MCP服务器、Playwright、数据库集成、工具扩展

标签：Claude CodeMCP协议AI工具集成模型上下文协议Playwright数据库工具扩展

写在前面

2024 年底 Anthropic 发布 MCP（Model Context Protocol）的时候，我觉得这是个"聪明的 API 规范"。用了几个月之后，我改变了看法：MCP 是 AI 工具集成的基础设施，类似于 USB-C 统一了设备连接方式。

在没有 MCP 之前，每个 AI 工具需要为每个外部服务写定制集成：GitHub 插件、Jira 插件、Slack 插件……每个 IDE、每个 AI 助手都要重复造轮子。MCP 把这个 M×N 的问题变成了 M+N——任何 AI 工具只要支持 MCP 客户端，就能连接任何 MCP 服务器。

这篇文章带你把 MCP 从"概念"变成"能用的工具"。

一、MCP 核心架构：三角关系

MCP 的核心是一个三方协议：

+-------------------+ MCP协议 +-------------------+ | | <---------------> | | | MCP客户端 | | MCP服务器 | | (Claude Code) | | (Playwright等) | | | | | +-------------------+ +-------------------+ | | | 调用工具 | 访问外部资源 v v +-------------------+ +-------------------+ | Claude模型 | | 外部系统 | | 进行推理 | | (浏览器/数据库) | +-------------------+ +-------------------+

Claude Code 作为 MCP 客户端，发现服务器提供的工具，按需调用。服务器负责实际连接外部系统。这种解耦设计让工具生态可以独立发展。

二、三种服务器类型与配置

MCP 支持三种传输类型，理解它们的区别是配置成功的关键：

类型一：HTTP 服务器（推荐，云端首选）

# 添加 Notion MCP 服务器claude mcpadd--transporthttp notion https://mcp.notion.com/mcp# 添加 GitHub MCP 服务器claude mcpadd--transporthttp github https://api.githubcopilot.com/mcp/# 添加 Sentry 监控claude mcpadd--transporthttp sentry https://mcp.sentry.dev/mcp

HTTP 服务器支持 OAuth 2.0 认证，适合云端托管的服务。无需本地安装，即连即用。

类型二：Stdio 服务器（本地工具首选）

# 添加 Playwright 浏览器自动化claude mcpadd--transportstdio playwright -- npx-y@playwright/mcp# 添加本地数据库工具claude mcpadd--transportstdio\--envDATABASE_URL=postgresql://user:pass@localhost/mydb\db -- npx-y@bytebase/dbhub--dsn"$DATABASE_URL"# 添加 Airtable 集成claude mcpadd--transportstdio\--envAIRTABLE_API_KEY=your_key\airtable -- npx-yairtable-mcp-server

Stdio 服务器以子进程方式运行，通过标准输入/输出通信。大多数开源 MCP 工具使用这种方式。

类型三：SSE 服务器（已弃用）

SSE 传输已被 HTTP 传输取代，老旧配置可以按照以下方式迁移：

# 旧方式（弃用）claude mcpadd--transportsse old-server https://example.com/sse# 新方式（推荐）claude mcpadd--transporthttp new-server https://example.com/mcp

三、配置文件详解：三个作用域

MCP 服务器配置有三个作用域，理解它们能避免很多团队协作问题：

优先级（高 → 低）： 命令行参数 > 本地配置 > 项目配置 > 用户配置

项目级配置：.mcp.json（团队共享）

{"mcpServers":{"playwright":{"type":"stdio","command":"npx","args":["-y","@playwright/mcp"]},"github":{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${GITHUB_TOKEN}"}},"db":{"type":"stdio","command":"npx","args":["-y","@bytebase/dbhub"],"env":{"DATABASE_URL":"${DATABASE_URL}"}}}}

关键点：.mcp.json支持环境变量扩展（${VAR_NAME}），把密钥放在.env中，.mcp.json提交到 git，密钥不提交。

用户级配置：~/.claude.json（个人工具）

把不与项目绑定的个人工具放在用户级配置里：

{"mcpServers":{"personal-notes":{"type":"stdio","command":"/usr/local/bin/notes-mcp-server"}}}

四、实战工具清单：我最常用的 MCP 集成

Playwright：让 Claude 真正"看见"浏览器

claude mcpadd--transportstdio playwright -- npx-y@playwright/mcp

配置后，Claude 可以：

• 截图页面，分析视觉效果
• 点击元素、填写表单
• 读取控制台日志、网络请求
• 端到端测试的执行和验证

真实用例：我用这个来调试 React 组件的样式问题——告诉 Claude “打开 localhost:3000，截图看一下 Header 组件的布局”，Claude 自己打开浏览器，截图，分析对比 CSS，然后直接修改代码。

数据库工具：直接问数据库

# PostgreSQLclaude mcpadd--transportstdio\db-pg -- npx-y@bytebase/dbhub\--dsn"postgresql://user:pass@localhost/mydb"

配置后可以直接问：

"用户表的 email 字段有没有索引？" "最近 7 天的订单量按日分布是什么？" "查看 orders 和 users 表的关联关系"

Slack：上下文感知的代码审查

claude mcpadd--transporthttp slack https://mcp.slack.com/mcp

配置后 Claude 可以读取 Slack 消息，把 bug 报告或需求讨论直接纳入代码修改的上下文中。告别"在 Slack 看需求，在 IDE 写代码，来回切换"的工作方式。

五、工具搜索机制：超过 10% 自动启动

当 MCP 服务器提供的工具描述超过上下文窗口的 10% 时，Claude Code 自动启用工具搜索机制：

正常模式：所有工具描述预加载到上下文 ↓ 工具描述 > 10% 上下文 ↓ 搜索模式：工具延迟加载，按需搜索

这意味着你可以配置很多 MCP 服务器，而不用担心它们"撑爆"上下文。实际上我配置了 12 个 MCP 服务器，日常使用完全没有问题。

手动控制工具搜索阈值：

# 将阈值降低到 5%（更激进的延迟加载）ENABLE_TOOL_SEARCH=auto:5 claude# 禁用工具搜索（强制预加载所有工具）ENABLE_TOOL_SEARCH=false claude

六、自定义 MCP 服务器开发

当现有的开源 MCP 服务器不能满足需求时，可以自己开发。核心逻辑非常简单：

TypeScript 版本（推荐）

import{McpServer}from"@modelcontextprotocol/sdk/server/mcp.js";import{StdioServerTransport}from"@modelcontextprotocol/sdk/server/stdio.js";import{z}from"zod";constserver=newMcpServer({name:"my-custom-server",version:"1.0.0",description:"处理公司内部系统的工具集合，包括工单查询、部署状态检查、配置管理"});// 注册工具：查询工单系统server.tool("get_ticket","查询内部工单系统中的工单详情，输入工单ID获取标题、状态、负责人和描述",{ticketId:z.string().describe("工单ID，格式如 PROJ-123"),},async({ticketId})=>{// 实际调用内部APIconstticket=awaitfetchTicket(ticketId);return{content:[{type:"text",text:JSON.stringify(ticket,null,2)}]};});// 注册工具：查询部署状态server.tool("check_deploy_status","查询指定服务的最新部署状态和版本信息",{serviceName:z.string(),environment:z.enum(["dev","staging","prod"])},async({serviceName,environment})=>{conststatus=awaitgetDeployStatus(serviceName,environment);return{content:[{type:"text",text:JSON.stringify(status)}]};});// 启动服务器consttransport=newStdioServerTransport();awaitserver.connect(transport);

关键设计原则：工具的description字段是 Claude 决策是否调用该工具的依据，写得越清晰，调用越精准。把"什么时候用这个工具"写进描述里。

注册到 Claude Code

# 将自定义服务器注册为本地工具claude mcpadd--transportstdio\my-company-tools --node/path/to/my-server.js

七、管理与调试

# 查看所有配置的 MCP 服务器claude mcp list# 查看特定服务器详情claude mcp get github# 删除服务器claude mcp remove old-server# 在会话内检查服务器状态/mcp

当 MCP 服务器连接失败时，用--debug标志启动 Claude Code 可以看到详细的错误信息：

claude--debug

总结

MCP 的价值不在于单个工具的功能，而在于工具的可组合性。Playwright + 数据库 + Slack 组合起来，Claude 就能做到：从 Slack 读到 bug 报告 → 查数据库验证现象 → 打开浏览器复现问题 → 定位代码修改。这个闭环在没有 MCP 之前需要人工协调。

建议从两三个最常用的工具开始（Playwright + GitHub 是很好的起点），逐步建立自己的 MCP 工具库。