Japanese Weather MCP Server

A Model Context Protocol (MCP) server that provides access to Japanese weather forecasts using the weather.tsukumijima.net API.

Features

• 🌤️ Get weather forecasts for Japanese cities
• 📍 Support for major Japanese cities (Tokyo, Osaka, Kyoto, etc.)
• 📊 Detailed weather information including temperature, precipitation chance, and wind conditions
• 🏢 Data sourced from Japan Meteorological Agency
• 🔧 Easy-to-use MCP tools for weather queries

Installation

Installing via Smithery

To install japanese-weather-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @kongyo2/japanese-weather-mcp --client claude

Manual Installation

1. Clone this repository:

git clone https://github.com/kongyo2/Japanese-Weather-MCP
cd weather-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

Usage

Development Mode

Run the server in development mode:

npm run dev

Production Mode

Build and run the server:

npm run build
npm start

Available Tools

1. get_weather_forecast

Get weather forecast for any Japanese city using its city ID.

Parameters:

• cityId (string): City ID for the Japanese city (e.g., '130010' for Tokyo)

Example:

{
  "cityId": "130010"
}

2. get_available_city_ids

Get a list of available city IDs for common Japanese cities.

Parameters: None

Returns: List of available city IDs with their corresponding names.

3. get_weather_by_city_name

Get weather forecast for common Japanese cities by name.

Parameters:

• cityName (enum): Name of the Japanese city
  • Options: TOKYO, OSAKA, KYOTO, FUKUOKA, SAPPORO, NAGOYA, YOKOHAMA, KOBE, KAWASAKI, HIROSHIMA

Example:

{
  "cityName": "TOKYO"
}

Common City IDs

City	ID	Prefecture
Tokyo	130010	Tokyo
Osaka	270000	Osaka
Kyoto	260010	Kyoto
Fukuoka	400010	Fukuoka
Sapporo	016010	Hokkaido
Nagoya	230010	Aichi
Yokohama	140010	Kanagawa
Kobe	280010	Hyogo
Kawasaki	140020	Kanagawa
Hiroshima	340010	Hiroshima

For more city IDs, visit: https://weather.tsukumijima.net/primary_area.xml

Weather Data Structure

The weather forecast includes:

• Basic Information:

  • Publication time and office
  • Location details (prefecture, city, district)

• Forecast Data (3 days):

  • Weather condition (telop)
  • Temperature (max/min in Celsius and Fahrenheit)
  • Precipitation chance (6-hour intervals)
  • Detailed weather information
  • Wind conditions
  • Wave height (for coastal areas)

• Additional Information:

  • Weather icons (SVG format)
  • Links to official JMA weather pages

API Source

This MCP server uses the weather.tsukumijima.net API, which provides:

• Livedoor Weather API compatible format
• Data from Japan Meteorological Agency
• No API key required
• Free to use

Rate Limiting

Please be respectful of the API:

• Use a custom User-Agent header
• Avoid rapid successive requests
• Maintain at least 0.5-second intervals between requests

Error Handling

The server includes comprehensive error handling:

• Network connectivity issues
• Invalid city IDs
• API service unavailability
• Data parsing errors

Development

Project Structure

weather-mcp-server/
├── src/
│   ├── server.ts          # Main MCP server implementation
│   └── weather-api.ts     # Weather API client
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Testing

npm test

Linting

npm run lint

Formatting

npm run format

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Acknowledgments

• weather.tsukumijima.net for providing the weather API
• Japan Meteorological Agency for the weather data
• FastMCP for the MCP framework

Support

If you encounter any issues or have questions, please:

1. Check the weather.tsukumijima.net documentation
2. Review the available city IDs
3. Ensure proper rate limiting
4. Open an issue in this repository