Claude Code 进阶篇（四）：MCP 工具扩展

---

修订记录

编号	版本	修订人	修订内容	日期
001	1.0	lixh	创建全文	2026-01-21

---

1. 概述

MCP（Model Context Protocol）是 Claude Code 的核心扩展机制，允许接入外部工具和服务，极大地扩展 Claude 的能力边界。

1.1 什么是 MCP

图表源文件：06-mcp-architecture.drawio

MCP 的本质：一种标准化协议，定义了 AI 模型如何与外部工具交互。

1.2 MCP 的价值

优势	说明
能力扩展	接入数据库、API、浏览器等外部资源
标准化	统一的工具调用协议
可复用	MCP 服务可跨项目共享
安全可控	权限隔离，按需授权

---

2. MCP 服务类型

2.1 官方 MCP 服务

服务	功能	典型用途
github	GitHub 操作	创建 PR、管理 Issue
playwright	浏览器自动化	网页测试、截图
filesystem	文件系统扩展	跨目录文件操作
memory	知识图谱	实体关系存储

2.2 社区 MCP 服务

服务	功能	来源
claude-mem	向量记忆	社区开发
drawio	图表绘制	社区开发
modao	原型设计	墨刀集成

---

3. MCP 配置

3.1 配置文件位置

系统	路径
Windows	%APPDATA%\claude\settings.json
macOS	~/Library/Application Support/claude/settings.json
Linux	~/.config/claude/settings.json

3.2 配置结构

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

3.3 配置字段说明

字段	类型	说明
command	string	启动命令（如 npx、node）
args	array	命令参数
env	object	环境变量（API Keys 等）
cwd	string	工作目录（可选）

---

4. 常用 MCP 服务详解

4.1 GitHub MCP

功能：完整的 GitHub 操作能力

配置：

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
    }
  }
}

支持的操作：

操作	工具名	说明
创建仓库	create_repository	创建新仓库
创建 PR	create_pull_request	发起 Pull Request
管理 Issue	create_issue / update_issue	Issue 操作
搜索代码	search_code	跨仓库代码搜索
提交文件	push_files	推送文件到仓库

使用示例：

> 帮我创建一个 PR，标题是 "feat: 添加用户认证"

(Claude 使用 GitHub MCP 创建 PR)

4.2 Playwright MCP

功能：浏览器自动化和网页操作

配置：

{
  "playwright": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-playwright"]
  }
}

支持的操作：

操作	工具名	说明
导航	browser_navigate	访问 URL
点击	browser_click	点击元素
输入	browser_type	输入文本
截图	browser_take_screenshot	页面截图
快照	browser_snapshot	获取页面结构

使用示例：

> 帮我打开 example.com 并截图

(Claude 使用 Playwright MCP 操作浏览器)

4.3 Memory MCP

功能：知识图谱存储，实体和关系管理

配置：

{
  "memory": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-memory"]
  }
}

支持的操作：

操作	工具名	说明
创建实体	create_entities	存储知识节点
创建关系	create_relations	建立实体关联
搜索	search_nodes	查询知识
读取图谱	read_graph	获取全部知识

4.4 Filesystem MCP

功能：扩展文件系统访问

配置：

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@anthropic-ai/mcp-server-filesystem",
      "/allowed/path1",
      "/allowed/path2"
    ]
  }
}

注意：只能访问配置中指定的目录。

---

5. 安装与使用 MCP 服务

5.1 安装步骤

步骤 1：编辑配置文件

# 打开配置文件
code ~/.config/claude/settings.json

步骤 2：添加 MCP 配置

{
  "mcpServers": {
    "服务名": {
      "command": "...",
      "args": ["..."]
    }
  }
}

步骤 3：重启 Claude Code

claude

5.2 验证安装

> 列出可用的 MCP 工具

(Claude 会列出已配置的 MCP 服务和工具)

5.3 使用 MCP 工具

Claude 会自动识别并使用 MCP 工具：

> 帮我在 GitHub 上搜索 "react hooks" 相关代码

(自动使用 GitHub MCP 的 search_code)

> 打开 https://example.com 看看页面内容

(自动使用 Playwright MCP)

---

6. 高级 MCP 配置

6.1 环境变量管理

推荐做法：将敏感信息存储在环境变量中

{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}

6.2 多实例配置

可以配置同一 MCP 的多个实例：

{
  "filesystem-docs": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/docs"]
  },
  "filesystem-src": {
    "command": "npx",
    "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/src"]
  }
}

6.3 自定义 MCP 服务

可以开发自己的 MCP 服务：

// 简单的 MCP 服务示例
const { Server } = require('@modelcontextprotocol/sdk/server');

const server = new Server({
  name: 'my-custom-mcp',
  version: '1.0.0'
});

server.addTool({
  name: 'my_tool',
  description: 'My custom tool',
  inputSchema: { /* JSON Schema */ },
  handler: async (params) => {
    // 工具逻辑
    return { result: 'success' };
  }
});

server.start();

---

7. MCP 与工具链集成

7.1 典型工作流

7.2 实际案例

案例：自动化 PR 流程

> 帮我完成以下工作：
> 1. 修改代码
> 2. 运行测试
> 3. 创建 PR
> 4. 截图展示变更

Claude 执行：
1. 使用内置工具修改代码
2. 使用 Bash 运行测试
3. 使用 GitHub MCP 创建 PR
4. 使用 Playwright MCP 截图

---

8. 常用 MCP 工具速查

8.1 GitHub MCP

工具	用途
mcp__github__create_repository	创建仓库
mcp__github__create_pull_request	创建 PR
mcp__github__create_issue	创建 Issue
mcp__github__search_code	搜索代码
mcp__github__get_file_contents	获取文件内容
mcp__github__push_files	推送文件

8.2 Playwright MCP

工具	用途
mcp__playwright__browser_navigate	导航到 URL
mcp__playwright__browser_click	点击元素
mcp__playwright__browser_type	输入文本
mcp__playwright__browser_snapshot	获取页面快照
mcp__playwright__browser_take_screenshot	截图

8.3 Memory MCP

工具	用途
mcp__memory__create_entities	创建实体
mcp__memory__create_relations	创建关系
mcp__memory__search_nodes	搜索节点
mcp__memory__read_graph	读取图谱

---

9. 故障排除

9.1 MCP 服务未加载

检查点：

1. 配置文件 JSON 格式是否正确
2. 服务名是否有拼写错误
3. 命令和参数是否正确

调试：

# 手动运行 MCP 服务检查
npx -y @modelcontextprotocol/server-github

9.2 权限错误

GitHub MCP：

• 检查 Token 权限范围
• 确认 Token 未过期

Filesystem MCP：

• 确认目录路径正确
• 检查文件系统权限

9.3 连接超时

可能原因：

• 网络问题
• 服务启动慢

解决：

• 检查网络连接
• 增加超时配置

---

10. 下一步

了解了 MCP 系统后，继续学习：

• 07-上下文管理策略：优化上下文使用
• 08-CLAUDE.md配置最佳实践：整合 MCP 到项目

---

参考资料

• MCP 官方规范
• MCP 服务仓库
• Claude Code MCP 文档