generate-data-mcp
This MCP server wraps Generate-Data.com so an agent can design schemas, generate synthetic datasets/projects, inspect field types and usage, and manage saved Projects.
Generate synthetic rows from a field list (CSV and other formats per plan).
Propose or refine dataset schemas from natural language.
List available field types and get per-field configuration options.
Validate field options before generation (README v2).
Check API key usage, plan, and limits.
Generate all tables in a saved Project.
List, get, create, update, and delete Projects (README v2; the supplied schema only exposes list/generate).
Return success/error envelopes and save oversized or binary results to files/base64.
Note: the supplied schema reflects the older 8-tool v1 surface, while the README documents 14 renamed
gd_*v2 tools.
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., "@generate-data-mcp Propose a schema for an e-commerce product catalog."
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.
generate-data-mcp
An MCP server for Generate-Data.com — generate synthetic datasets, design schemas from natural language, and manage Projects, straight from your agent.
Thin HTTP wrapper over the Generate-Data.com API. No generation logic lives in this repo — it's a curated, agent-friendly interface onto the real thing: 14 tools, one consistent response shape, binary-safe output, and server-side validation on every input.
Installation (30-second setup)
You need a Generate-Data.com API key first — create one in Settings → API Access on generate-data.com.
Add this to your MCP client config (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json):
{
"mcpServers": {
"generate-data": {
"command": "uvx",
"args": ["generate-data-mcp"],
"env": {
"GENERATE_DATA_API_KEY": "your-uuid-key-here"
}
}
}
}uvx fetches and runs the latest published version on demand — no separate install step, nothing to update by hand. Restart your client and the 14 gd_* tools are available.
Do not commit a config file containing your real API key.
# run once, ad hoc:
uvx generate-data-mcp
# or install it as a persistent CLI tool:
uv tool install generate-data-mcppip install generate-data-mcpFor local development against this repo directly:
git clone https://github.com/ns-3e/generate-data-mcp.git
cd generate-data-mcp
pip install -e ".[dev]"Verify it works
export GENERATE_DATA_API_KEY=your-key
generate-data-mcpFrom your MCP client, invoke gd_get_usage — it should return your tier and call counts. Then invoke gd_list_field_types — it should return the category map.
Bam — you're ready to generate data.
Ask your agent something like "generate 50 rows of fake e-commerce customers as CSV" and it will call gd_design_schema then gd_generate_dataset on its own.
Related MCP server: Http-tools Universal MCP Server
Quick start
A typical session looks like this — the agent chains tools on its own, you just describe the outcome:
Discover what's possible.
gd_list_field_types— see every field type, grouped by category.Design a schema.
gd_design_schema(prompt="E-commerce customers with name, email, and signup date")— proposes afieldsarray from plain English.Generate the data.
gd_generate_dataset(fields=..., num_rows=10, format="csv")— returns the rows.Refine if needed. Call
gd_design_schemaagain, this time passingmessages(the running conversation) +current_schema(the priorproposed_schemaarray) together — it refines instead of proposing fresh.
Every tool returns the same envelope: {"ok": true, "summary": "...", "data": {...}} on success, or {"ok": false, "error": {"code": ..., "message": ..., "retriable": ..., "details": {...}}} on failure, with MCP's isError set to true. Errors always tell you what to do next, never a raw stack trace.
Large results
Small results come back inline. Text over 50,000 characters and binary over 32 KiB are saved in full to a new file and returned as data.file_path, with data.preview for text formats. Pass save_to_file: true to save a result of any size.
Files go to GENERATE_DATA_OUTPUT_DIR (default ~/generate-data-output). They're never overwritten and never deleted automatically, so clear the directory yourself when you're done. In the Docker image, that path is inside the container: mount a volume there and set GENERATE_DATA_OUTPUT_DIR to read the files from outside.
Local development
{
"env": { "GENERATE_DATA_API_BASE_URL": "http://localhost:8000" }
}Point at a locally running Django backend instead of the hosted API.
Migrating from v1
v2.0.0 renames every tool (breaking change). Old name → new name:
generate_data→gd_generate_datasetlist_field_types→gd_list_field_typesget_field_options→gd_get_field_type_optionspropose_schema→gd_design_schema(first call, nomessages/current_schema)refine_schema→gd_design_schema(passmessages+current_schematogether)get_api_usage→gd_get_usagelist_projects→gd_list_projects(now paginated:limit/offset)generate_project→gd_generate_project(binary formats now returned base64-encoded, not corrupted utf-8)
Reference
All 14 tools work on every plan, within that plan's limits.
Generate data
gd_generate_dataset — Generate rows from a field list.
format:csv,json,xml,yaml,sql,jsonl,parquet,xlsx, orhf-datasets(the last three return base64-encoded). Optionalsettings,ai_groups(Pro, forai_generatedcolumns that should relate) andsave_to_file. Returnsrowsandcalls_remainingwhen the API reports them.gd_generate_project — Generate all tables in a saved Project.
format:zip,xlsx,neo4j(base64-encoded),jsonld, orbundle.gd_generate_project_inline — Generate multi-table data once, without saving a Project. Same formats as
gd_generate_project.
Design and discover
gd_design_schema — Propose a dataset schema from natural language, or refine one by passing
messagesandcurrent_schema.gd_design_project — Propose a multi-table Project from natural language. Nothing is saved.
gd_list_field_types — List all field types grouped by category.
gd_get_field_type_options — Get the option schema for one field type.
field_typemust match^[a-z0-9_]+$.gd_validate_field_options — Check options for a field type without generating anything. Returns
is_validanderrors.gd_get_usage — Get your plan, calls today and limits.
Manage Projects
gd_list_projects — List your Projects, paginated (
limit/offset, default 20/0).gd_get_project — Get one Project with its tables and relationships.
gd_create_project — Save a Project from
name,tablesandrelationships.gd_update_project — Change a Project. Only the arguments you pass change, but each one replaces the saved value completely, so sending
tablesreplaces every table.gd_delete_project — Permanently delete a Project. Does nothing unless you pass
confirm: true.
Every tool declares read-only and destructive hints, so MCP clients can decide which calls need your approval. Read-only tools are retried automatically (up to twice) on connection failures, throttling and gateway errors. Anything that can create data or use quota is never retried automatically.
Tier limits (API key)
Capability | Free | Pro |
Max rows / request | 100 | 10,000 |
Max columns | 10 | 50 |
Max tables / project | 3 | 20 |
Dataset formats | CSV | CSV, JSON, XML, YAML, SQL, JSONL, Parquet, XLSX, HF Datasets |
Project formats | ZIP | ZIP, XLSX, Neo4j, JSON-LD, bundle |
Daily API calls | 10 | 1,000 |
Daily AI design calls ( | 3 | No daily quota |
Limits are enforced by the Django API, not this MCP server. Daily limits reset at 00:00 UTC. AI design calls have their own quota: they count toward your daily calls but aren't blocked by that limit. Rows added by duplication_config stay within the row limit, and many-to-many junction rows have their own budget equal to the row limit, so a project can deliver up to twice it. data.warnings says when rows were trimmed.
Configuration
Variable | Required | Default |
| Yes | — |
| No |
|
| No |
|
Error codes
| Meaning |
|
| Bad arguments, or the API rejected the request; | No |
| Invalid or deactivated API key | No |
| The plan doesn't allow this format or size | No |
| Per-minute limit ( | Per-minute yes, daily no |
| Unknown project id or field type | No |
| Format isn't offered by this tool | No |
| Missing key, unusable base URL, or unwritable output directory | No |
| Connection failure, timeout, or 502/503/504 | Yes |
| Unexpected API response | No |
Troubleshooting
Symptom | Fix |
| Set the variable in your MCP client config and restart the server |
| Use the site origin, such as |
| Point it at a writable directory |
| Invalid or deactivated key |
| Wait for |
| Reduce the request to fit your plan, or upgrade |
| Use a format listed for that tool: datasets and Projects support different formats |
| Value failed server-side validation before any request was sent — check spelling/type |
Development
git clone https://github.com/ns-3e/generate-data-mcp.git
cd generate-data-mcp
pip install -e ".[dev]"
pytest tests/ -vAPI docs
Docs live on generate-data.com. See this repo's tool docstrings (generate_data_mcp/server.py) for the authoritative request/response shapes.
Available Tools
8 toolsgenerate_dataC
Generate synthetic data rows. Returns CSV/text content or error message.
Inputs: fields (required), format, num_rows, settings. Returns: result
generate_projectC
Generate all tables in a Project. Returns ZIP bytes as text or JSON error.
Inputs: project_id (required), format. Returns: result
get_api_usageB
Get current API key usage stats.
Inputs: no named parameters. Returns: result
get_field_optionsB
Get configuration schema for a field type.
Inputs: field_type (required). Returns: result
list_field_typesA
List available field types grouped by category.
Inputs: no named parameters. Returns: result
list_projectsA
List user's Projects (Premium).
Inputs: no named parameters. Returns: result
propose_schemaC
Propose a schema from natural language.
Inputs: prompt (required), locale. Returns: result
refine_schemaC
Refine an existing schema via conversation.
Inputs: messages (required), current_schema (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool serves a distinct function: generating data, generating full projects, checking API usage, retrieving field options, listing fields, listing projects, proposing schemas, and refining schemas. No overlapping purposes.
All tool names follow a consistent verb_noun pattern with lowercase and underscores (e.g., generate_data, list_field_types). No mixing of styles.
With 8 tools, the set is well-scoped for the domain of synthetic data generation and schema management. It covers both creation and configuration without being overwhelming.
The tool set covers core workflows: generating data and projects, schema proposal/refinement, and listing field types and projects. Minor gaps exist (e.g., no delete or update for projects), but agents can still accomplish main tasks.
Maintenance
Related MCP Connectors
Unofficial Datafiniti MCP — wraps the Datafiniti Data API (datafiniti.co)
Data.gov MCP — wraps Data.gov CKAN API (catalog.data.gov/api/3)
Unofficial JSONPlaceholder MCP — wraps JSONPlaceholder fake REST API (free, no auth)
Unofficial ScrapeCreators MCP — wraps the ScrapeCreators social-media + ad-library scraping API…
Related MCP Servers
- AlicenseBqualityDmaintenanceA configurable MCP server that adapts any HTTP API into an MCP toolset with generic HTTP tools (GET, POST, PUT, DELETE) and pluggable authentication. Includes API discovery scripts and supports dynamic tool generation from OpenAPI specs or wordlist scans.51MIT
- AlicenseNot gradedqualityDmaintenanceProvides a standardized MCP interface for interacting with HTTP tools and services, enabling unified API access and management.MIT
- AlicenseAqualityDmaintenanceEnables MCP-capable clients to interact with OpenRefine's HTTP API for creating projects, applying operations, exporting CSV, and deleting projects.49MIT
- FlicenseNot gradedqualityDmaintenanceEnables MCP-compliant agents to perform data discovery, schema matching, and export via HTTP, with a mock mode for demonstration.-