# Directory Structure
```
├── .gitignore
├── .mcp.json
├── .python-version
├── LICENSE
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock
```
# Files
--------------------------------------------------------------------------------
/.python-version:
--------------------------------------------------------------------------------
```
3.10
```
--------------------------------------------------------------------------------
/.mcp.json:
--------------------------------------------------------------------------------
```json
{
"mcpServers": {
"zipcode-search": {
"command": "uv",
"args": ["run", "python", "main.py"]
}
}
}
```
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
```
# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class
# C extensions
*.so
# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
pip-wheel-metadata/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST
# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec
# Installer logs
pip-log.txt
pip-delete-this-directory.txt
# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
# Translations
*.mo
*.pot
# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal
# Flask stuff:
instance/
.webassets-cache
# Scrapy stuff:
.scrapy
# Sphinx documentation
docs/_build/
# PyBuilder
target/
# Jupyter Notebook
.ipynb_checkpoints
# IPython
profile_default/
ipython_config.py
# pyenv
#.python-version
# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock
# PEP 582; used by e.g. github.com/David-OConnor/pyflow
__pypackages__/
# Celery stuff
celerybeat-schedule
celerybeat.pid
# SageMath parsed files
*.sage.py
# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/
# Spyder project settings
.spyderproject
.spyproject
# Rope project settings
.ropeproject
# mkdocs documentation
/site
# mypy
.mypy_cache/
.dmypy.json
dmypy.json
# Pyre type checker
.pyre/
# IDE
.vscode/
.idea/
*.swp
*.swo
# macOS
.DS_Store
# Windows
Thumbs.db
ehthumbs.db
Desktop.ini
# Linux
*~
# Keep important MCP files
!.mcp.json
!.python-version
```
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
```markdown
# 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.
```
--------------------------------------------------------------------------------
/main.py:
--------------------------------------------------------------------------------
```python
from mcp.server.fastmcp import FastMCP
import httpx
mcp = FastMCP(
name="zipcode-search",
description="A Model Context Protocol server for Japanese postal code address lookup"
)
@mcp.tool()
def search_zipcode(zipcode: str) -> dict:
"""Search for address by Japanese postal code
Args:
zipcode: 7-digit postal code (e.g., "1000001")
Returns:
dict: Address information with "address" key
"""
try:
with httpx.Client() as client:
response = client.get(f"https://zipcloud.ibsnet.co.jp/api/search?zipcode={zipcode}")
response.raise_for_status()
data = response.json()
if data.get("results"):
result = data["results"][0]
address = f"{result['address1']}{result['address2']}{result['address3']}"
return {"address": address}
return {"address": "Address not found"}
except Exception as e:
return {"address": f"Error occurred: {str(e)}"}
if __name__ == "__main__":
mcp.run()
```
--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
```toml
[project]
name = "zipcode-search-mcp"
version = "0.1.0"
description = "A Model Context Protocol (MCP) server for Japanese postal code address lookup"
readme = "README.md"
requires-python = ">=3.10"
license = {text = "MIT"}
authors = [
{name = "RookingOSS", email = "[email protected]"}
]
keywords = ["mcp", "postal-code", "zipcode", "address", "japan"]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"License :: OSI Approved :: MIT License",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [
"httpx>=0.28.1",
"mcp[cli]>=1.9.3",
]
[project.urls]
Homepage = "https://github.com/rooking-oss/zipcode-search-mcp"
Repository = "https://github.com/rooking-oss/zipcode-search-mcp"
Issues = "https://github.com/rooking-oss/zipcode-search-mcp/issues"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.uv]
dev-dependencies = []
```