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: 7 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.

{
  "mcpServers": {
    "generate-data": {
      "command": "uvx",
      "args": ["generate-data-mcp"],
      "env": {
        "GENERATE_DATA_API_KEY": "your-uuid-key-here"
      }
    }
  }
}

# run once, ad hoc:
uvx generate-data-mcp

# or install it as a persistent CLI tool:
uv tool install generate-data-mcp

pip install generate-data-mcp

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-mcp

From 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.

Quick start

A typical session looks like this — the agent chains tools on its own, you just describe the outcome:

1. Discover what's possible. gd_list_field_types — see every field type, grouped by category.
2. Design a schema. gd_design_schema(prompt="E-commerce customers with name, email, and signup date") — proposes a fields array from plain English.
3. Generate the data. gd_generate_dataset(fields=..., num_rows=10, format="csv") — returns the rows.
4. Refine if needed. Call gd_design_schema again, this time passing messages (the running conversation) + current_schema (the prior result) 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": ...}} on failure — errors always tell you what to do next, never a raw stack trace.

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_dataset
• list_field_types → gd_list_field_types
• get_field_options → gd_get_field_type_options
• propose_schema → gd_design_schema (first call, no messages/current_schema)
• refine_schema → gd_design_schema (pass messages + current_schema together)
• get_api_usage → gd_get_usage
• list_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 7 tools, split by tier.

Free tier

• gd_generate_dataset — Generate synthetic dataset rows from a field list. format: csv, json, xml, parquet, or zip (binary formats return base64-encoded).
• gd_list_field_types — List all available field types grouped by category. Takes no arguments.
• gd_get_field_type_options — Get the configuration option schema for one field type. field_type must match ^[a-z0-9_]+$.
• gd_design_schema — Design a dataset schema from natural language, or refine an existing one — one tool for both the first proposal and follow-up conversation turns.
• gd_get_usage — Get current API key usage stats: calls today, tier, limits. Takes no arguments.

Premium tier

Requires a Premium API key — Free-tier keys get a tier_forbidden error.

• gd_list_projects — List the user's Projects, paginated (limit/offset, default 20/0).
• gd_generate_project — Generate all tables in a Project and download the result. Same format/binary rules as gd_generate_dataset.

Tier limits (API key)

Limits are enforced by the Django API, not this MCP server.

Configuration

Troubleshooting

Development

git clone https://github.com/ns-3e/generate-data-mcp.git
cd generate-data-mcp
pip install -e ".[dev]"
pytest tests/ -v

API docs

Docs live on generate-data.com. See this repo's tool docstrings (generate_data_mcp/server.py) for the authoritative request/response shapes.