{
  "markdown": "# dataset-mcp\n\nMCP server over the [jayjex Data Vault](https://jayjex.github.io/data-vault/). Sample data is free, and since v1.1.0 the full released files are queryable too: filter, paginate, and summarize every row without downloading anything yourself.\n\nFull data lives in a public GitHub release ([data-v1](https://github.com/jayjex/dataset-mcp/releases/tag/data-v1), 24 MB across 26 files). The server downloads a file once into `~/.cache/dataset-mcp/`, pins the cache to the manifest SHA-256, and then answers queries from memory.\n\nRun it with `npx -y @jayjex/dataset-mcp` (npm) or `npx -y github:jayjex/dataset-mcp` (repo). See Config below.\n\n## Datasets\n\nBrowse the full catalog at [jayjex.github.io/data-vault](https://jayjex.github.io/data-vault/): 51,895 HUD rent rows, 7,548 NFL games, 90,169 Airbnb listings. Samples are free, and this server queries the full files at no cost.\n\n| slug | what it is | rows | license |\n|---|---|---|---|\n| `nfl-games` | NFL games with scores, closing spreads, totals, moneylines, 1999-2026 | 7,548 + 2 derived tables | CC BY 4.0 (nflverse) |\n| `hud-fmr-2026` | HUD Fair Market Rents FY2026, rent by ZIP, county, and state | 51,895 + 2 tables | Public domain (US government data) |\n| `hud-fmr-2027` | HUD Fair Market Rents FY2027, effective October 1, 2026, same three tables | 51,871 + 2 tables | Public domain (US government data) |\n| `airbnb-six-cities` | Airbnb listings in Austin, Nashville, Denver, NYC, Las Vegas, San Diego | 90,169 across 6 files | CC BY 4.0 (Inside Airbnb) |\n| `earn-bounties` | Superteam Earn listings: cards, full descriptions, 186+ API routes | 51 cards / 28 descriptions | Public API aggregate |\n| `scraper-pack` | Playwright scraping scripts (samples only) | n/a | See data-vault page |\n\n## Tools\n\n- `list_datasets()`: every dataset in the catalog plus full-query availability and release sizes.\n- `get_dataset_info(slug)`: catalog entry merged with the release manifest: file list with row counts, byte sizes, SHA-256, attribution, and query tips.\n- `get_sample(slug, format)`: free preview rows, about 22 per dataset.\n- `query_dataset(slug, {file?, columns?, where?, limit?, offset?, format?})`: filter and paginate the full file. `where` clauses support `=`, `contains` (case-insensitive), `gt`, `lt`; numeric compare when both sides are numeric, lexicographic fallback for dates and strings. 100 rows per call, `next_offset` pages through the rest.\n- `get_stats(slug, {file?, column?, top?})`: row count, non-empty and unique counts, numeric min/max/mean, top-N value frequencies.\n\n## Query examples\n\nNew York, NY rents from the FY2027 ZIP table (51,871 rows, rates effective October 1, 2026):\n\n```\nquery_dataset(\"hud-fmr-2027\", {\n  where: [{ column: \"state\", op: \"=\", value: \"NY\" }],\n  limit: 5\n})\n```\n\nReturns `total_matched: 2397` with rows like:\n\n```json\n{\n  \"zip\": \"10001\",\n  \"area_name\": \"New York, NY HUD Metro FMR Area\",\n  \"state\": \"NY\",\n  \"fmr_2br\": \"4460\"\n}\n```\n\nTexas rents from the FY2026 ZIP table:\n\n```\nquery_dataset(\"hud-fmr-2026\", {\n  where: [{ column: \"state\", op: \"=\", value: \"TX\" }],\n  limit: 5\n})\n```\n\nReturns `total_matched: 3247` with rows like:\n\n```json\n{\n  \"zip\": \"76437\",\n  \"area_name\": \"Abilene, TX MSA\",\n  \"state\": \"TX\",\n  \"fmr_2br\": \"1090\"\n}\n```\n\nEvery 2025 NFL game (285 matched):\n\n```\nquery_dataset(\"nfl-games\", {\n  where: [{ column: \"season\", op: \"=\", value: 2025 }],\n  limit: 10\n})\n```\n\nNYC Airbnb price stats:\n\n```\nget_stats(\"airbnb-six-cities\", { file: \"airbnb-new-york-city.csv\", column: \"price\" })\n```\n\nReturns `rows: 30234, min: 4.58, max: 31210.79, mean: 267.35` plus the most common prices.\n\nFilter JSON without converting to CSV:\n\n```\nquery_dataset(\"earn-bounties\", {\n  where: [{ column: \"rewardAmount\", op: \"gt\", value: 5000 }],\n  columns: [\"title\", \"rewardAmount\", \"token\"]\n})\n```\n\n`format: \"csv\"` returns the page as CSV text if your pipeline prefers raw rows.\n\n## Config\n\nFrom npm (works everywhere, no git access needed):\n\n```json\n{\n  \"mcpServers\": {\n    \"dataset-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@jayjex/dataset-mcp\"]\n    }\n  }\n}\n```\n\npi, Codex, or other TOML-based agents:\n\n```toml\n[mcp_servers.dataset-mcp]\ncommand = \"npx\"\nargs = [\"-y\", \"@jayjex/dataset-mcp\"]\n```\n\nFrom GitHub (same server, pulls the repo instead of the npm tarball):\n\nClaude Desktop (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"dataset-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:jayjex/dataset-mcp\"]\n    }\n  }\n}\n```\n\nnpm 12 refuses git-based installs by default (`EALLOWGIT`). Pass the flag through npx:\n\n```json\n{\n  \"mcpServers\": {\n    \"dataset-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"--allow-git=all\", \"-y\", \"github:jayjex/dataset-mcp\"]\n    }\n  }\n}\n```\n\nor set `allow-git=github.com` once in your `~/.npmrc`. npm 10 and 11 need no flag.\n\n## How it works\n\nThree HTTPS sources, no API key, no auth, no tracking:\n\n- `https://jayjex.github.io/data-vault/catalog.json`: dataset index (cached 10 minutes).\n- `https://raw.githubusercontent.com/jayjex/dataset-mcp/main/data/manifest.json`: release manifest with per-file SHA-256, rows, bytes, and download URLs (cached 10 minutes).\n- `https://github.com/jayjex/dataset-mcp/releases/download/data-v1/<file>`: the full files themselves, streamed into the local cache on first query.\n\nA cached file is re-verified against the manifest hash on every load, so a stale or corrupted cache triggers one fresh download instead of serving wrong data. If a tool returns a network error, check that your agent can reach github.com and raw.githubusercontent.com.\n\nEnvironment overrides:\n\n- `DATA_VAULT_CATALOG_URL`: catalog URL (default above).\n- `DATA_VAULT_SAMPLE_BASE`: sample base URL (default `https://jayjex.github.io/data-vault/data`).\n- `DATASET_MCP_MANIFEST_URL`: manifest URL (default above).\n- `DATASET_MCP_CACHE_DIR`: cache directory (default `~/.cache/dataset-mcp`).\n\n## Licenses\n\nMIT for the server code. Per-dataset licenses ship in the manifest and in `get_dataset_info`: public domain for US government data, CC BY 4.0 where the sources require attribution (nflverse, Inside Airbnb). Keep the attribution lines when you republish the data.\n\n## Roadmap\n\nQuery access is free and unlimited. A paid per-call tier over x402 is planned for high-volume commercial scraping of the same files; the free query path stays.\n",
  "bytes": 6324,
  "sha": "ba15407a4c07f1b4ec6fbdcd3112cb3215d2865df305306dc2eae19218c52b82",
  "repo_slug": "jayjex/dataset-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jayjex_dataset_mcp_f56f25d7/readme"
}