Generate-Data
MCP server for Generate-Data.com: dataset generation, AI schema design, Project management.
Open source Open in the app JSON README (API)
About
MCP server for Generate-Data.com: dataset generation, AI schema design, Project management.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- ns-3e
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.0.1
- Last push
- 2026-08-03T18:15:28Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:57
- Updated
- 2026-08-29 04:00:57
- Origin id
io.github.ns-3e/generate-data-mcp
README
# generate-data-mcp
<!-- mcp-name: io.github.ns-3e/generate-data-mcp -->
[](https://pypi.org/project/generate-data-mcp/)
An MCP server for [Generate-Data.com](https://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](https://generate-data.com).
<details open>
<summary><strong>Claude Desktop / Cursor (recommended)</strong></summary>
Add this to your MCP client config (Claude Desktop: `claude_desktop_config.json`; Cursor: `.cursor/mcp.json`):
```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 7 `gd_*` tools are available.
> Do not commit a config file containing your real API key.
</details>
<details>
<summary><strong>uv / uvx (any MCP client)</strong></summary>
```bash
# run once, ad hoc:
uvx generate-data-mcp
# or install it as a persistent CLI tool:
uv tool install generate-data-mcp
```
</details>
<details>
<summary><strong>pip (fallback)</strong></summary>
```bash
pip install generate-data-mcp
```
For local development against this repo directly:
```bash
git clone https://github.com/ns-3e/generate-data-mcp.git
cd generate-data-mcp
pip install -e ".[dev]"
```
</details>
### Verify it works
```bash
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
```json
{
"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_data_mcp/server.py)** — Generate synthetic dataset rows from a field list. `format`: `csv`, `json`, `xml`, `parquet`, or `zip` (binary formats return base64-encoded).
- **[gd_list_field_types](./generate_data_mcp/server.py)** — List all available field types grouped by category. Takes no arguments.
- **[gd_get_field_type_options](./generate_data_mcp/server.py)** — Get the configuration option schema for one field type. `field_type` must match `^[a-z0-9_]+$`.
- **[gd_design_schema](./generate_data_mcp/server.py)** — 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](./generate_data_mcp/server.py)** — 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](./generate_data_mcp/server.py)** — List the user's Projects, paginated (`limit`/`offset`, default 20/0).
- **[gd_generate_project](./generate_data_mcp/server.py)** — Generate all tables in a Project and download the result. Same format/binary rules as `gd_generate_dataset`.
### Tier limits (API key)
| Capability | Free | Premium |
|------------|------|---------|
| Max rows / request | 100 | 100,000 |
| Max columns | 10 | 50 |
| Formats | CSV | CSV, JSON, XML, Parquet |
| Daily API calls | 10 | 1,000 |
Limits are enforced by the Django API, not this MCP server.
## Configuration
| Variable | Required | Default |
|----------|----------|---------|
| `GENERATE_DATA_API_KEY` | Yes | — |
| `GENERATE_DATA_API_BASE_URL` | No | `https://api.generate-data.com` |
## Troubleshooting
| Symptom | Fix |
|---------|-----|
| `GENERATE_DATA_API_KEY is required` | Set env var before starting the server |
| HTTP 401 / `auth_failed` | Invalid or deactivated key |
| HTTP 429 / `rate_limited` | Per-minute or daily cap hit; wait or upgrade tier |
| HTTP 403 / `tier_forbidden` | Free tier lacks access; upgrade plan |
| `unsupported_format` | `format` must be one of `csv`, `json`, `xml`, `parquet`, `zip` |
| `invalid_input` on a field type or project ID | Value failed server-side validation before any request was sent — check spelling/type |
## Development
```bash
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](https://generate-data.com). See this repo's tool docstrings (`generate_data_mcp/server.py`) for the authoritative request/response shapes.