Zipcode Search MCP

🚀 郵編搜索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服務條款。