Mexico

About Mexico

Sepomex is a REST and MCP API providing access to Mexico's official postal code database (SEPOMEX), covering zip codes, states, municipalities, and cities across roughly 154,000 settlements. The dataset ships as a bundled SQLite database within the application, requiring no external database, API key, or rate limit for self-hosted deployments.

The API exposes four resources under /api/v1 — zip codes, states, municipalities, and cities — with show and paginated index endpoints for each. Zip code lookups can be filtered by zip code, state, city, or colony, individually or combined, with partial and accent-insensitive matching. List responses include pagination metadata and Link/X-Total-* headers. Interactive documentation is available via Swagger UI, with the raw spec published as OpenAPI 3.

As of v1.0.0, the same data is also exposed to AI agents through the Model Context Protocol, via both Streamable HTTP and stdio interfaces. The project is Dockerized with a multi-stage build and CI that publishes images to Docker Hub, and a free, best-effort hosted instance exists for prototyping, rate-limited to about 300 requests per 5 minutes per IP with no uptime guarantee. It is intended for developers who need Mexican postal/address data, either self-hosted for production use or via the public instance for quick testing.

Key features

• Query zip codes by zip_code, state, city, or colony with accent- and case-insensitive matching
• Four resources — zip codes, states, municipalities and cities — each with show and index endpoints
• Paginated list responses with meta.pagination block plus Link/X-Total headers
• Built-in MCP server exposing the data over Streamable HTTP and stdio for AI agents
• Bundled SQLite dataset (~154k settlements) with zero external dependencies
• Dockerized with a multi-stage build and one-command dev environment

Frequently asked questions