{
  "markdown": "# generate-data-mcp\n\n<!-- mcp-name: io.github.ns-3e/generate-data-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/generate-data-mcp)](https://pypi.org/project/generate-data-mcp/)\n\nAn 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.\n\nThin 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.\n\n## Installation (30-second setup)\n\nYou need a Generate-Data.com API key first — create one in **Settings → API Access** on [generate-data.com](https://generate-data.com).\n\n<details open>\n<summary><strong>Claude Desktop / Cursor (recommended)</strong></summary>\n\nAdd this to your MCP client config (Claude Desktop: `claude_desktop_config.json`; Cursor: `.cursor/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"generate-data\": {\n      \"command\": \"uvx\",\n      \"args\": [\"generate-data-mcp\"],\n      \"env\": {\n        \"GENERATE_DATA_API_KEY\": \"your-uuid-key-here\"\n      }\n    }\n  }\n}\n```\n\n`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.\n\n> Do not commit a config file containing your real API key.\n\n</details>\n\n<details>\n<summary><strong>uv / uvx (any MCP client)</strong></summary>\n\n```bash\n# run once, ad hoc:\nuvx generate-data-mcp\n\n# or install it as a persistent CLI tool:\nuv tool install generate-data-mcp\n```\n\n</details>\n\n<details>\n<summary><strong>pip (fallback)</strong></summary>\n\n```bash\npip install generate-data-mcp\n```\n\nFor local development against this repo directly:\n\n```bash\ngit clone https://github.com/ns-3e/generate-data-mcp.git\ncd generate-data-mcp\npip install -e \".[dev]\"\n```\n\n</details>\n\n### Verify it works\n\n```bash\nexport GENERATE_DATA_API_KEY=your-key\ngenerate-data-mcp\n```\n\nFrom 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.\n\n### Bam — you're ready to generate data.\n\nAsk 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.\n\n## Quick start\n\nA typical session looks like this — the agent chains tools on its own, you just describe the outcome:\n\n1. **Discover what's possible.** `gd_list_field_types` — see every field type, grouped by category.\n2. **Design a schema.** `gd_design_schema(prompt=\"E-commerce customers with name, email, and signup date\")` — proposes a `fields` array from plain English.\n3. **Generate the data.** `gd_generate_dataset(fields=..., num_rows=10, format=\"csv\")` — returns the rows.\n4. **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.\n\nEvery 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.\n\n### Local development\n\n```json\n{\n  \"env\": { \"GENERATE_DATA_API_BASE_URL\": \"http://localhost:8000\" }\n}\n```\n\nPoint at a locally running Django backend instead of the hosted API.\n\n### Migrating from v1\n\nv2.0.0 renames every tool (breaking change). Old name → new name:\n\n- `generate_data` → `gd_generate_dataset`\n- `list_field_types` → `gd_list_field_types`\n- `get_field_options` → `gd_get_field_type_options`\n- `propose_schema` → `gd_design_schema` (first call, no `messages`/`current_schema`)\n- `refine_schema` → `gd_design_schema` (pass `messages` + `current_schema` together)\n- `get_api_usage` → `gd_get_usage`\n- `list_projects` → `gd_list_projects` (now paginated: `limit`/`offset`)\n- `generate_project` → `gd_generate_project` (binary formats now returned base64-encoded, not corrupted utf-8)\n\n## Reference\n\nAll 7 tools, split by tier.\n\n### Free tier\n\n- **[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).\n- **[gd_list_field_types](./generate_data_mcp/server.py)** — List all available field types grouped by category. Takes no arguments.\n- **[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_]+$`.\n- **[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.\n- **[gd_get_usage](./generate_data_mcp/server.py)** — Get current API key usage stats: calls today, tier, limits. Takes no arguments.\n\n### Premium tier\n\nRequires a Premium API key — Free-tier keys get a `tier_forbidden` error.\n\n- **[gd_list_projects](./generate_data_mcp/server.py)** — List the user's Projects, paginated (`limit`/`offset`, default 20/0).\n- **[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`.\n\n### Tier limits (API key)\n\n| Capability | Free | Premium |\n|------------|------|---------|\n| Max rows / request | 100 | 100,000 |\n| Max columns | 10 | 50 |\n| Formats | CSV | CSV, JSON, XML, Parquet |\n| Daily API calls | 10 | 1,000 |\n\nLimits are enforced by the Django API, not this MCP server.\n\n## Configuration\n\n| Variable | Required | Default |\n|----------|----------|---------|\n| `GENERATE_DATA_API_KEY` | Yes | — |\n| `GENERATE_DATA_API_BASE_URL` | No | `https://api.generate-data.com` |\n\n## Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `GENERATE_DATA_API_KEY is required` | Set env var before starting the server |\n| HTTP 401 / `auth_failed` | Invalid or deactivated key |\n| HTTP 429 / `rate_limited` | Per-minute or daily cap hit; wait or upgrade tier |\n| HTTP 403 / `tier_forbidden` | Free tier lacks access; upgrade plan |\n| `unsupported_format` | `format` must be one of `csv`, `json`, `xml`, `parquet`, `zip` |\n| `invalid_input` on a field type or project ID | Value failed server-side validation before any request was sent — check spelling/type |\n\n## Development\n\n```bash\ngit clone https://github.com/ns-3e/generate-data-mcp.git\ncd generate-data-mcp\npip install -e \".[dev]\"\npytest tests/ -v\n```\n\n## API docs\n\nDocs 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.\n",
  "bytes": 6811,
  "sha": "3f1241ea50defa0cd618178582e6849d80c915975d1b55a6f4207e8b3efe1202",
  "repo_slug": "ns-3e/generate-data-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ns_3e_generate_data_mcp_8cad7e7c/readme"
}