🌦️ Malaysian Weather MCP Server

A production-ready MCP (Model Context Protocol) server that brings real-time Malaysian weather forecasts to your favorite AI assistant.

This project implements a local MCP server that fetches live weather data from MET Malaysia's API and integrates it seamlessly with any MCP-compatible client (Claude Desktop, Cursor, Cline, etc.). Users can ask their AI assistant about Malaysian weather in natural language, and it will use this server to fetch accurate, up-to-date forecasts.

What is MCP?

Model Context Protocol (MCP) is a standard that allows AI assistants to interact with external tools and services. By integrating this MCP server with your AI assistant, you enable it to:

• Query real-time weather data

• Access current and future forecasts for any Malaysian location

• Provide weather information in natural conversation

• Use weather data to inform responses and recommendations

What This Project Does

1. Fetches Weather Data: Automatically updates Malaysian weather forecasts from MET Malaysia every 15 minutes

2. Exposes MCP Tools: Provides two tools (check_weather_today, check_7day_forecast) that your AI assistant can call

3. Manages Data: Stores forecasts in a local MySQL database with automatic cleanup

4. Runs Locally: Everything runs on your machine - no cloud dependencies

5. Works with Any MCP Client: Add a simple config to your favorite AI tool and start asking about weather!

Quick Overview

🎯 Features

• Real-time Weather Data: Automatically fetches weather forecasts every 15 minutes

• 7-Day Forecasts: Access forecasts for up to 7 days ahead

• Multi-Location Support: Query weather for states, districts, towns, recreation centres, and divisions across Malaysia

• AI-Friendly Format: Returns structured data that works with any AI assistant

• Optimized Database: Efficient MySQL storage with automatic cleanup of old records

• Telegram Alerts: Error notifications sent to your Telegram channel for immediate awareness

• Production-Ready: Comprehensive error handling and logging

🚀 Quick Start

Get up and running in 5 minutes! This will set everything up locally on your machine.

Prerequisites

Before starting, ensure you have:

• Python 3.8+ - Install from python.org

• MySQL 8.0+ - Install from mysql.com (or use Homebrew: brew install mysql)

• An MCP Client - One of: Claude Desktop, Cursor IDE, Cline VSCode extension, or any MCP-compatible client

• Git - For cloning this repository

Installation Steps

Step 1: Clone the Repository

Step 2: Install Python Dependencies

This installs:

• fastmcp - MCP server framework

• mysql-connector-python - MySQL database driver

• pydantic - Input validation

• requests - For API calls

• And other utilities

Step 3: Set Up MySQL Database

Now edit .env with your MySQL credentials:

Content of .env:

Then initialize the database:

This creates the weather_by_met database and weather_forecasts table automatically.

Step 4: Start the Scheduler (Keep Running)

In one terminal, start the scheduler to fetch weather data:

You'll see output like:

Keep this terminal running in the background. It will:

• Fetch weather data immediately

• Update every 15 minutes automatically

• Clean old records daily at 12:05 AM (Malaysia Time)

Step 5: Configure Your MCP Client

Choose your MCP client below and follow the configuration steps.

Option A: Claude Desktop

Step 5.1: Open config file

macOS/Linux:

Windows: Open %APPDATA%\Claude\claude_desktop_config.json with Notepad

Step 5.2: Add configuration (replace path with your actual path):

Step 5.3: Restart Claude Desktop

• Completely close the application

• Wait 2 seconds and reopen

Option B: Cursor IDE

Step 5.1: Open Cursor settings

• Open Cursor settings (Cmd+, or Ctrl+,)

• Search for "MCP"

Step 5.2: Add MCP server config

• Click "Add MCP Server"

• Select "Standard I/O"

• Fill in:

  • Command: python

  • Arguments: /path/to/weather-by-met/server.py

  • Environment Variables:

    { "DB_HOST": "localhost", "DB_USER": "root", "DB_PASSWORD": "your_mysql_password", "DB_NAME": "weather_by_met" }

Step 5.3: Restart Cursor

