Zipcode Search MCP Server

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

Tech Stack

Python 3.10+
MCP (Model Context Protocol) - AI tool integration protocol
FastMCP - MCP server framework
httpx - Modern HTTP client
Zipcloud API - Japanese postal code data source

Installation

Prerequisites

Python 3.10 or higher
uv (recommended) or pip

Quick Start

Clone the repository:

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

Install dependencies using uv:

uv sync

Or with pip:

pip install -e .

Run the MCP server:

uv run python main.py

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:

Tool	Description	Input	Output
`search_zipcode`	Search address by postal code	`zipcode: string`	`{address: string}`

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

Clone and install in development mode:

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

Run tests (if available):

uv run pytest

Format code:

uv run black .
uv run isort .

Contributing

We welcome contributions! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests if applicable
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Verify Python version is 3.10+:

python --version

Ensure dependencies are installed:

uv sync

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:

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

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.

Zipcode Search MCP Server