Content
# PostalDataPI MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/postaldatapi-mcp/)
MCP (Model Context Protocol) server for [PostalDataPI](https://postaldatapi.com) — lets AI agents look up, validate, and search postal codes across **240+ countries and territories** with rich metadata: timezone, administrative regions, elevation, and coordinates.
## Tools
| Tool | Description |
|------|-------------|
| `lookup_postal_code` | Get city, state/region, and abbreviation for a postal code (US ZIP, UK postcode, German PLZ, etc.) |
| `validate_postal_code` | Check if a postal code exists in a country |
| `search_by_city` | Find all postal codes for a city |
| `get_postal_code_metadata` | Full metadata: coordinates, admin hierarchy, timezone, elevation, and more |
## Setup
### 1. Get an API Key
Sign up at [postaldatapi.com/register](https://postaldatapi.com/register) — 1,000 free queries, no credit card required.
### 2. Install
```bash
pip install postaldatapi-mcp
```
### 3. Configure with Claude Code
```bash
claude mcp add --transport stdio postaldatapi -- \
env POSTALDATAPI_KEY=your_api_key_here postaldatapi-mcp
```
### 4. Configure with Claude Desktop
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):
```json
{
"mcpServers": {
"postaldatapi": {
"command": "postaldatapi-mcp",
"env": {
"POSTALDATAPI_KEY": "your_api_key_here"
}
}
}
}
```
## Usage
Once configured, ask Claude naturally:
- "What city is ZIP code 90210?"
- "Look up UK postcode SW1A"
- "Is 10115 a valid German postal code?"
- "What are the postal codes for Beverly Hills, CA?"
- "Get the coordinates for postal code 100-0001 in Japan"
Claude will automatically use the PostalDataPI tools to answer.
## Supported Countries
240+ countries and territories including US, UK, Canada, Germany, France, Japan, Australia, Brazil, India, and many more. See the full list at [postaldatapi.com/countries](https://postaldatapi.com/countries).
## Rich Metadata
Beyond basic lookups, the `get_postal_code_metadata` tool returns up to 18 fields per postal code including:
- **Coordinates** (latitude, longitude)
- **Timezone** (e.g., `America/Mexico_City`, `Europe/Berlin`)
- **Administrative hierarchy** (state/province, county, municipality)
- **Elevation** (meters above sea level)
- **Place name** and country information
Example response for Mexico City 06000:
```json
{
"postalCode": "06000",
"country": "MX",
"placeName": "Centro",
"latitude": 19.4364,
"longitude": -99.1553,
"timezone": "America/Mexico_City",
"adminLevel1": "Ciudad de México",
"adminLevel2": "Cuauhtémoc",
"elevation": 2239
}
```
## Links
- [PostalDataPI](https://postaldatapi.com)
- [API Reference](https://postaldatapi.com/reference)
- [Documentation](https://docs.postaldatapi.com)
- [Python SDK](https://pypi.org/project/postaldatapi/)
- [Node.js SDK](https://www.npmjs.com/package/postaldatapi)
