dataset-mcp

MCP server over the jayjex 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.

Full data lives in a public GitHub release (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.

Datasets

Browse the full catalog at 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.

Tools

• list_datasets(): every dataset in the catalog plus full-query availability and release sizes.
• get_dataset_info(slug): catalog entry merged with the release manifest: file list with row counts, byte sizes, SHA-256, attribution, and query tips.
• get_sample(slug, format): free preview rows, about 22 per dataset.
• 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.
• get_stats(slug, {file?, column?, top?}): row count, non-empty and unique counts, numeric min/max/mean, top-N value frequencies.

Query examples

New York, NY rents from the FY2027 ZIP table (51,871 rows, rates effective October 1, 2026):

query_dataset("hud-fmr-2027", {
  where: [{ column: "state", op: "=", value: "NY" }],
  limit: 5
})

Returns total_matched: 2397 with rows like:

{
  "zip": "10001",
  "area_name": "New York, NY HUD Metro FMR Area",
  "state": "NY",
  "fmr_2br": "4460"
}

Texas rents from the FY2026 ZIP table:

query_dataset("hud-fmr-2026", {
  where: [{ column: "state", op: "=", value: "TX" }],
  limit: 5
})

Returns total_matched: 3247 with rows like:

{
  "zip": "76437",
  "area_name": "Abilene, TX MSA",
  "state": "TX",
  "fmr_2br": "1090"
}

Every 2025 NFL game (285 matched):

query_dataset("nfl-games", {
  where: [{ column: "season", op: "=", value: 2025 }],
  limit: 10
})

NYC Airbnb price stats:

get_stats("airbnb-six-cities", { file: "airbnb-new-york-city.csv", column: "price" })

Returns rows: 30234, min: 4.58, max: 31210.79, mean: 267.35 plus the most common prices.

Filter JSON without converting to CSV:

query_dataset("earn-bounties", {
  where: [{ column: "rewardAmount", op: "gt", value: 5000 }],
  columns: ["title", "rewardAmount", "token"]
})

format: "csv" returns the page as CSV text if your pipeline prefers raw rows.

Config

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dataset-mcp": {
      "command": "npx",
      "args": ["-y", "github:jayjex/dataset-mcp"]
    }
  }
}

pi, Codex, or other TOML-based agents:

[mcp_servers.dataset-mcp]
command = "npx"
args = ["-y", "github:jayjex/dataset-mcp"]

npm 12 refuses git-based installs by default (EALLOWGIT). Pass the flag through npx:

{
  "mcpServers": {
    "dataset-mcp": {
      "command": "npx",
      "args": ["--allow-git=all", "-y", "github:jayjex/dataset-mcp"]
    }
  }
}

or set allow-git=github.com once in your ~/.npmrc. npm 10 and 11 need no flag.

Once the npm package is published, npx -y @jayjex/dataset-mcp does the same thing as the git form, with no allow-git flag needed.

How it works

Three HTTPS sources, no API key, no auth, no tracking:

• https://jayjex.github.io/data-vault/catalog.json: dataset index (cached 10 minutes).
• 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).
• https://github.com/jayjex/dataset-mcp/releases/download/data-v1/<file>: the full files themselves, streamed into the local cache on first query.

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

Environment overrides:

• DATA_VAULT_CATALOG_URL: catalog URL (default above).
• DATA_VAULT_SAMPLE_BASE: sample base URL (default https://jayjex.github.io/data-vault/data).
• DATASET_MCP_MANIFEST_URL: manifest URL (default above).
• DATASET_MCP_CACHE_DIR: cache directory (default ~/.cache/dataset-mcp).

Licenses

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

Roadmap

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