Faker Mcp Server

Faker MCP サーバー

Faker.js ライブラリを使用して、偽のデータやモックデータを生成する機能を提供する Model Context Protocol（MCP）サーバーです。データベースへの初期データ投入、API テスト、デモアプリケーション、開発環境向けに、リアルなテストデータを生成します。

この MCP サーバーを使う理由や利用するタイミングについては、ブログ記事をご覧ください。

特長

• 基本データの生成：名前、メールアドレス、住所、連絡先情報を含む、リアルな人物データや企業データを生成します
• 構造化データセット：複雑なテストシナリオ向けに、参照整合性を備えた複数エンティティのデータセットを作成します
• カスタムパターン：ドメイン固有の要件に合わせて、カスタムパターン（正規表現、列挙、形式、範囲）に従ったデータを生成します
• 複数のロケールに対応：英語、フランス語、ドイツ語、スペイン語、日本語でデータを生成します
• 再現可能なデータ：シードに基づいて一貫性のあるテストデータを生成します
• 高パフォーマンス：1 秒あたり 1000 件以上のレコードを生成します
• MCP プロトコルに準拠：MCP 対応クライアントとシームレスに連携します

インストール

前提条件

• Node.js 18 以降がシステムにインストールされていること
• MCP 対応クライアント（例：Claude Desktop、Cline、Cursor、その他の MCP クライアント）

クイックスタート

mcpServers セクションに Faker MCP サーバーを追加します。

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

さまざまな MCP クライアントの詳細な設定方法については、MCP クライアントの設定セクションをご覧ください。

利用可能なツール

Faker MCP サーバーには、偽のデータを生成するための強力なツールが 4 つ用意されています。

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" } 
      }
    }
  }
}

---

パフォーマンスの目安

操作	レコード数	想定時間	メモリ使用量
Person の生成	100	<100ms	<5MB
Person の生成	1,000	<1s	<50MB
Person の生成	10,000	<10s	<100MB
Company の生成	100	<100ms	<5MB
データセットの生成	合計 1,000	<2s	<50MB
カスタムデータの生成	1,000	<1s	<30MB

パフォーマンスは、システムリソースやパターンの複雑さによって異なる場合があります。

---

エラー処理

サーバーは MCP 標準のエラーレスポンス形式に従います。一般的なエラーは次のとおりです：

無効なパラメーター（コード：-32602）：

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

未対応のロケール（コード：-32001）：

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

スキーマ検証エラー（コード：-32602）：

{
  "error": {
    "code": -32602,
    "message": "Invalid schema: circular dependency detected in relationships",
    "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 は、MCP をサポートし、AI アシスタンスをエディターに直接導入する VS Code 拡張機能です。

セットアップ手順：

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 は、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 サーバーをテストするための公式デバッグツールです。

使用方法：

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

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

これにより、http://localhost:5173 にウェブインターフェースが開き、次の操作ができます：

• 利用可能なすべてのツールを検出する
• カスタムパラメーターを指定してツール呼び出しをテストする
• リクエスト／レスポンスのログを表示する
• 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';

// 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」

解決策：

• faker-mcp-server の代わりに npx 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/ にあります
• Node.js には Homebrew を使用します：brew install node@18

Windows:

• 設定ファイルは通常、%APPDATA%\ または %USERPROFILE%\.config\ にあります
• nodejs.org または nvm-windows から Node.js インストーラーを使用します
• JSON のパスにはスラッシュまたはエスケープしたバックスラッシュを使用します

Linux:

• 設定ファイルは通常、~/.config/ にあります
• Node.js のバージョン管理には nvm を使用します
• 実行権限があることを確認します：chmod +x /path/to/faker-mcp-server

---

トラブルシューティング

「MCP サーバーが見つかりません」

原因：サーバーが正しくインストールまたは設定されていません。

解決方法：

1. インストールを確認します：npm list -g faker-mcp-server
2. MCP クライアントの設定ファイルでコマンドが正しいことを確認します
3. 設定を変更した後、MCP クライアントを再起動します

「無効なロケールエラー」

原因：指定されたロケールはサポートされていません。

解決方法：サポートされているロケールのいずれかを使用します：en、fr、de、es、ja

「大規模なデータセットでリクエストがタイムアウトする」

原因：5,000 件を超えるレコードの生成には数秒かかる場合があります。

解決方法：

• バッチサイズを小さくします
• しばらくお待ちください（通常、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

コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。