Demo mode, no key
Connect without a key and every tool answers with real, current data. Deeper fields are withheld: masked text and null mean withheld, not missing, and each answer says so. Nothing is charged.
Your key, full answers
Send your API key in the X-Api-Key header for complete answers. A tool call costs the same credits as its REST endpoint; reference tools are free. A free key comes with 2,500 credits a day.
Connect
Claude Code
claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp
# with your key
claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp --header "X-Api-Key: YOUR_KEY"Claude and Claude Desktop
Settings → Connectors → Add custom connector, and paste the server URL. A client that can't send the X-Api-Key header runs in demo mode.
Cursor, Windsurf and other mcpServers clients
{
"mcpServers": {
"zip-codes": {
"url": "https://mcp.zip-codes.com/mcp",
"headers": { "X-Api-Key": "YOUR_KEY" }
}
}
}VS Code
{
"servers": {
"zip-codes": {
"type": "http",
"url": "https://mcp.zip-codes.com/mcp",
"headers": { "X-Api-Key": "YOUR_KEY" }
}
}
}Leave out headers for demo mode. Most clients load new tools in a new chat.
Tools
Each API tool takes the same include flags as its endpoint and returns the same JSON, so the API documentation describes every field.
| Tool | What it does | REST endpoint |
|---|---|---|
distanceDistance between two places | Distance between two places, in miles and kilometres, plus the compass bearing from the first to the second. | /v2/distance |
quick_zipQuick ZIP / ZIP+4 / reverse geocode | The fast, small answer for a postal code. | /v2/quick-zip |
radius_searchRadius search | Find every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each. | /v2/radius |
suggest_placesPlace search (type-ahead) | Search for a place by partial name, misspelled name, or partial code. | /v2/suggest |
validate_addressValidate a US address | Validate and standardise a US street address and return its ZIP+4. | /v2/address |
zip_lookupZIP Code lookup | The full record for a postal code. | /v2/zip |
about_dataAbout this data | Where this server's data comes from: for each dataset the authority behind it, the edition served where the source publishes editions (TIGER/Line, ACS, ZCTA), how often a new release is taken, and a ready-made citation string. | reference · free |
city_name_rulesCity name rules | How USPS names a ZIP Code, and which of those names may be used on mail. | reference · free |
county_referenceCounty reference | US counties and county equivalents. | reference · free |
metro_area_referenceMetro area reference | US metropolitan and micropolitan statistical areas (CBSAs). | reference · free |
zip_factsZIP Code facts | Statistics about US ZIP Codes and Canadian postal codes: how many exist, how they break down by type, delivery point and carrier route totals, per-state tables, and ranked lists such as the ZIP Codes with the most carrier routes. | reference · free |
Get a key
A free key gives complete answers and 2,500 credits a day. Subscriptions and credit packs add more credits and batch endpoints for larger jobs.
More
- llms.txt: this page for agents.
- Overview page: what the server does, how to connect, demo mode versus a key.
- REST API llms.txt: endpoints, credits and include flags.
- Data sources: license, vintages and refresh cadence per source.
- Bugs and feature requests: jharris@zip-codes.com.