Faker MCP

🚀 Faker MCP 服务器

Faker MCP 服务器是一个基于 Model Context Protocol (MCP) 的服务器，它借助 Faker.js 库实现了伪造/模拟数据的生成功能。该服务器可用于为数据库填充、API 测试、演示应用程序以及开发环境生成逼真的测试数据。

你可以在我的博客文章中了解更多关于为何以及何时使用此 MCP 服务器的信息。

✨ 主要特性

• 基础数据生成：生成包含姓名、电子邮件、地址和联系信息的逼真个人和公司数据。
• 结构化数据集：为复杂的测试场景创建具有引用完整性的多实体数据集。
• 自定义模式：根据自定义模式（正则表达式、枚举、格式、范围）生成特定领域需求的数据。
• 多语言支持：支持生成英语、法语、德语、西班牙语和日语的数据。
• 可重现数据：基于种子生成一致的测试数据。
• 高性能：每秒可生成 1000 条以上的记录。
• 符合 MCP 协议：可与兼容 MCP 的客户端无缝集成。

📦 安装指南

前提条件

• 系统中已安装 Node.js 18 或更高版本。
• 拥有一个兼容 MCP 的客户端（例如，Claude Desktop、Cline、Cursor 或任何 MCP 客户端）。

🚀 快速开始

将 Faker MCP 服务器添加到 mcpServers 部分：

{
  "mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

有关各种 MCP 客户端的详细设置说明，请参阅MCP 客户端配置部分。

💻 使用示例

可用工具

Faker MCP 服务器提供了四个强大的伪造数据生成工具：

1. generate-person

生成包含姓名、电子邮件、电话号码和地址的逼真个人数据。 参数：

• count（数字，可选）：要生成的个人记录数量（1 - 10,000，默认值：1）。
• locale（字符串，可选）：生成数据的语言环境 - en、fr、de、es、ja（默认值：en）。
• seed（数字，可选）：用于可重现生成的种子。
• includeAddress（布尔值，可选）：是否包含地址信息（默认值：true）。
• includePhone（布尔值，可选）：是否包含电话号码（默认值：true）。
• includeDateOfBirth（布尔值，可选）：是否包含出生日期（默认值：false）。

示例用法：

生成 10 条包含姓名、电子邮件和地址的伪造个人记录

示例请求（MCP 协议）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-person",
    "arguments": {
      "count": 5,
      "locale": "en",
      "seed": 12345,
      "includeAddress": true,
      "includePhone": true,
      "includeDateOfBirth": false
    }
  }
}

示例输出：

[
  {
    "id": "person_12345_0",
    "firstName": "John",
    "lastName": "Doe",
    "fullName": "John Doe",
    "email": "john.doe@example.com",
    "phone": "+1-555-123-4567",
    "address": {
      "street": "123 Main St",
      "city": "Springfield",
      "state": "IL",
      "postalCode": "62701",
      "country": "United States"
    }
  }
]

2. generate-company

生成包含名称、行业、联系信息和地址的逼真公司数据。 参数：

• count（数字，可选）：要生成的公司记录数量（1 - 10,000，默认值：1）。
• locale（字符串，可选）：生成数据的语言环境 - en、fr、de、es、ja（默认值：en）。
• seed（数字，可选）：用于可重现生成的种子。
• includeAddress（布尔值，可选）：是否包含地址信息（默认值：true）。
• includeWebsite（布尔值，可选）：是否包含网站 URL（默认值：true）。
• includeFoundedYear（布尔值，可选）：是否包含成立年份（默认值：false）。
• includeEmployeeCount（布尔值，可选）：是否包含员工数量（默认值：false）。

示例用法：

生成 5 条具有种子 54321 的公司记录，以实现可重现性

示例请求（MCP 协议）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-company",
    "arguments": {
      "count": 3,
      "locale": "en",
      "seed": 54321,
      "includeAddress": true,
      "includeWebsite": true,
      "includeFoundedYear": true,
      "includeEmployeeCount": true
    }
  }
}

