# ZIP Codes MCP Server

> US ZIP Code and Canadian postal code data as tools for AI agents, over the Model Context Protocol (Streamable HTTP, stateless, read-only). Server URL https://mcp.zip-codes.com/mcp. No key needed to start: without one, every tool answers in demo mode (real, current values; deeper fields withheld). With a key (X-Api-Key header) answers are complete and cost the same credits as the REST API.

## Connect

- Claude Code: claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp
- Claude Code with a key: claude mcp add --transport http zip-codes https://mcp.zip-codes.com/mcp --header "X-Api-Key: YOUR_KEY"
- Any client that takes a JSON config: {"mcpServers":{"zip-codes":{"url":"https://mcp.zip-codes.com/mcp","headers":{"X-Api-Key":"YOUR_KEY"}}}} (omit headers for demo mode).
- Claude and Claude Desktop custom connectors: add the server URL; a client that can't send the X-Api-Key header runs in demo mode.

## Demo mode and keys

- No key: real, current values; withheld text reads as asterisks and withheld numbers and true/false as null. Withheld is not missing: a key returns those fields. Each free-tier answer opens with a short notice saying so. Demo answers are not charged.
- Free key: 2,500 credits a day, complete answers: https://www.zip-codes.com/api/signup?utm_source=mcp&utm_medium=home
- A keyed tool call costs exactly what its REST endpoint costs; reference tools are free. Pricing: https://www.zip-codes.com/api/pricing

## Tools

- distance (calls /v2/distance, https://api.zip-codes.com/docs#distance): Distance between two places, in miles and kilometres, plus the compass bearing from the first to the second.
- quick_zip (calls /v2/quick-zip, https://api.zip-codes.com/docs#quick-zip): The fast, small answer for a postal code.
- radius_search (calls /v2/radius, https://api.zip-codes.com/docs#radius): Find every US ZIP Code and Canadian postal area within a radius of a centre point, with the distance to each.
- suggest_places (calls /v2/suggest, https://api.zip-codes.com/docs#suggest): Search for a place by partial name, misspelled name, or partial code.
- validate_address (calls /v2/address, https://api.zip-codes.com/docs#address): Validate and standardise a US street address and return its ZIP+4.
- zip_lookup (calls /v2/zip, https://api.zip-codes.com/docs#zip-details): The full record for a postal code.
- about_data (built-in reference data, free, no key): 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.
- city_name_rules (built-in reference data, free, no key): How USPS names a ZIP Code, and which of those names may be used on mail.
- county_reference (built-in reference data, free, no key): US counties and county equivalents.
- metro_area_reference (built-in reference data, free, no key): US metropolitan and micropolitan statistical areas (CBSAs).
- zip_facts (built-in reference data, free, no key): 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.

## More

- [REST API for agents](https://api.zip-codes.com/llms.txt): endpoints, credits and flags; the tools take the same include flags as their endpoints.
- [Overview page](https://www.zip-codes.com/api/mcp): what the server does, how to connect, demo mode versus a key.
- [API documentation](https://api.zip-codes.com/docs)
- [Data sources](https://api.zip-codes.com/docs#data-sources): license, vintages and refresh cadence per source.
- [Get a free key](https://www.zip-codes.com/api/signup?utm_source=mcp&utm_medium=home) and [pricing](https://www.zip-codes.com/api/pricing).
- Bugs and feature requests: jharris@zip-codes.com.