Content
# Japanese Weather MCP
This is a sample program for a Model Context Protocol (MCP) server that provides weather information for Japan.
## 🌟 Features
- 🌤️ **Nationwide Coverage**: Provides weather information for 110 cities across the country
- 🗣️ **Natural Language Support**: Supports input in Kanji, Hiragana, and Katakana for place names
- 🤖 **MCP Compliant**: Usable with MCP clients such as Claude Desktop
- 🌐 **HTTP Support**: Accessible via the web using HTTP transport
- 🐳 **Docker Support**: Easy deployment
## 🛠️ Tech Stack
- [FastMCP](https://gofastmcp.com/) - MCP server framework
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) - Python dependency management (recommended)
- [OpenMeteo API](https://open-meteo.com/) - Weather data source
- pandas (for place name data processing)
- httpx (for HTTP communication)
## ⚡ Quick Start
```bash
# Clone the repository
git clone https://github.com/tsukiyama85/japanese-weather-mcp.git
cd japanese-weather-mcp
# Start the MCP server
docker compose build
docker compose up -d
# Start the MCP client
uv sync
uv run -m examples.gemini_mcp_client
```
## 📦 Installation
### 1. Clone the Repository
```bash
git clone https://github.com/tsukiyama85/japanese-weather-mcp.git
cd japanese-weather-mcp
```
### 2. Install Dependencies
#### Using uv (recommended)
```bash
# Install dependencies
uv sync
# Include development dependencies
uv sync --dev
```
#### Using pip
```bash
pip install -e .
```
### 3. Verify Functionality
#### Using uv
```bash
uv run -m src.japanese_weather_mcp.main
```
#### Using pip
```bash
python -m src.japanese_weather_mcp.main
```
### Using Docker Compose
```bash
docker-compose up --build
```
## 🚀 Usage
### Using with Claude Desktop
Add to the Claude Desktop configuration file (`claude_desktop_config.json`):
#### Using uv
```json
{
"mcpServers": {
"japanese-weather": {
"command": "uv",
"args": ["run", "python", "-m", "src.japanese_weather_mcp.main"],
"cwd": "/path/to/japanese-weather-mcp"
}
}
}
```
#### Using pip
```json
{
"mcpServers": {
"japanese-weather": {
"command": "python",
"args": ["-m", "src.japanese_weather_mcp.main"],
"cwd": "/path/to/japanese-weather-mcp"
}
}
}
```
### Run as an HTTP Server
#### Using uv
```bash
uv run -m src.japanese_weather_mcp.main
```
#### Using pip
```bash
python -m src.japanese_weather_mcp.main
```
## 🔧 Available Tools
| Tool Name | Description | Parameters |
|--------------------|---------------------------|--------------------------------|
| `get_weather` | Get weather forecast | `location`: Place name, `days`: Number of days (1-7) |
| `get_current_weather` | Get current weather | `location`: Place name |
| `search_locations` | Search for locations | `query`: Search query |
## 💬 Usage Examples
### Example Questions for Claude Desktop
```
"What is the weather in Tokyo tomorrow?"
"Please tell me the forecast for Osaka for the next three days."
"What is the current temperature in Sapporo?"
```
### 🤖 Verification with Gemini AI Client
You can verify functionality with natural language using `examples/gemini_mcp_client.py`:
#### Preparation
1. Obtain an API key from **Google AI Studio**
- https://makersuite.google.com/app/apikey
2. **Set Environment Variables**
```bash
cd examples
cp .env.example .env
# Set GEMINI_API_KEY in the .env file
```
3. **Install Dependencies**
```bash
# For uv
uv sync
# For pip
pip install -r examples/requirements.txt
```
#### Execution Steps
1. **Start the MCP Server** (in a separate terminal)
```bash
# For uv
uv run -m src.japanese_weather_mcp.main
uv run -m examples.gemini_mcp_client
```
```bash
# For pip
python -m src.japanese_weather_mcp.main
python -m examples.gemini_mcp_client
```
#### Usage Image
```
💬 Question: What is the weather like in Tokyo today?
🤖 Answer: The weather in Tokyo today is sunny, with a temperature of 22°C. The humidity is 65%, and the chance of rain is 10%.
```
This client understands questions in natural language and automatically selects and executes the appropriate MCP tool.
## 🌍 Supported Regions
Coverage for 110 cities nationwide:
- Hokkaido: Sapporo, Hakodate, Asahikawa
- Tohoku: Sendai, Aomori, Morioka, etc.
- Kanto: Tokyo, Yokohama, Saitama, etc.
- Chubu: Nagoya, Shizuoka, Kanazawa, etc.
- Kansai: Osaka, Kyoto, Kobe, etc.
- Chugoku & Shikoku: Hiroshima, Okayama, Takamatsu, etc.
- Kyushu & Okinawa: Fukuoka, Kumamoto, Naha, etc.
## ⚙️ Environment Variables
| Variable Name | Default Value | Description |
|--------------------|------------------|------------------------------|
| `MCP_TRANSPORT` | `streamable-http` | Transport method |
| `MCP_HOST` | `127.0.0.1` | Host for the HTTP server |
| `MCP_PORT` | `8000` | Port for the HTTP server |
| `MCP_PATH` | `/mcp/` | HTTP endpoint path |
| `LOG_LEVEL` | `INFO` | Log level |
## 🤝 Development & Contribution
### About the examples Folder
The `examples/` folder contains clients for development and testing:
- `gemini_mcp_client.py` - Intelligent client using Gemini AI
- `.env.example` - Template for environment variables
These are provided as reference implementations and are independent of the main MCP server.
## 📝 License
MIT License
## 🙏 Acknowledgments
- [OpenMeteo](https://open-meteo.com/) - Free weather data API
- [FastMCP](https://gofastmcp.com/) - MCP server framework
