🚀 邮编搜索MCP服务器

邮编搜索MCP服务器是一个基于Model Context Protocol (MCP) 的服务器，它提供了将日本邮政编码转换为对应地址的查询功能。该服务器可与AI助手及其他MCP客户端集成，从而实现邮政编码搜索能力。

🚀 快速开始

本服务器是一个支持Model Context Protocol (MCP) 的服务器，提供日本邮政编码到地址的查询功能。可与AI助手等MCP客户端集成，实现邮政编码搜索。

✨ 主要特性

• 🏣 支持通过7位邮政编码搜索日本地址。
• 🔌 与Model Context Protocol (MCP) 兼容。
• 🚀 实现快速且轻量级。
• 🌐 使用可靠的Zipcloud API作为数据源。
• 🛡️ 内置错误处理和验证机制。

🔧 技术细节

技术栈

• Python 3.10+
• MCP (Model Context Protocol) - AI工具集成协议
• FastMCP - MCP服务器框架
• httpx - 现代HTTP客户端
• 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 Desktop

在你的 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] - Model Context Protocol实现
• httpx - 用于API请求的异步HTTP客户端

故障排除

服务器无法启动

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

python --version

2. 确保依赖项已安装：

uv sync

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

uv run python main.py

邮政编码未找到

• 确保邮政编码正好是7位（无连字符）。
• 验证Zipcloud API是否可访问。
• 检查你的互联网连接。

MCP客户端连接问题

• 验证MCP客户端配置中的路径是否正确。
• 确保服务器可以从指定目录执行。
• 检查MCP客户端日志以获取详细错误消息。

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Zipcloud 提供邮政编码API。
• Model Context Protocol 提供集成框架。
• FastMCP 提供服务器实现。

支持

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

1. 查看 问题 页面。
2. 创建一个包含详细信息的新问题。
3. 对于一般性问题，请在 讨论 中发起讨论。

⚠️ 重要提示

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