Scan to join WeChat grouparticle
README
🚀 邮编搜索MCP服务器
这是一个模型上下文协议（MCP）服务器，提供日本邮政编码到地址的查询功能。该服务器可与AI助手及其他MCP客户端集成，以实现邮政编码搜索功能。
🚀 快速开始
安装前提
- Python 3.10 或更高版本
- uv（推荐）或 pip
快速启动步骤
- 克隆仓库：
git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
- 使用 uv 安装依赖：
uv sync
或者使用 pip：
pip install -e .
- 运行 MCP 服务器：
uv run python main.py
✨ 主要特性
- 🏣 通过 7 位邮政编码搜索日本地址
- 🔌 与模型上下文协议（MCP）兼容
- 🚀 快速轻量级实现
- 🌐 使用可靠的 Zipcloud API 作为数据源
- 🛡️ 内置错误处理和验证
📦 安装指南
安装前提
- Python 3.10 或更高版本
- uv（推荐）或 pip
快速启动步骤
- 克隆仓库：
git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
- 使用 uv 安装依赖：
uv sync
或者使用 pip：
pip install -e .
- 运行 MCP 服务器：
uv run python main.py
📚 详细文档
MCP 客户端配置
Claude 桌面版
在你的 claude_desktop_config.json 中添加以下配置：
{
"mcpServers": {
"zipcode-search": {
"command": "uv",
"args": ["run", "python", "/path/to/zipcode-search-mcp/main.py"]
}
}
}
其他 MCP 客户端
对于其他 MCP 客户端，请参考包含的 .mcp.json 配置文件，或使用以下连接详细信息：
- 服务器名称：
zipcode-search - 命令：
uv run python main.py - 工作目录：项目根目录
可用工具
search_zipcode
使用邮政编码搜索日本地址。
参数：
zipcode（字符串）：7 位邮政编码（例如，"1000001"）
返回值：
address（字符串）：找到的地址，如果没有匹配项则返回 "Address not found"
使用示例： 在你的 MCP 客户端（如 Claude）中：
What's the address for postal code 1000001?
或者直接使用：
Use the search_zipcode tool to find the address for postal code 1600020
API 参考
服务器通过 MCP 协议提供一个工具：
| 工具 | 描述 | 输入 | 输出 |
|------|-------------|-------|--------|
| search_zipcode | 通过邮政编码搜索地址 | zipcode: string | {address: string} |
开发
项目结构
zipcode-search-mcp/
├── main.py # MCP 服务器实现
├── pyproject.toml # 项目配置和依赖
├── uv.lock # 依赖锁定文件
├── .mcp.json # MCP 客户端配置
├── .python-version # Python 版本规范
├── .gitignore # Git 忽略规则
└── README.md # 本文件
开发设置
- 克隆并以开发模式安装：
git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
uv sync
- 运行测试（如果可用）：
uv run pytest
- 格式化代码：
uv run black .
uv run isort .
贡献代码
我们欢迎贡献！请遵循以下步骤：
- 分叉仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 进行更改
- 如有必要添加测试
- 提交更改 (
git commit -m 'Add amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开拉取请求
依赖项
外部服务
- Zipcloud API - 提供邮政编码到地址的映射数据
Python 包
mcp[cli]- 模型上下文协议实现httpx- 用于 API 请求的异步 HTTP 客户端
故障排除
服务器无法启动
- 验证 Python 版本是否为 3.10+：
python --version
- 确保已安装依赖项：
uv sync
- 检查服务器是否可以手动启动：
uv run python main.py
邮政编码未找到
- 确保邮政编码正好是 7 位（无连字符）
- 验证 Zipcloud API 是否可访问
- 检查你的互联网连接
MCP 客户端连接问题
- 验证 MCP 客户端配置中的路径是否正确
- 确保服务器可以从指定目录执行
- 检查 MCP 客户端日志以获取详细错误消息
🔧 技术细节
技术栈
- Python 3.10+
- MCP（模型上下文协议） - AI 工具集成协议
- FastMCP - MCP 服务器框架
- httpx - 现代 HTTP 客户端
- Zipcloud API - 日本邮政编码数据源
📄 许可证
本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。
致谢
支持
如果您遇到任何问题或有疑问：
⚠️ 重要提示
本服务使用 Zipcloud API，仅用于开发和教育目的。对于生产使用，请确保进行适当的错误处理、速率限制，并遵守 Zipcloud API 服务条款。