ZIP↔County Crosswalk MCP Server

A Model Context Protocol (MCP) server that lets Claude look up ZIP-to-county

and county-to-ZIP relationships, using HUD's official USPS ZIP Code

Crosswalk API — including residential-address overlap filtering, since ZIP

codes routinely cross county lines.

Architecture

flowchart LR
    Claude -->|MCP tool call| Server[zip-county-mcp server]
    Server -->|overlap ratios| HUD[HUD USPS Crosswalk API]
    Server -->|county names| BQ[(BigQuery:\ngeo_us_boundaries)]

Why this exists

ZIP codes and counties don't line up cleanly — a single ZIP can spread

across several counties, each holding a different share of that ZIP's

residential addresses. Most simple ZIP↔county lookups ignore this and just

return one answer, which is often wrong for the county holding a small

sliver of the ZIP. This server exposes HUD's real overlap-ratio data so a

caller can filter out negligible slivers via a `min_overlap_pct` threshold,

and get accurate county names via a BigQuery public dataset.

Example: ZIP `77494` (Katy, TX) is actually split across three counties —

Fort Bend (83.4%), Harris (16.5%), and Waller (0.17%). A caller who only

wants counties that meaningfully make up that ZIP can set

`min_overlap_pct=5` and get back just Fort Bend and Harris.

How overlap is actually measured

The overlap percentage comes straight from HUD's `res_ratio` field, and

it's worth being precise about what that field is (verified against

HUD's own API docs,

not assumed):

• It's a ratio of residential addresses, not population/headcount. A

single-person address and a five-person address both count as "1" toward

the ratio — addresses are a reasonable proxy for population, but not

the same measurement.

• The denominator flips with query direction. For `zip_to_county`

(HUD `type=2`), `res_ratio` is addresses-in-this-county ÷

addresses-in-the-whole-ZIP. For `zips_in_county` (HUD `type=7`, the

reverse lookup), it's addresses-in-this-ZIP ÷ addresses-in-**the-whole-

county**. Same field name, different denominator — which is why a

populous county like Harris shows dozens of ZIPs at only 1-3% each,

while a single ZIP can show one county at 80%+: the two percentages

aren't measuring against the same total.

Status

All three tools are implemented, tested (7 passing tests, `pytest`), and

verified end-to-end against live HUD + BigQuery data and a real Claude

Desktop connection.

Setup

1. Get a free HUD API account and Bearer token at

huduser.gov.

2. Confirm you have BigQuery access to `bigquery-public-data.geo_us_boundaries`

(e.g. via `gcloud auth application-default login`).

3. Copy `.env.example` to `.env` and fill in `HUD_API_TOKEN` and your Google

Cloud project.

4. Create a virtualenv with Python 3.10+ (the `mcp` package requires it —

on macOS the system `python3` is often older, so check `python3 --version`

first) and install dependencies:

python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt

5. Run it: `.venv/bin/python3 server.py`

Connecting to Claude Desktop

Add an entry to your `claude_desktop_config.json` (macOS:

`~/Library/Application Support/Claude/claude_desktop_config.json`):

"mcpServers": {
  "zip-county-mcp": {
    "command": "/absolute/path/to/zip-county-mcp/.venv/bin/python3",
    "args": ["/absolute/path/to/zip-county-mcp/server.py"]
  }
}

Fully quit and reopen Claude Desktop (MCP servers only load at startup), then

try one of the questions below.

Example usage

Once connected, just ask Claude in plain English — it picks the right tool

and arguments on its own. A few real examples (verified against live data):

Look up a single ZIP:

> "What county is ZIP 77002 in?"

Claude calls `zip_to_county("77002")` → ZIP 77002 (Houston, TX) is entirely

in Harris County, TX (FIPS 48201) — 100% overlap.

A ZIP that crosses county lines:

> "What counties does ZIP 77494 overlap, and by how much?"

Claude calls `zip_to_county("77494")` → three counties: Fort Bend (83.4%),

Harris (16.5%), Waller (0.17%). Ask a follow-up like *"only ones with at

least 5%"* and it re-calls with `min_overlap_pct=5`, dropping Waller's

negligible sliver.

Reverse lookup — ZIPs inside a county:

> "What ZIP codes are in Harris County, Texas?" (or give it the FIPS code,

> 48201, directly)

Claude calls `zips_in_county("48201")` → a list of every ZIP holding a

meaningful share of Harris County's residential addresses, sorted by

overlap.

A list of ZIP codes at once:

> "What counties are ZIP codes 77002, 77494, and 10001 each in?"

Claude calls `batch_zip_to_county(["77002", "77494", "10001"])` → one

result per ZIP in a single response, without querying BigQuery once per

ZIP behind the scenes.

Tools (v1 scope)

• `zip_to_county(zip_code, min_overlap_pct=0)` — county/counties for a ZIP, with % overlap
• `zips_in_county(county_fips, min_overlap_pct=0)` — ZIP codes in a county, with % overlap
• `batch_zip_to_county(zip_codes, min_overlap_pct=0)` — same as above, multiple ZIPs at once

Out of scope for v1: census tract-level lookups, CBSA/congressional district

crosswalks, caching layer, other geography types.

Testing

.venv/bin/pip install -r requirements.txt
.venv/bin/python3 -m pytest tests/ -v

Tests mock HUD's API responses (`httpx.MockTransport`) and the BigQuery

name lookup, so they run in about a second with no live token or BigQuery

access required.