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

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