• Close Cursor completely

• Reopen the application

Option C: Cline (VSCode Extension)

Step 5.1: Open Cline settings

• Click the Cline icon in VSCode sidebar

• Open Settings → MCP Servers

Step 5.2: Add MCP server config

• Click "Add MCP Server"

• Fill in:

  • Type: stdio

  • Command: python

  • Arguments: /path/to/weather-by-met/server.py

  • Environment Variables:

    { "DB_HOST": "localhost", "DB_USER": "root", "DB_PASSWORD": "your_mysql_password", "DB_NAME": "weather_by_met" }

Step 5.3: Restart Cline

• Click the Cline icon to restart

• Or reload VSCode window (Cmd+Shift+P → "Reload Window")

Path Examples (replace with your actual path):

• macOS: /Users/john/weather-by-met/server.py

• Windows: C:\Users\john\weather-by-met\server.py

• Linux: /home/john/weather-by-met/server.py

Step 6: Test It!

Try asking your AI assistant:

You should see real weather data! 🎉

What Each File Does

Important Configuration Details

• "command": "python" - Tells your MCP client to run Python

• "args" - Full absolute path to server.py (NOT relative path like ./server.py)

• "env" - Environment variables passed to the server

  • DB_HOST: Where MySQL is running (usually localhost)

  • DB_USER: MySQL username (default is root)

  • DB_PASSWORD: MySQL password you set during MySQL installation

  • DB_NAME: Database name (leave as weather_by_met)

Verify your path is correct:

🛠️ Tools Available

Your MCP client can use these tools to fetch weather data:

1. check_weather_today

Check today's weather forecast for specific Malaysian locations.

When used: When asking for today's weather with no specific timeframe mentioned (e.g., "What's the weather today?", "Tell me the weather in Kuala Lumpur").

Parameters:

• location_query (string, optional): Location name (e.g., city, town, state). If not provided, your AI assistant may use device/browser location if available.

Returns:

• JSON formatted weather data with Malay forecasts for morning, afternoon, and night

• Includes day of the week for today

Examples:

2. check_7day_forecast

Get custom timeframe or specific day weather forecast for Malaysian locations.

Two modes available:

Mode 1: Timeframe (use days parameter)

Use when a specific timeframe is requested (e.g., "Give me a 2-day forecast", "What's the weather tomorrow?", "Show me next week's weather").

Parameters:

• location_query (string, optional): Location name (e.g., city, town, state). If not provided, your AI assistant may use device/browser location if available.

• days (int): Number of days (1-7). Your AI assistant extracts this from the user's timeframe query.

