Skip to main content

postal-lookup-mcp

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

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 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, 70% rev share.

Data

Postal data by Zippopotam.us, a free community lookup service covering ~60 countries. This project is not affiliated with Zippopotam.us.

Self-hosting over HTTP

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

Metadata

Release files for postal-lookup-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for postal-lookup-mcp 0.1.0
File Interpreter ABI Platform Actions
postal_lookup_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for postal_lookup_mcp-0.1.0-py3-none-any.whl

Release files / postal_lookup_mcp-0.1.0-py3-none-any.whl

Download URL postal_lookup_mcp-0.1.0-py3-none-any.whl
Size 6.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fefedbb6198bb277eb104cd1670e20d76f7939972d5cde8251484b53030a04e6
BLAKE2b-256 checksum
How to use checksums
b883c925a801fddc5dbed5a473222ec2b8b57224f67a4094c4b349b2861014f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.2

Security for postal-lookup-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

1 release file No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page