示例输出：

[
  {
    "id": "company_54321_0",
    "name": "Acme Corporation",
    "industry": "Technology",
    "email": "contact@acme.example.com",
    "phone": "+1-555-111-2222",
    "website": "https://acme.example.com",
    "address": {
      "street": "100 Tech Blvd",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "United States"
    },
    "founded": 2010,
    "employeeCount": 250
  }
]

3. generate-dataset

生成具有多个实体类型和它们之间引用完整性的结构化数据集。 参数：

• schema（对象，必需）：定义实体和关系的数据集架构。
  • entities（对象）：实体名称到实体定义的映射。
    • count（数字）：为该实体生成的记录数量（1 - 10,000）。
    • type（字符串）：实体类型 - person、company 或 custom。
    • fields（数组，可选）：要包含的字段列表（默认为所有字段）。
    • relationships（对象，可选）：与其他实体的外键关系。
      • references（字符串）：父实体的名称。
      • type（字符串）：关系类型 - one-to-many 或 many-to-many。
      • nullable（布尔值，可选）：外键是否可以为空（默认值：false）。
• locale（字符串，可选）：生成数据的语言环境 - en、fr、de、es、ja（默认值：en）。
• seed（数字，可选）：用于可重现生成的种子。

示例用法：

生成一个包含 20 个用户和 100 个订单的数据集，其中每个订单引用一个用户

示例请求（MCP 协议）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-dataset",
    "arguments": {
      "schema": {
        "entities": {
          "users": {
            "count": 10,
            "type": "person",
            "fields": ["id", "fullName", "email", "phone"]
          },
          "orders": {
            "count": 30,
            "type": "custom",
            "fields": ["id", "userId", "productName", "price", "orderDate"],
            "relationships": {
              "userId": {
                "references": "users",
                "type": "one-to-many",
                "nullable": false
              }
            }
          }
        }
      },
      "locale": "en",
      "seed": 99999
    }
  }
}

示例输出：

{
  "users": [
    {
      "id": "user_99999_0",
      "fullName": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1-555-100-0001"
    },
    {
      "id": "user_99999_1",
      "fullName": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+1-555-100-0002"
    }
  ],
  "orders": [
    {
      "id": "order_99999_0",
      "userId": "user_99999_0",
      "productName": "Laptop",
      "price": 1299.99,
      "orderDate": "2024-03-15"
    },
    {
      "id": "order_99999_1",
      "userId": "user_99999_0",
      "productName": "Mouse",
      "price": 29.99,
      "orderDate": "2024-03-16"
    },
    {
      "id": "order_99999_2",
      "userId": "user_99999_1",
      "productName": "Keyboard",
      "price": 89.99,
      "orderDate": "2024-03-17"
    }
  ]
}

4. generate-custom

根据自定义模式（包括正则表达式模式、枚举、格式和范围）生成数据。 参数：

• count（数字，可选）：要生成的记录数量（1 - 10,000，默认值：1）。
• patterns（对象，必需）：字段名称到模式定义的映射。
  • type（字符串）：模式类型 - regex、enum、format 或 range。
  • value：模式值（取决于模式类型）：
    • regex：正则表达式字符串（例如，"PRD-[0-9]{4}-[A-Z]{2}"）。
    • enum：可供选择的字符串值数组（例如，["pending", "active", "completed"]）。
    • format：带有占位符的模板字符串（例如，"REF-{{year}}-{{random:5}}"）。
    • range：包含 min 和 max 数值的对象（例如，{"min": 10, "max": 1000}）。
• locale（字符串，可选）：生成数据的语言环境 - 影响基于格式的模式（默认值：en）。
• seed（数字，可选）：用于可重现生成的种子。

示例用法：

生成 50 条产品记录，其代码符合模式 PRD - #### - XX，其中 # 是数字，X 是大写字母

示例请求（MCP 协议）：

