Faker Mcp Server

Faker MCP Server

一个基于 Faker.js 库提供虚假／模拟数据生成功能的模型上下文协议（MCP）服务。为数据库填充、API 测试、演示应用和开发环境生成逼真的测试数据。

请阅读我的博客文章，进一步了解为何以及何时在 GitHub Copilot 等 AI Agent 中使用此 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 Server 提供四个强大的工具，用于生成虚假数据：

1. generate-person

生成逼真的人员数据，包括姓名、电子邮件、电话号码和地址。

参数：

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

使用示例：

Generate 10 fake person records with names, emails, and addresses

请求示例（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": "[email protected]",
    "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）

使用示例：

Generate 5 company records with seed 54321 for reproducibility

请求示例（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": "[email protected]",
    "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（object，必需）：定义实体和关系的数据集架构
  • entities（object）：实体名称到实体定义的映射
    • count（number）：为此实体生成的记录数（1-10,000）
    • type（string）：实体类型——person、company 或 custom
    • fields（array，可选）：要包含的字段列表（默认包含全部字段）
    • relationships（object，可选）：指向其他实体的外键关系
      • references（string）：父实体的名称
      • type（string）：关系类型——one-to-many 或 many-to-many
      • nullable（boolean，可选）：外键是否可以为 null（默认值：false）
• locale（string，可选）：生成数据的区域设置——en、fr、de、es、ja（默认值：en）
• seed（number，可选）：用于可重复生成的种子

使用示例：

Generate a dataset with 20 users and 100 orders, where each order references a user

请求示例（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": "[email protected]",
      "phone": "+1-555-100-0001"
    },
    {
      "id": "user_99999_1",
      "fullName": "Jane Smith",
      "email": "[email protected]",
      "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（number，可选）：生成的记录数（1-10,000，默认值：1）
• patterns（object，必需）：字段名称到模式定义的映射
  • type（string）：模式类型——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（string，可选）：生成数据的区域设置——会影响基于格式的模式（默认值：en）
• seed（number，可选）：用于可重复生成的种子

使用示例：

Generate 50 product records with codes matching pattern PRD-####-XX where # is a digit and X is an uppercase letter

请求示例（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"
  }
]

---

常见用例

数据库填充

生成逼真的测试数据，用于填充开发数据库：

Generate a dataset with 100 users, 500 orders, and 1000 order items with proper relationships, using seed 100

API 集成测试

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

Generate 20 user registration payloads with emails, passwords, and profile information

UI 演示数据

使用特定区域设置的数据构建演示环境：

Generate French locale data: 50 customers with addresses and 200 orders for a demo e-commerce site

性能测试

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

Generate 10000 person records for load testing my user import API

---

最佳实践

1. 使用种子确保可重复性

需要在不同环境中保持测试数据一致时，务必指定种子：

Generate 100 users with seed 12345

2. 选择合适的区域设置

让区域设置与目标市场匹配，以生成逼真的数据：

Generate 50 companies in German locale (de)

3. 对大型请求进行分批处理

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

Generate 3000 records with seed 111 (first batch)
Generate 3000 records with seed 222 (second batch)
Generate 3000 records with seed 333 (third batch)

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 标准错误响应格式。常见错误包括：

参数无效（code: -32602）：

{
  "error": {
    "code": -32602,
    "message": "Invalid count parameter: must be between 1 and 10000",
    "data": {
      "received": 50000,
      "max": 10000
    }
  }
}

不支持的区域设置（code: -32001）：

{
  "error": {
    "code": -32001,
    "message": "Unsupported locale: zh. Supported locales: en, fr, de, es, ja",
    "data": {
      "received": "zh",
      "supported": ["en", "fr", "de", "es", "ja"]
    }
  }
}

架构验证错误（code: -32602）：

{
  "error": {
    "code": -32602,
    "message": "Invalid schema: circular dependency detected in relationships",
    "data": {
      "cycle": ["orders", "items", "orders"]
    }
  }
}

---

MCP 客户端配置

Claude Desktop

Claude Desktop 是一款 AI 助手应用，支持 MCP 服务以扩展功能。

配置文件位置：

• 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 Marketplace 安装 Cline 扩展
2. 打开 VS Code 设置（JSON）——按 Cmd/Ctrl + Shift + P → “Preferences: Open User Settings (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 是一款面向 VS Code、支持 MCP 的开源 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 服务。

用法：

# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run with Faker MCP Server
mcp-inspector npx faker-mcp-server

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

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

---

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

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

连接参数：

• 命令：npx faker-mcp-server（如果已全局安装，也可使用 faker-mcp-server）
• 传输方式：stdio（标准输入/输出）
• 协议：MCP（模型上下文协议）
• 环境：需要 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';

// Start the MCP server process
const mcpServer = spawn('npx', ['faker-mcp-server'], {
  stdio: ['pipe', 'pipe', 'inherit']
});

// Send MCP request to generate person data
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');

// Read response
mcpServer.stdout.on('data', (data) => {
  const response = JSON.parse(data.toString());
  console.log('Generated data:', response.result);
});

---

配置故障排除

问题：“Command not found: faker-mcp-server”

解决方案：

• 使用 npx faker-mcp-server，而不是 faker-mcp-server
• 先进行全局安装：npm install -g faker-mcp-server
• 使用二进制文件的绝对路径

问题：“MCP server connection timeout”

解决方案：

• 确认已安装 Node.js 18+：node --version
• 检查服务能否手动启动：npx faker-mcp-server
• 查看客户端日志，查找具体错误消息
• 确保防火墙/防病毒软件未阻止 Node.js 进程

问题：“Invalid JSON response from server”

解决方案：

• 确保传输方式设为 stdio（而非 http 或 sse）
• 检查 Node.js 版本兼容性（需要 18+）
• 确认没有其他进程正在使用 stdio 流

---

特定平台说明

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 秒）
• 如果超时持续发生，请检查内存限制

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

原因：架构以错误的顺序定义关系，或存在循环依赖。

解决方案：

• 先定义父实体，再定义子实体
• 避免循环引用
• 生成前验证架构

---

开发

设置

# Clone the repository
git clone <repository-url>
cd faker-mcp

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run in development mode
npm run dev

脚本

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

许可证

MIT

作者

Funs Janssen

参与贡献

欢迎参与贡献！请随时提交 Pull Request。