Zipcode Search MCP

🚀 Zipcode Search MCP Server

A Model Context Protocol (MCP) server that enables lookup of Japanese addresses by postal code, compatible with AI assistants and other MCP clients.

🚀 Quick Start

A Model Context Protocol (MCP) server that provides Japanese postal code to address lookup functionality. This server can be integrated with AI assistants and other MCP clients to enable postal code search capabilities.

✨ Features

• 🏣 Search Japanese addresses by 7 - digit postal codes
• 🔌 Model Context Protocol (MCP) compatible
• 🚀 Fast and lightweight implementation
• 🌐 Uses reliable Zipcloud API as data source
• 🛡️ Built - in error handling and validation

🔧 Technical Details

Tech Stack

📦 Installation

Prerequisites

• Python 3.10 or higher
• uv (recommended) or pip

Quick Start

1. Clone the repository:

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

2. Install dependencies using uv:

uv sync

Or with pip:

pip install -e .

3. Run the MCP server:

uv run python main.py

📚 Documentation

MCP Client Configuration

Claude Desktop

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "zipcode-search": {
      "command": "uv",
      "args": ["run", "python", "/path/to/zipcode-search-mcp/main.py"]
    }
  }
}

Other MCP Clients

For other MCP clients, refer to the included .mcp.json configuration file or use the following connection details:

• Server Name: zipcode-search
• Command: uv run python main.py
• Working Directory: Project root directory

Available Tools

search_zipcode

Searches for a Japanese address using a postal code.

Parameters:

• zipcode (string): 7 - digit postal code (e.g., "1000001")

Returns:

• address (string): The found address, or "Address not found" if no match

Example Usage:

In your MCP client (like Claude):

What's the address for postal code 1000001?

Or directly:

Use the search_zipcode tool to find the address for postal code 1600020

API Reference

The server provides one tool through the MCP protocol:

Development

Project Structure

zipcode-search-mcp/
├── main.py              # MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock             # Dependency lock file
├── .mcp.json           # MCP client configuration
├── .python-version     # Python version specification
├── .gitignore          # Git ignore rules
└── README.md           # This file

Development Setup

1. Clone and install in development mode:

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

2. Run tests (if available):

uv run pytest

3. Format code:

uv run black .
uv run isort .

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests if applicable
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Dependencies

External Services

• Zipcloud API - Provides postal code to address mapping data

Python Packages

• mcp[cli] - Model Context Protocol implementation
• httpx - Async HTTP client for API requests

Troubleshooting

Server Won't Start

1. Verify Python version is 3.10+:

python --version

2. Ensure dependencies are installed:

uv sync

3. Check if the server starts manually:

uv run python main.py

Postal Code Not Found

• Ensure the postal code is exactly 7 digits (no hyphens)
• Verify the Zipcloud API is accessible
• Check your internet connection

MCP Client Connection Issues

• Verify the path in your MCP client configuration is correct
• Ensure the server is executable from the specified directory
• Check MCP client logs for detailed error messages

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Zipcloud for providing the postal code API
• Model Context Protocol for the integration framework
• FastMCP for the server implementation

Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. For general questions, start a Discussion

⚠️ Important Note

This service uses the Zipcloud API and is intended for development and educational purposes. For production use, please ensure proper error handling, rate limiting, and compliance with the Zipcloud API terms of service.