{
  "method": "tools/call",
  "params": {
    "name": "generate-custom",
    "arguments": {
      "count": 5,
      "patterns": {
        "productCode": {
          "type": "regex",
          "value": "PRD-[0-9]{4}-[A-Z]{2}"
        },
        "status": {
          "type": "enum",
          "value": ["pending", "active", "completed", "cancelled"]
        },
        "price": {
          "type": "range",
          "value": { "min": 10, "max": 1000 }
        },
        "reference": {
          "type": "format",
          "value": "REF-{{year}}-{{random:5}}"
        }
      },
      "locale": "en",
      "seed": 11111
    }
  }
}

示例输出：

[
  {
    "id": "custom_11111_0",
    "productCode": "PRD-1234-AB",
    "status": "active",
    "price": 456.78,
    "reference": "REF-2024-A3B5C"
  },
  {
    "id": "custom_11111_1",
    "productCode": "PRD-5678-CD",
    "status": "pending",
    "price": 123.45,
    "reference": "REF-2024-D7E9F"
  }
]

常见用例

数据库填充

生成逼真的测试数据以填充开发数据库：

使用种子 100 生成一个包含 100 个用户、500 个订单和 1000 个订单项的数据集，并确保它们之间的关系正确

API 集成测试

创建具有逼真数据结构的测试负载：

生成 20 个包含电子邮件、密码和个人资料信息的用户注册负载

UI 演示数据

使用特定语言环境的数据构建演示环境：

为一个演示电子商务网站生成法语语言环境的数据：50 个带有地址的客户和 200 个订单

性能测试

生成大量数据进行负载测试：

生成 10000 条个人记录，用于对我的用户导入 API 进行负载测试

最佳实践

1. 使用种子实现可重现性

当你需要在不同环境中获得一致的测试数据时，始终指定一个种子：

使用种子 12345 生成 100 个用户

2. 选择合适的语言环境

根据目标市场选择合适的语言环境，以生成逼真的数据：

使用德语语言环境（de）生成 50 家公司

3. 批量处理大型请求

对于非常大的数据集，可以考虑分批生成：

使用种子 111 生成 3000 条记录（第一批）
使用种子 222 生成 3000 条记录（第二批）
使用种子 333 生成 3000 条记录（第三批）

4. 谨慎定义关系

确保在生成子实体之前先生成父实体：

{
  "entities": {
    "users": { "count": 10, "type": "person" },
    "orders": { 
      "count": 50, 
      "type": "custom",
      "relationships": { 
        "userId": { "references": "users", "type": "one-to-many" } 
      }
    }
  }
}

性能预期

操作	记录数量	预期时间	内存使用
生成个人记录	100	<100ms	<5MB
生成个人记录	1,000	<1s	<50MB
生成个人记录	10,000	<10s	<100MB
生成公司记录	100	<100ms	<5MB
生成数据集	总计 1,000 条	<2s	<50MB
生成自定义数据	1,000 条	<1s	<30MB

性能可能会因系统资源和模式复杂性而有所不同。

错误处理

服务器遵循 MCP 标准错误响应格式。常见错误包括：

参数无效（代码：-32602）：

{
  "error": {
    "code": -32602,
    "message": "无效的 count 参数：必须在 1 到 10000 之间",
    "data": {
      "received": 50000,
      "max": 10000
    }
  }
}

不支持的语言环境（代码：-32001）：

{
  "error": {
    "code": -32001,
    "message": "不支持的语言环境：zh。支持的语言环境：en、fr、de、es、ja",
    "data": {
      "received": "zh",
      "supported": ["en", "fr", "de", "es", "ja"]
    }
  }
}

模式验证错误（代码：-32602）：

{
  "error": {
    "code": -32602,
    "message": "无效的模式：在关系中检测到循环依赖",
    "data": {
      "cycle": ["orders", "items", "orders"]
    }
  }
}

📚 详细文档

MCP 客户端配置

