Repository avatar
Other Tools
v0.1.1
active

postalkit-mcp

io.github.postalkit/postalkit-mcp

Mexican postal codes (SEPOMEX), colonias, municipalities, streets and geocoding via PostalKit.

Documentation

PostalKit MCP server

npm tests

An MCP server that gives Claude, Cursor, VS Code and other AI assistants accurate Mexican address data: postal codes (códigos postales), colonias, municipalities, states, streets and geocoding, from the official SEPOMEX catalog via the PostalKit API.

Español: servidor MCP para consultar códigos postales, colonias, municipios y estados de México desde Claude, Cursor y otros asistentes de IA, con datos oficiales de SEPOMEX a través de la API de PostalKit.

Ask things like:

  • "¿Qué colonias tiene el código postal 06600?"
  • "What's the postal code for Colonia Americana in Guadalajara?"
  • "Validate these 200 shipping addresses and flag any postal code that doesn't match its colonia."
  • "Which postal code is closest to 19.4233, -99.1637?"

Get an API key

Create a free account at postalkit.mx (100 requests/month on the free plan) and copy your key from the dashboard.

Install

Claude Code

claude mcp add postalkit --env POSTALKIT_KEY=your-api-key -- npx -y postalkit-mcp

Claude Desktop, Cursor, Windsurf, VS Code and other clients

Add this to your client's MCP config (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "postalkit": {
      "command": "npx",
      "args": ["-y", "postalkit-mcp"],
      "env": {
        "POSTALKIT_KEY": "your-api-key"
      }
    }
  }
}

Requires Node.js 20 or newer.

Tools

All tools are read-only.

ToolWhat it does
lookup_postal_codeState, municipality, city and every colonia for a 5-digit postal code
search_postal_codesPostal codes that start with a prefix
find_postal_codes_by_placePostal codes for a state, municipality and/or colonia name
search_coloniasColonias by name, nationwide
list_statesThe 32 states with INEGI codes
list_municipalitiesMunicipalities of a state, by ID or INEGI code
list_municipality_coloniasEvery colonia in a municipality
search_streetsStreets of a municipality, by name
geocode_postal_codeLatitude/longitude for a postal code (optionally street and number)
reverse_geocodeNearest postal code to a coordinate
get_usageYour plan, monthly limit and requests used

Each tool call is one API request against your PostalKit quota.

Configuration

VariableDefault
POSTALKIT_KEY(required)Your API key (POSTALKIT_API_KEY also works)
POSTALKIT_BASEhttps://api.postalkit.mxAPI base URL

Development

npm install
npm test          # unit tests, no network
npm run build
npm run inspector # try the tools in the MCP Inspector

Links

License

MIT

NPM
postalkit-mcp
Install Command
npm install postalkit-mcp