Forecast Semantics (aligned with MET Malaysia's definition):

• days=1 ("tomorrow"): Returns only tomorrow's forecast

• days=2+ ("N-day forecast"): Returns today + next (N-1) days (inclusive of today as day 1)

  • "2-day forecast" → today + tomorrow

  • "7-day forecast" → today through day 7 (matching MET's official 7-day forecast)

Examples:

Mode 2: Specific Day (use specific_day_name parameter)

Use when a specific day is requested (e.g., "What's the weather for this Sunday?", "Show me weather for next Tuesday", "How will it be on Wednesday?").

Parameters:

• location_query (string, optional): Location name (e.g., city, town, state). If not provided, your AI assistant may use device/browser location if available.

• specific_day_name (string): Day name (e.g., 'Sunday', 'Monday', 'Tuesday', etc.). Your AI assistant extracts this from the user's query.

Returns: ONLY the requested day's forecast

Examples:

Returns (both modes):

• JSON formatted weather data with Malay forecasts

• Includes day of the week for each forecast date

Response Format: Your AI assistant presents the JSON data in a compact, easy-to-read format grouped by date:

Important Notes:

• Your AI assistant displays ALL dates returned by the tool in the exact order received

  • For "2-day forecast" → Shows today + tomorrow (e.g., Friday + Saturday)

  • For "tomorrow" only → Shows only tomorrow (e.g., Saturday)

  • The assistant doesn't skip today or reinterpret the dates returned

• Data Availability: The tool ONLY provides forecasts from TODAY onwards

  • Past/historical weather data is NOT available

  • If users ask "What was the weather yesterday?" or similar, the assistant should inform them that only current and future forecasts are available

All locations are included for each date with their morning, afternoon, and night forecasts displayed on separate lines for clarity.

🔄 Automated Jobs

Job 1: Update Weather Forecast (Every 15 minutes)

Automatically fetches the latest weather forecast data from MET Malaysia API.

• Frequency: Every 15 minutes

• API: https://api.data.gov.my/weather/forecast

• Action: Inserts new records or updates existing ones

Job 2: Clean Old Records (Daily at 12:05 AM)

Removes outdated weather forecast records.

• Frequency: Daily at 12:05 AM (Malaysia Time, GMT+8)

• Action: Deletes records where forecast_date < today

🌐 Data Source

• Provider: MET Malaysia (Malaysian Meteorological Department)

• Official Portal: https://www.met.gov.my/

• API Documentation: https://developer.data.gov.my/realtime-api/weather

⚙️ Configuration

Environment Variables

Telegram Alerts Setup (Optional)

To receive error alerts via Telegram when scheduler jobs encounter issues:

1. Create a Telegram Bot:

   • Open Telegram and message @BotFather

   • Send /newbot and follow the instructions

   • Copy the API token provided

2. Get Your Chat ID:

   • Create a private Telegram group or use a direct message with your bot

   • Send a test message to the group

   • Forward the message to @userinfobot

   • Note the chat ID (negative number for groups)

3. Configure Environment Variables:

   # Add to your .env file: TELEGRAM_BOT_TOKEN=your_bot_token_here TELEGRAM_CHAT_ID=your_chat_id_here

4. How It Works:

   • Errors in the scheduler jobs (weather update, record cleanup) trigger Telegram alerts

   • Successful operations run silently (no alerts)

   • Each alert includes job name, timestamp, and error details

   • If credentials are missing, the scheduler continues to work normally

🎉 Try It Out

Once configured, try these with your AI assistant:

🌐 Language Support

The server returns weather data in Malay as provided by MET Malaysia. Your AI assistant understands Malay and will:

• Automatically translate forecasts to your preferred language

• Provide context-aware weather interpretation

• Answer follow-up questions about weather in any language

This approach provides better multilingual support compared to fixed server-side translations.

🧪 Testing

Verify everything is working by testing the components:

1. Test Database Connection:

2. Test Server (in a new terminal):

3. Test Scheduler (in another terminal):

4. Test with Your MCP Client:

• Ask your AI assistant: "What's the weather in Kuala Lumpur?"

• Should return real weather data from the database

📝 Logging & Alerts

The scheduler logs all operations to weather_scheduler.log:

Log Entries:

• ✅ Successful operations logged at INFO level

• ⚠️ Errors logged at ERROR level

• ✉️ Telegram alerts confirmed when sent successfully

🚨 Troubleshooting

Database connection failed

No weather data

Telegram alerts not working

Verify credentials are set:

Check Telegram bot token:

• Ensure token is correctly copied from @BotFather

• Make sure the bot has been started (@BotFather /start)

Verify chat ID:

• Ensure chat ID is correct (negative number for groups)

• Test by sending a message to the group manually

View Telegram send attempts in logs:

Missing Telegram credentials?:

• If TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are empty, the scheduler will still work normally

• Alerts are simply disabled; no errors will occur

📜 License

MIT License - see LICENSE file for details.

Data is provided by MET Malaysia through Malaysia's Open API initiative.

🙏 Acknowledgments

• MET Malaysia - For providing free weather API

• Anthropic - For the FastMCP framework

• Malaysian Government - For the open data initiative

📚 Documentation

• MCP_CLIENT_SETUP.md - Setup guide for Claude Desktop, Cline, and other MCP clients

• CONTRIBUTING.md - How to contribute to this project

• CODE_OF_CONDUCT.md - Community guidelines

All times are in Malaysia Time (GMT+8)