Zipcode Search MCP

🚀 邮编搜索MCP服务器

这是一个模型上下文协议（MCP）服务器，提供日本邮政编码到地址的查询功能。该服务器可与AI助手及其他MCP客户端集成，以实现邮政编码搜索功能。

🚀 快速开始

安装前提

• Python 3.10 或更高版本
• uv（推荐）或 pip

快速启动步骤

1. 克隆仓库：

git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp

2. 使用 uv 安装依赖：

uv sync

或者使用 pip：

pip install -e .

3. 运行 MCP 服务器：

uv run python main.py

✨ 主要特性

• 🏣 通过 7 位邮政编码搜索日本地址
• 🔌 与模型上下文协议（MCP）兼容
• 🚀 快速轻量级实现
• 🌐 使用可靠的 Zipcloud API 作为数据源
• 🛡️ 内置错误处理和验证

📦 安装指南

安装前提

• Python 3.10 或更高版本
• uv（推荐）或 pip

快速启动步骤

1. 克隆仓库：

git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp

2. 使用 uv 安装依赖：

uv sync

或者使用 pip：

pip install -e .

3. 运行 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 协议提供一个工具：

开发

项目结构

zipcode-search-mcp/
├── main.py              # MCP 服务器实现
├── pyproject.toml       # 项目配置和依赖
├── uv.lock             # 依赖锁定文件
├── .mcp.json           # MCP 客户端配置
├── .python-version     # Python 版本规范
├── .gitignore          # Git 忽略规则
└── README.md           # 本文件

开发设置

1. 克隆并以开发模式安装：

git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
uv sync

2. 运行测试（如果可用）：

uv run pytest

3. 格式化代码：

uv run black .
uv run isort .

贡献代码

我们欢迎贡献！请遵循以下步骤：

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 如有必要添加测试
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开拉取请求

依赖项

外部服务

• Zipcloud API - 提供邮政编码到地址的映射数据

Python 包

• mcp[cli] - 模型上下文协议实现
• httpx - 用于 API 请求的异步 HTTP 客户端

故障排除

服务器无法启动

1. 验证 Python 版本是否为 3.10+：

python --version

2. 确保已安装依赖项：

uv sync

3. 检查服务器是否可以手动启动：

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
• 模型上下文协议 提供集成框架
• FastMCP 提供服务器实现

支持

如果您遇到任何问题或有疑问：

1. 查看 问题 页面
2. 创建一个包含详细信息的新问题
3. 对于一般问题，请启动 讨论

⚠️ 重要提示

本服务使用 Zipcloud API，仅用于开发和教育目的。对于生产使用，请确保进行适当的错误处理、速率限制，并遵守 Zipcloud API 服务条款。