@przeslijmi/real-fake-data-mcp
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_generatorsfor discovery,generateto 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
seedfor reproducible output, or omit it to randomise each call.
Install
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.
Claude Desktop / Claude Code
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+.
Configuration
The client passes configuration through the server's env:
| Variable | Required | Description |
|---|---|---|
REAL_FAKE_DATA_API_KEY | No | API key sent as Authorization: Bearer <key>, lifting requests onto your metered plan. Omit to use the anonymous lane. |
REAL_FAKE_DATA_API_BASE_URL | No | Override the hosted API. Defaults to https://api.real-fake-data.com; point it at a local API during development. |
Tools
list_generators
Lists 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, …
generate
Runs one generator and returns the API's { data, meta } envelope.
| Argument | Type | Description |
|---|---|---|
generator | string (required) | Generator id from list_generators, e.g. pl.pesel or any.email. |
options | Record<string, string | number | boolean> | Generator-specific query parameters; omit for defaults. |
count | number | Number of records to generate; omit for a single record. (Upper bound enforced by your plan.) |
seed | number | 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.
How it relates to the REST API
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.
License
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.