README.md•5.52 kB
# Zipcode Search MCP Server
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
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](https://docs.astral.sh/uv/) (recommended) or pip
### Quick Start
1. Clone the repository:
```bash
git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
```
2. Install dependencies using uv:
```bash
uv sync
```
Or with pip:
```bash
pip install -e .
```
3. Run the MCP server:
```bash
uv run python main.py
```
## MCP Client Configuration
### Claude Desktop
Add the following configuration to your `claude_desktop_config.json`:
```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
1. Clone and install in development mode:
```bash
git clone https://github.com/rooking-oss/zipcode-search-mcp.git
cd zipcode-search-mcp
uv sync
```
2. Run tests (if available):
```bash
uv run pytest
```
3. Format code:
```bash
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](https://zipcloud.ibsnet.co.jp/) - 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+:
```bash
python --version
```
2. Ensure dependencies are installed:
```bash
uv sync
```
3. Check if the server starts manually:
```bash
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](LICENSE) file for details.
## Acknowledgments
- [Zipcloud](https://zipcloud.ibsnet.co.jp/) for providing the postal code API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration framework
- [FastMCP](https://github.com/jlowin/fastmcp) for the server implementation
## Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/rooking-oss/zipcode-search-mcp/issues) page
2. Create a new issue with detailed information
3. For general questions, start a [Discussion](https://github.com/rooking-oss/zipcode-search-mcp/discussions)
---
**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.