# postal-lookup-mcp

**Resolve any postal/ZIP code to its place name, state/region, and coordinates. Free, in one command.**

```bash
pip install postal-lookup-mcp   # or: uvx postal-lookup-mcp
```

Then ask your agent: *"what city is ZIP 90210 in?"* or *"where is postal code SW1A in the UK?"*

No API key. No signup. Free.

## Tools

| Tool | What the model sees it for |
|---|---|
| `lookup_postal_code(country_code, postal_code)` | Resolve a postal/ZIP code to place name(s), state/region, and lat/lon. "What city is ZIP 90210 in?", "where is postal code X in country Y?" |

`country_code` is a 2-letter ISO code (US, GB, DE, ...). `postal_code` format varies by country. Some postal codes span multiple places, in which case all of them come back in `places[]`.

## Example

```
> lookup_postal_code("us", "90210")
{
  "country": "United States",
  "country_abbreviation": "US",
  "postal_code": "90210",
  "places": [
    {
      "place_name": "Beverly Hills",
      "state": "California",
      "state_abbreviation": "CA",
      "latitude": "34.0901",
      "longitude": "-118.4065"
    }
  ],
  "attribution": "Postal data by Zippopotam.us (zippopotam.us)"
}
```

A code that isn't recognized comes back as a clean error, never a crash:

```
> lookup_postal_code("us", "00000")
{
  "error": "No place found for postal code \"00000\" in country \"US\" — check the code and the 2-letter country code (US, GB, DE, ...), or the country may not be covered.",
  "attribution": "Postal data by Zippopotam.us (zippopotam.us)"
}
```

## How it's free

This server is part of the [Lulu Ads](https://getlulu.dev/publishers) network:
tool results may carry one clearly labeled, disclosed `sponsored` data field
(never instructions, never hidden). That sponsorship pays the hosting, so the
lookup stays free. Fail-open by design — if the ads backend is slow, down,
or (as with a local install) has no credentials at all, the tools behave
exactly like an unmonetized server.

Run your own MCP? The same one-line integration is open to every publisher —
[getlulu.dev/publishers](https://getlulu.dev/publishers), 70% rev share.

## Data

Postal data by [Zippopotam.us](https://zippopotam.us), a free community
lookup service covering ~60 countries. This project is not affiliated with
Zippopotam.us.

## Self-hosting over HTTP

```bash
pip install fastmcp lulu-ads httpx uvicorn
MCP_TRANSPORT=http POSTAL_LOCAL_DEV=1 python server.py   # serves http://localhost:8080/postal/mcp
```