Claude Desktop

Claude Desktop 是一款支持 MCP 服务器以扩展功能的 AI 助手应用程序。 配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

替代方案（使用全局安装的包）：

{
  "mcpServers": {
    "faker": {
      "command": "faker-mcp-server",
      "args": []
    }
  }
}

配置后：重启 Claude Desktop。你可以通过询问“有哪些 MCP 工具可用？”来验证连接。

Cline（VS Code 扩展）

Cline 是一个 VS Code 扩展，它通过 MCP 支持将 AI 辅助直接集成到你的编辑器中。 设置步骤：

1. 从 VS Code 市场安装 Cline 扩展。
2. 打开 VS Code 设置（JSON） - 按下 Cmd/Ctrl + Shift + P → “首选项：打开用户设置（JSON）”。
3. 添加 MCP 服务器配置：

{
  "cline.mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  }
}

替代方案（特定于工作区的配置）： 在你的项目中创建或编辑 .vscode/settings.json：

{
  "cline.mcpServers": {
    "faker": {
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  }
}

配置后：重新加载 VS Code 窗口或重启 Cline 扩展。

Continue（VS Code 扩展）

Continue 是一个支持 MCP 的开源 VS Code AI 代码助手。 配置文件位置：~/.continue/config.json（或特定于工作区的 .continue/config.json）。 配置：

{
  "mcpServers": [
    {
      "name": "faker",
      "command": "npx",
      "args": ["faker-mcp-server"],
      "transport": "stdio"
    }
  ]
}

配置后：重启 Continue 扩展或重新加载 VS Code。

Zed Editor

Zed 是一款内置 AI 和 MCP 支持的高性能代码编辑器。 配置文件位置：~/.config/zed/settings.json。 配置：

{
  "context_servers": {
    "faker-mcp-server": {
      "command": "npx",
      "args": ["faker-mcp-server"]
    }
  }
}

配置后：重启 Zed 编辑器。

MCP Inspector（开发/测试）

MCP Inspector 是一个用于在开发过程中测试 MCP 服务器的官方调试工具。 用法：

# 全局安装 MCP Inspector
npm install -g @modelcontextprotocol/inspector

# 使用 Faker MCP 服务器运行
mcp-inspector npx faker-mcp-server

这将在 http://localhost:5173 打开一个 Web 界面，你可以在其中：

• 发现所有可用的工具。
• 使用自定义参数测试工具调用。
• 查看请求/响应日志。
• 验证 MCP 协议合规性。

自定义 MCP 客户端（通用集成）

对于任何未列出的兼容 MCP 的客户端，请使用以下配置参数： 连接参数：

• 命令：npx faker-mcp-server（如果全局安装，也可以使用 faker-mcp-server）。
• 传输：stdio（标准输入/输出）。
• 协议：MCP（Model Context Protocol）。
• 环境：需要 Node.js 18 或更高版本。

通用 JSON 配置：

{
  "command": "npx",
  "args": ["faker-mcp-server"],
  "transport": "stdio",
  "env": {
    "NODE_ENV": "production"
  }
}

使用绝对路径（当 npx 不可用时）：

{
  "command": "/usr/local/bin/faker-mcp-server",
  "args": [],
  "transport": "stdio"
}

使用自定义 Node 路径：

{
  "command": "/usr/local/bin/node",
  "args": ["/path/to/node_modules/.bin/faker-mcp-server"],
  "transport": "stdio",
  "env": {
    "NODE_ENV": "production",
    "NODE_OPTIONS": "--max-old-space-size=512"
  }
}

Docker 容器

对于容器化环境或 CI/CD 管道： Dockerfile：

FROM node:18-alpine
RUN npm install -g faker-mcp-server
CMD ["faker-mcp-server"]

构建和运行：

docker build -t faker-mcp-server .
docker run -i faker-mcp-server

Docker Compose（用于与其他服务集成）：

version: '3.8'
services:
  faker-mcp:
    image: node:18-alpine
    command: npx faker-mcp-server
    stdin_open: true
    tty: true

编程式使用（Node.js）

你还可以在 Node.js 应用程序中以编程方式使用 MCP 服务器：

import { spawn } from 'child_process';

// 启动 MCP 服务器进程
const mcpServer = spawn('npx', ['faker-mcp-server'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

// 发送 MCP 请求以生成个人数据
const request = {
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'generate-person',
    arguments: {
      count: 5,
      locale: 'en',
      seed: 12345
    }
  }
};

mcpServer.stdin.write(JSON.stringify(request) + '\n');

// 读取响应
mcpServer.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  console.log('生成的数据:', response.result);
});

