内容
# PostalDataPI MCP 服务器
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://pypi.org/project/postaldatapi-mcp/)
MCP（模型上下文协议）服务器，用于 [PostalDataPI](https://postaldatapi.com) —— 让 AI 代理查找、验证和搜索 **240+ 个国家和地区的邮政编码**，并提供丰富的元数据：时区、行政区域、海拔和坐标。
## 工具列表
| 工具 | 描述 |
|------|-------------|
| `lookup_postal_code` | 获取城市、州/地区和缩写形式的邮政编码（美国 ZIP、英国邮政编码、德国 PLZ 等） |
| `validate_postal_code` | 检查一个邮政编码在一个国家是否存在 |
| `search_by_city` | 查找一个城市的所有邮政编码 |
| `get_postal_code_metadata` | 获取完整的元数据：坐标、行政层级、时区、海拔等 |
## 安装配置
### 1. 获取 API 密钥
在 [postaldatapi.com/register](https://postaldatapi.com/register) 注册 —— 免费提供 1,000 次查询，无需信用卡。
### 2. 安装
```bash
pip install postaldatapi-mcp
```
### 3. 使用 Claude Code 配置
```bash
claude mcp add --transport stdio postaldatapi -- \
env POSTALDATAPI_KEY=your_api_key_here postaldatapi-mcp
```
### 4. 使用 Claude Desktop 配置
在您的 Claude Desktop 配置文件（macOS 上为 `~/Library/Application Support/Claude/claude_desktop_config.json`）中添加：
```json
{
"mcpServers": {
"postaldatapi": {
"command": "postaldatapi-mcp",
"env": {
"POSTALDATAPI_KEY": "your_api_key_here"
}
}
}
}
```
## 使用方法
配置完成后，您可以自然地向 Claude 提问：
- "ZIP 代码 90210 是哪个城市？"
- "查找英国邮政编码 SW1A"
- "10115 是有效的德国邮政编码吗？"
- "贝弗利山庄、加利福尼亚州的邮政编码是多少？"
- "获取日本邮政编码 100-0001 的坐标"
Claude 将自动使用 PostalDataPI 工具来回答。
## 支持的国家和地区
240+ 个国家和地区，包括美国、英国、加拿大、德国、法国、日本、澳大利亚、巴西、印度等。完整列表请参见 [postaldatapi.com/countries](https://postaldatapi.com/countries)。
## 丰富的元数据
除了基本的查找外，`get_postal_code_metadata` 工具还返回每个邮政编码的最多 18 个字段，包括：
- **坐标**（纬度，经度）
- **时区**（例如，`America/Mexico_City`，`Europe/Berlin`）
- **行政层级**（州/省，县，市镇）
- **海拔**（海平面以上米数）
- **地名**和国家信息
墨西哥城 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
}
```
## 相关链接
- [PostalDataPI](https://postaldatapi.com)
- [API 参考](https://postaldatapi.com/reference)
- [文档](https://docs.postaldatapi.com)
- [Python SDK](https://pypi.org/project/postaldatapi/)
- [Node.js SDK](https://www.npmjs.com/package/postaldatapi)
