ustaxrecords-mcp

USTaxRecords MCP server (read-only POC)

A Model Context Protocol server that exposes the USTaxRecords tax-sale dataset to AI assistants and agents as tools. It reads the same normalized data the website serves (../public/data/states/*.json) — read-only, no network, no writes, no payments.

This is Step 2 of the agent-monetization roadmap (see the "Agent-monetization / data-API track" section in planning.md): ship a free tool interface first to prove demand, before any billing (Stripe/x402) is considered. Every result carries provenance (source_url, last_verified) and an explicit data_tier so consumers see the county-verified vs. state-statute-framework distinction honestly.

Tools

Tool	What it returns
list_states	All 51 jurisdictions with auction type + county-verified vs framework record counts (coverage overview).
get_state_tax_sale_rules	A state's statutory rules: auction type, redemption period, interest/penalty, bid method, sale frequency, OTC, statute URL.
get_county_tax_sale	One county's sale record(s): type, schedule, next confirmed date, online platform, source URL, verification date, tier.
search_upcoming_tax_sales	Counties with a confirmed upcoming date in a window. Filters: state, days_ahead (default 90), online_only, verified_only.
find_online_tax_auctions	Counties whose sales run on an online platform (GovEase, Bid4Assets, RealAuction, …). Filters: state, platform.

All tools are annotated readOnlyHint: true.

Data tiers (important)

• county_verified — confirmed on the county's own official page.
• state_statute_framework — describes only the state-law process; NOT county-verified. Filter these out with verified_only: true on search_upcoming_tax_sales.

Where the data comes from

Two modes, chosen automatically — you don't configure anything:

Situation	Source
Run from inside this repo	../public/data/states/*.json (fast, offline, matches your working tree)
Installed anywhere else	Fetched over HTTPS from https://ustaxrecords.com/data at startup

Data is fetched, never bundled. This is a calendar: a snapshot frozen at publish time would silently serve dead sale dates under a "verified" label as it aged. An installed copy always reflects the current deploy.

Set USTAXRECORDS_DATA_URL to force the remote path (or point at a staging deploy):

USTAXRECORDS_DATA_URL=https://ustaxrecords.com/data npm run smoke

Requires Node >= 18 (global fetch, top-level await).

Run it

From inside this repo:

cd mcp-server
npm install
npm start          # serves over stdio
npm run smoke      # end-to-end self-test (spawns the server as a client, exercises every tool)

Use it in an MCP client (e.g. Claude Desktop)

Add to your client's MCP config (claude_desktop_config.json → mcpServers).

Once published to npm, no clone or absolute path is needed:

{
  "mcpServers": {
    "ustaxrecords": {
      "command": "npx",
      "args": ["-y", "ustaxrecords-mcp"]
    }
  }
}

Running from a local clone instead — use an absolute path to index.mjs:

{
  "mcpServers": {
    "ustaxrecords": {
      "command": "node",
      "args": ["C:/projects/ustaxrecords/mcp-server/index.mjs"]
    }
  }
}

Then ask, e.g.: "Find online tax-deed sales in Arkansas in the next 60 days" → the assistant calls search_upcoming_tax_sales.

Demand instrumentation (Step 2d)

The server emits structured JSONL to stderr — the raw demand signal for deciding whether to pursue paid tiers. stdout is the JSON-RPC channel, so logs go to stderr; when this server is hosted, the platform captures stderr. Set USTAXRECORDS_MCP_LOG=0 to silence.

• client_connected — one line per session with the MCP client's name + version (from the initialize handshake). This is the cleanest per-client demand read — e.g. Claude Desktop vs. Cursor vs. a custom agent.
• tool_call — one line per invocation: tool, the filter args (state/date filters only — no PII), result_count, ms (latency), error, and client.

Example:

{"ts":"2026-07-11T19:49:06.022Z","event":"tool_call","tool":"search_upcoming_tax_sales","args":{"days_ahead":120,"verified_only":true},"result_count":336,"ms":2,"error":false,"client":{"name":"claude-desktop","version":"0.x"}}

What to watch (see the measurement plan + go/no-go threshold in planning.md Step 2d): repeat callers (same client over multiple weeks) matter far more than raw volume; which tools/args dominate tells you the flagship product. Keep logs within the site privacy posture (no PII is logged; disclose operational logging if/when hosted).

Not included (by design, for this POC)

• No authentication, rate limiting, billing, or crypto — those are later roadmap steps and gated on proven demand + a data-rights/liability review.
• No parcel-level property data (assessed value, owner, liens). This server serves jurisdiction-level sale schedules and rules only — the data the site actually holds.
• Remote/HTTP transport. This is a local stdio server; a hosted HTTP variant is a later step.

License — the code, not the data

This server's source code is MIT-licensed (see LICENSE). Use it, fork it, ship it.

The MIT license covers this ~15 kB client wrapper only — it is not a license to the tax-sale data, which the server fetches at runtime from https://ustaxrecords.com/data and which remains subject to the site's own terms. The two are deliberately separate: the code is a convenience, the dataset is the work.

The underlying records are drawn from public government sources, and each one carries the source_url it was verified against. When you use this data, cite that official source rather than presenting our copy as the record of authority.

Legal

Independent directory; not a government agency; not legal, tax, or investment advice. The disclaimer is embedded in the server instructions and every tool response.