配置故障排除

问题：“找不到命令：faker-mcp-server” 解决方案：

• 使用 npx faker-mcp-server 代替 faker-mcp-server。
• 先全局安装：npm install -g faker-mcp-server。
• 使用二进制文件的绝对路径。

问题：“MCP 服务器连接超时” 解决方案：

• 验证是否安装了 Node.js 18 或更高版本：node --version。
• 检查服务器是否可以手动启动：npx faker-mcp-server。
• 查看客户端日志以获取具体错误消息。
• 确保没有防火墙/防病毒软件阻止 Node.js 进程。

问题：“来自服务器的无效 JSON 响应” 解决方案：

• 确保传输设置为 stdio（而不是 http 或 sse）。
• 检查 Node.js 版本兼容性（需要 18 或更高版本）。
• 验证没有其他进程正在使用标准输入/输出流。

特定平台注意事项

macOS：

• 配置文件通常位于 ~/Library/Application Support/。
• 使用 Homebrew 安装 Node.js：brew install node@18。

Windows：

• 配置文件通常位于 %APPDATA%\ 或 %USERPROFILE%\.config\。
• 使用 nodejs.org 上的 Node.js 安装程序或 nvm-windows。
• 在 JSON 路径中使用正斜杠或转义反斜杠。

Linux：

• 配置文件通常位于 ~/.config/。
• 使用 nvm 管理 Node.js 版本。
• 确保执行权限：chmod +x /path/to/faker-mcp-server。

故障排除

"MCP 服务器未找到"

原因：服务器未正确安装或配置。 解决方案：

1. 验证安装：npm list -g faker-mcp-server。
2. 检查 MCP 客户端配置文件中的命令是否正确。
3. 配置更改后重启 MCP 客户端。

"无效的语言环境错误"

原因：请求的语言环境不受支持。 解决方案：使用支持的语言环境之一：en、fr、de、es、ja。

"大数据集请求超时"

原因：生成超过 5000 条记录可能需要几秒钟。 解决方案：

• 使用较小的批量大小。
• 耐心等待（通常生成 10,000 条记录需要不到 10 秒）。
• 如果仍然超时，请检查内存限制。

"数据集中的引用完整性错误"

原因：模式以错误的顺序定义关系或存在循环依赖。 解决方案：

• 在定义子实体之前先定义父实体。
• 避免循环引用。
• 在生成之前验证模式。

开发

设置

# 克隆仓库
git clone <repository-url>
cd faker-mcp

# 安装依赖项
npm install

# 运行测试
npm test

# 构建项目
npm run build

# 以开发模式运行
npm run dev

脚本

• npm run build - 为生产环境构建项目。
• npm run dev - 以监视模式构建，用于开发。
• npm test - 运行一次测试。
• npm run test:watch - 以监视模式运行测试。
• npm run test:coverage - 运行测试并生成覆盖率报告。
• npm run lint - 对代码进行 lint 检查。
• npm run lint:fix - 进行 lint 检查并修复问题。
• npm run format - 使用 Prettier 格式化代码。
• npm run typecheck - 进行类型检查但不生成输出。

📄 许可证

本项目采用 MIT 许可证。

作者

Funs Janssen

贡献

欢迎贡献代码！请随时提交拉取请求。