Japanese Weather MCP

🚀 Japanese Weather MCP Server

This is a Model Context Protocol (MCP) server that offers access to Japanese weather forecasts by leveraging the weather.tsukumijima.net API. It simplifies the process of retrieving accurate and detailed weather information for various Japanese cities.

🚀 Quick Start

The Japanese Weather MCP Server allows you to easily access Japanese weather forecasts. You can install it either automatically via Smithery or manually. After installation, you can run the server in development or production mode.

✨ Features

• 🌤️ Retrieve weather forecasts for Japanese cities.
• 📍 Provide support for major Japanese cities, such as Tokyo, Osaka, and Kyoto.
• 📊 Offer detailed weather information, including temperature, precipitation chance, and wind conditions.
• 🏢 Source data from the Japan Meteorological Agency.
• 🔧 Equip with easy - to - use MCP tools for weather queries.

📦 Installation

Installing via Smithery

To automatically install japanese - weather - mcp for Claude Desktop via Smithery, use the following command:

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

Manual Installation

1. Clone the 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 Examples

Basic Usage

Development Mode

Run the server in development mode:

npm run dev

Production Mode

Build and run the server:

npm run build
npm start

Advanced Usage

The server provides several useful tools for weather queries.

1. get_weather_forecast

Get the weather forecast for any Japanese city using its city ID. Parameters:

• cityId (string): The 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: A list of available city IDs along with their corresponding names.

3. get_weather_by_city_name

Get the weather forecast for common Japanese cities by name. Parameters:

• cityName (enum): The name of the Japanese city. Options include TOKYO, OSAKA, KYOTO, FUKUOKA, SAPPORO, NAGOYA, YOKOHAMA, KOBE, KAWASAKI, HIROSHIMA. Example:

{
  "cityName": "TOKYO"
}

📚 Documentation

Common City IDs

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

Weather Data Structure

The weather forecast consists of the following information:

• 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 utilizes the weather.tsukumijima.net API, which features:

• A Livedoor Weather API compatible format.
• Data from the Japan Meteorological Agency.
• No requirement for an API key.
• Free to use.

Rate Limiting

Please follow these guidelines when using the API:

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

Error Handling

The server has comprehensive error handling for the following scenarios:

• 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

This project is under the MIT License. For detailed information, please refer to the LICENSE file.

🤝 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.
• The 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.