Zipcode Search MCP

🚀 Zipcode Search MCP Server

このサーバーは、日本の郵便番号から住所を検索する機能を提供するModel Context Protocol (MCP) サーバーです。AIアシスタントやその他のMCPクライアントと統合することで、郵便番号検索機能を有効にすることができます。

🚀 クイックスタート

このZipcode Search MCP Serverは、日本の郵便番号から住所を検索する機能を提供する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プロトコルを通じて1つのツールを提供します:

開発

プロジェクト構造

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. Issues ページを確認します
2. 詳細な情報を含めて新しいissueを作成します
3. 一般的な質問については、Discussion を開始します

⚠️ 重要提示

このサービスはZipcloud APIを使用しており、開発および教育目的で意図されています。本番環境での使用には、適切なエラーハンドリング、レート制限、およびZipcloud APIのサービス利用規約への準拠を確認してください。