This server lets AI assistants discover and generate realistic, synthetic test data via two MCP tools:
list_generators: Retrieve all available generators with their IDs, descriptions, and supported locales (e.g., pl.pesel, any.email, de.company-name). Use this first to explore what data types are available.
generate: Run any generator by ID to produce fake-but-realistic data, including:
Polish identifiers with valid checksums: PESELs, NIPs, REGONs
IBANs across 27 EU countries
Addresses drawn from real cities and streets
People (names, surnames, birth dates) with optional sex filtering
Company names, emails, and other generic data
Key features:
Batch generation: Use the count parameter to produce multiple records in one call.
Reproducible output: Pass a seed value for deterministic, repeatable results — useful for consistent test fixtures.
Generator-specific options: Customize via options (e.g., { "sex": "f" } for female persons, { "format": "digits-only" } for NIPs, { "invalid": true } for deliberately wrong checksums to test validators).
Auto-updating: New upstream generators become available immediately without client upgrades.
Configuration: Set REAL_FAKE_DATA_API_KEY for metered plans, or REAL_FAKE_DATA_API_BASE_URL to point to a custom API instance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@real-fake-data-mcp Generate 5 Polish addresses for my test database"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for Real Fake Data — gives an AI assistant (Claude Desktop, Claude Code, Cursor, …) realistic, synthetic test data on demand: valid PESELs (correct checksums), NIPs, REGONs, IBANs, addresses drawn from real cities and streets, people, and company names across 27 EU countries.
Output looks real but is fake — safe for staging, demos, and seed data.
Two tools, self-updating. list_generators for discovery, generate to run any generator by id. New generators on the API appear automatically — no client upgrade.
Thin and stateless. Calls the hosted Real Fake Data API over HTTPS; no data is generated or stored locally.
Seeded when you want it. Pass a seed for reproducible output, or omit it to randomise each call.
No global install needed — point your MCP client at the package via npx. It runs over stdio, so the client spawns it as a subprocess.
Add it to your MCP servers config (claude_desktop_config.json, or via claude mcp add):
{
"mcpServers": {
"real-fake-data": {
"command": "npx",
"args": ["-y", "@przeslijmi/real-fake-data-mcp"],
"env": {
"REAL_FAKE_DATA_API_KEY": "your-api-key"
}
}
}
}Restart the client; the real-fake-data tools become available in any conversation.
Requires Node 22+.
Related MCP server: Faker MCP Server
The client passes configuration through the server's env:
Variable | Required | Description |
| No | API key sent as |
| No | Override the hosted API. Defaults to |
list_generatorsLists every available generator with its id, description, and supportedLocales. Call it first to discover which ids generate accepts.
You: What fake-data generators are available?
Claude (calls
list_generators) →pl.pesel,pl.company,pl.address,any.email,de.company-name, …
generateRuns one generator and returns the API's { data, meta } envelope.
Argument | Type | Description |
|
| Generator id from |
|
| Generator-specific query parameters; omit for defaults. |
|
| Number of records to generate; omit for a single record. (Upper bound enforced by your plan.) |
|
| Seed for reproducible output; omit to randomise each call. |
You: Generate 3 female Polish people for my staging DB.
Claude (calls
generatewith{ generator: "pl.person", count: 3, options: { sex: "f" } }) → three records of{ name, surname, initials, birthDate, pesel }.
options are the same query parameters the generator exposes on the REST API — list_generators describes each, and the API docs list them in full. Examples: { "format": "digits-only" } for a NIP, { "teryt": "14" } to anchor an address to a region, { "invalid": true } to get a deliberately-wrong checksum for testing your validators.
This server is a thin MCP front end over the same hosted endpoints the Playwright addon and REST API serve. A generator id maps directly to a route — pl.pesel → GET /v1/pl/pesel, any.email → GET /v1/email — and metering, plan limits, and validation all behave identically. Use this package when you want an AI assistant to produce test data conversationally; use the Playwright addon or the REST API directly from code.
MIT
This repository is auto-generated from a private upstream monorepo. Open issues here, but code changes are made upstream and re-synced — pull requests against this repo are applied upstream, not merged directly.
Generate realistic synthetic data from one Real Fake Data generator. Pass a generator id from list_generators (e.g. pl.pesel). Use options for generator-specific parameters (e.g. {"sex":"f"} for a person, {"format":"digits-only"} for a NIP) — see each generator's description. Set count for a batch and seed for reproducible output. Returns the API's { data, meta } envelope.
| Name | Required | Description | Default |
|---|---|---|---|
| generator | Yes | Generator id from `list_generators`, e.g. `pl.pesel` or `any.email`. | |
| options | No | Generator-specific query parameters; omit for defaults. | |
| count | No | Number of records to generate; omit for a single record. | |
| seed | No | Seed for reproducible output; omit to randomise each call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the return envelope format (`{ data, meta }`), reproducibility via seed, and batching via count. However, it does not discuss side effects, permissions, or potential errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no wasted words. The first sentence states the core function, followed by parameter usage guidance. Structure is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description sufficiently explains the return format. It covers all parameters, the dependency on `list_generators`, and behavioral nuances (seed, batch). The tool is straightforward, so completeness is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are already described in the schema (100% coverage), but the description adds valuable context: examples for `options` (e.g., `{"sex":"f"}`), clarification that `count` is for batch and `seed` for reproducibility, and references to generator descriptions. This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: generating realistic synthetic data using a generator ID from `list_generators`. It uses specific verbs ('generate', 'pass') and distinguishes from the sibling tool by referencing the generator list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use the tool (need synthetic data from a specific generator) and implicitly directs to `list_generators` for IDs. It does not explicitly state when not to use it, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every available Real Fake Data generator with its id, description and supported locales. Call this first to discover which generator ids the generate tool accepts (e.g. pl.pesel, pl.company, any.email).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, but description implies a safe read operation listing all generators. Does not declare side effects or errors, but for a list tool that is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both productive: first states function, second gives critical usage guidance. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless list tool, the description fully covers purpose, output contents, and integration with sibling tool. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so schema coverage is 100%. Description adds value by specifying output fields (id, description, locales) and usage examples, going beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States verb 'list' and resource 'every available Real Fake Data generator' with specific output fields (id, description, locales). Clearly distinguishes from sibling 'generate' by positioning it as a discovery tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to 'call this first' to discover generator ids accepted by the 'generate' tool, providing clear when-to-use and prerequisite context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0generatelist_generatorsScored across 2 tools
The two tools have completely distinct purposes: one lists available generators, the other generates data. There is no overlap or ambiguity.
Both tools use imperative verbs, but 'list_generators' follows a verb_noun pattern while 'generate' is just a verb, creating a slight inconsistency. The pattern is still clear and readable.
Two tools is minimal but appropriate for the server's purpose of discovering and generating synthetic data. The scope is well-defined without unnecessary extras.
The tools cover the essential workflow: discover generators and generate data. There is a minor gap in not having a tool to view detailed generator options, but the descriptions in list_generators suffice for basic use.
Generate realistic, FK-consistent synthetic test data for your databases from your AI assistant.
Format-true synthetic test data for 90 countries — IBANs, SWIFT/BIC, IDs, cards, all certified.
Generate synthetic random user data for testing, demos, and development without using real persona.
Privacy-safe synthetic financial data for LatAm fintech, AI agents, testing and ML.
