MCP Mock Server
一个基于 MCP (Model Context Protocol) 的 Mock 服务器，专为移动端应用设计，支持通过 Charles 代理实现零代码侵入的数据 Mock。
特性
- 零代码侵入: RN 应用只需配置 Charles 代理，无需修改任何业务代码
- 动态规则管理: 通过 MCP 工具（在 Cursor 中）动态添加/删除 Mock 规则，无需重启服务
- 自动生成 Charles 配置: 添加 Mock 规则后自动生成 Charles XML 配置文件
- 多项目支持: 多个项目可同时使用同一个 MCP 服务，各自占用不同端口，互不干扰
- 数据持久化: 所有 Mock 规则自动保存到文件，重启后自动恢复
- 自然语言交互: 在 Cursor 中用自然语言描述即可创建 Mock 接口
架构
RN App → Charles Proxy → MCP Mock Server（HTTP 代理）→ 返回 Mock 数据---
安装与配置
1. 在 Cursor 中配置 MCP
编辑 ~/.cursor/mcp.json，添加：
{
"mcpServers": {
"mi-mock-server": {
"command": "npx",
"args": ["-y", "mockserver-mcp-charles"]
}
}
}配置完成后重启 Cursor 或重新加载 MCP 即可使用。
2. 在项目根目录创建配置文件
在项目根目录创建 mockCharlesConfig.json：
{
"rulesPath": "_mock-rules/rules.json",
"charlesTargetDomains": [
"api.example.com",
"api-pre.example.com"
]
}| 字段 | 必填 | 说明 | |------|------|------| | rulesPath | 推荐 | Mock 规则文件存储路径（相对于配置文件目录），建议加入 .gitignore | | charlesTargetDomains | 必填 | 生成 Charles 映射时的目标域名列表（线上/预发/测试等） | | charlesTargetPort | 可选 | 目标域名端口，默认 443（HTTPS 标准端口，通常不需要填写） | | projectPrefix | 可选 | 项目前缀，默认取项目目录名，用于多项目共享代理时区分路由 |
其余字段（
port、enableLogging、maxLogs、mockEnabled）均有合理默认值，无需配置。
---
端口机制
- 启动时从默认端口（7979）开始自动查找可用端口，不会杀掉其他进程
- 多个项目各自找到空闲端口，天然隔离、互不影响
- 启动成功后控制台打印实际地址，生成 Charles 配置时自动使用该端口
┌────────────────────────────────────────────────────────┐
│ Mock HTTP 代理已启动
│ 地址: http://127.0.0.1:7979
│ 规则文件: /path/to/project/_mock-rules/rules.json
└────────────────────────────────────────────────────────┘---
多项目支持
多个项目同时使用时，每个项目有独立的 HTTP 代理端口，Charles 映射也各自指向正确端口：
项目A → 监听 7979 → Charles: api-a.com → localhost:7979
项目B → 监听 7980 → Charles: api-b.com → localhost:7980生成 Charles 配置文件时自动使用当前项目实际监听的端口，无需手动修改。
---
使用方式
在 Cursor 中创建 Mock 接口
直接用自然语言描述：
添加一个 POST 接口 /api/user/info，返回：
{
"code": 0,
"data": { "id": 1, "name": "张三" },
"message": "ok"
}MCP 服务会自动调用 add_mock_rule 工具创建规则，并生成 Charles 配置文件。
手动生成 Charles 映射文件
在 Cursor 对话框中输入：
生成 Charles 映射文件生成的 XML 文件位于 _mock-rules/map-remote.xml。
导入 Charles 步骤：
- 打开 Charles → 菜单
Tools→Map Remote... - 点击
Import Settings - 选择
_mock-rules/map-remote.xml - 确认导入，规则立即生效
---
MCP 工具说明
add_mock_rule — 添加 Mock 规则
| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | url | string | ✅ | 接口路径，如 /api/user/info | | response | object | ✅ | JSON 响应数据 | | method | string | — | HTTP 方法，默认 GET | | statusCode | number | — | 状态码，默认 200 | | headers | object | — | 自定义响应头 | | delay | number | — | 响应延迟（毫秒） |
remove_mock_rule — 删除 Mock 规则
通过 id 或 url + method 删除。
list_mock_rules — 列出所有规则
generate_charles_config — 生成 Charles 配置
| 参数 | 说明 | |------|------| | targetDomains | 域名数组，不传则从 mockCharlesConfig.json 读取 | | targetDomain | 单个域名（兼容旧用法） | | targetPort | 目标端口，不传则从配置读取，默认 443 |
get_request_logs — 查看请求日志
| 参数 | 说明 | |------|------| | limit | 返回条数，默认 100 |
toggle_mock — 启用/禁用 Mock
| 参数 | 说明 | |------|------| | enabled | true 启用，false 禁用 |
reload_rules — 重新加载规则文件
手动编辑 rules.json 后调用，无需重启服务。
---
URL 匹配规则
| 模式 | 示例 | 说明 | |------|------|------| | 精确匹配 | /api/user/info | 只匹配完全相同的路径 | | 单段通配 | /api/user/ | 匹配 /api/user/123、/api/user/abc | | 多段通配 | /api/ | 匹配 /api/user/info、/api/order/list 等 |
---
数据持久化
规则保存在 rulesPath 指定的文件中（默认 _mock-rules/rules.json）：
{
"rules": [
{
"id": "uuid",
"url": "/api/user/info",
"method": "GET",
"response": { "code": 0, "data": {} },
"statusCode": 200,
"enabled": true,
"createdAt": "2024-01-01T00:00:00Z"
}
],
"version": "1.0.0"
}建议将 _mock-rules/ 加入 .gitignore，避免 Mock 数据污染代码仓库。
---
项目结构
mockserver-mcp-charles/
├── src/
│ ├── server.ts # MCP 服务器主入口 & HTTP 代理启动
│ ├── proxy.ts # HTTP 代理请求处理
│ ├── rules.ts # Mock 规则管理
│ ├── tools.ts # MCP 工具定义与处理器
│ ├── config.ts # 配置加载与运行时状态
│ ├── charles.ts # Charles XML 配置生成
│ └── types.ts # TypeScript 类型定义
└── _mock-rules/ # 运行时生成（建议 .gitignore）
├── rules.json # Mock 规则持久化文件
└── map-remote.xml # Charles Map Remote 配置---
故障排查
请求没有被 Mock 拦截
- 确认 Charles 已启用 Map Remote 且规则已导入
- 确认 移动端 应用流量经过 Charles 代理
- 用
list_mock_rules检查规则是否存在 - 用
get_request_logs查看请求日志，确认请求是否到达 Mock 服务
Charles 映射端口不对
重新执行「生成 Charles 映射文件」，配置会自动使用当前实际监听端口，重新导入即可。
规则重启后丢失
检查 rulesPath 配置的路径是否正确，以及该文件是否被意外删除或加入了 .gitignore。
---
许可证
MIT
扩展
后端接口如果使用接口管理平台的话例如YApi Pro，apifox可以扩展通过平台开放api接入数据，从而实现输入链接一键mock（mock质量依赖文档）
