WeatherNow MCP Tool

A Model Context Protocol (MCP) tool for accessing real-time weather information using the Weatherstack API. This tool can be installed as an npm package and integrated into MCP-compatible applications.

Features

• 🌤️ Get current weather information for any location worldwide
• 🌍 Support for cities, countries, and coordinates
• 📊 Detailed weather data including temperature, humidity, wind, and more
• 🎨 Formatted output with emojis for better readability
• ⚡ Fast and reliable API responses
• 🔒 Secure API key management with environment variables
• 📦 Easy installation as an npm package

Installation

Prerequisites

• Node.js 18.0.0 or higher
• A Weatherstack API key (free at weatherstack.com)

Install the Package

npm install weathernow-mcp

Get Your API Key

1. Visit Weatherstack
2. Sign up for a free account
3. Get your API key from the dashboard
4. Set it as an environment variable:

export WEATHERSTACK_API_KEY="your_api_key_here"

Usage

As an MCP Server

The package can be used as an MCP server that provides weather information to MCP clients.

# Start the MCP server
npx weathernow-mcp

Programmatic Usage

import { WeatherService } from 'weathernow-mcp';

const weatherService = new WeatherService(process.env.WEATHERSTACK_API_KEY!);

// Get weather for a location
const weather = await weatherService.getCurrentWeather('New York');

if ('error' in weather) {
  console.error('Error:', weather.error.info);
} else {
  console.log(weatherService.formatWeatherData(weather));
}

MCP Tool Integration

The tool provides a weathernow tool with the following parameters:

• location (required): The location to get weather for (e.g., "New York", "London", "Tokyo")
• format (optional): Output format - "detailed" (default) or "simple"

Example MCP tool call:

{
  "name": "weathernow",
  "arguments": {
    "location": "Paris, France",
    "format": "detailed"
  }
}

API Reference

WeatherService

Constructor

new WeatherService(apiKey: string)

Methods

getCurrentWeather(location: string): Promise<WeatherData | WeatherError>

Fetches current weather data for the specified location.

Parameters:

• location: The location to get weather for (city name, country, coordinates, etc.)

Returns:

• WeatherData: Weather information object
• WeatherError: Error object if the request fails

formatWeatherData(data: WeatherData): string

Formats weather data into a human-readable string with emojis.

Parameters:

• data: WeatherData object to format

Returns:

• string: Formatted weather information

WeatherData Interface

interface WeatherData {
  location: {
    name: string;
    country: string;
    region: string;
    lat: string;
    lon: string;
    timezone_id: string;
    localtime: string;
    localtime_epoch: number;
    utc_offset: string;
  };
  current: {
    observation_time: string;
    temperature: number;
    weather_code: number;
    weather_icons: string[];
    weather_descriptions: string[];
    wind_speed: number;
    wind_degree: number;
    wind_dir: string;
    pressure: number;
    precip: number;
    humidity: number;
    cloudcover: number;
    feelslike: number;
    uv_index: number;
    visibility: number;
    is_day: string;
  };
}

Development

Setup

1. Clone the repository

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your API key

4. Build the project:

   npm run build

Testing

Run the test suite:

npm test

Building

Build the TypeScript source:

npm run build

Configuration

Environment Variables

• WEATHERSTACK_API_KEY: Your Weatherstack API key (required)

MCP Server Configuration

The MCP server can be configured by setting environment variables:

export WEATHERSTACK_API_KEY="your_api_key_here"

Error Handling

The tool provides comprehensive error handling for:

• Invalid API keys
• Network connectivity issues
• Invalid location names
• API rate limiting
• Service unavailability

All errors are returned in a consistent format with error codes and descriptive messages.

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

Support

For issues and questions:

1. Check the GitHub Issues
2. Create a new issue with detailed information
3. Include your Node.js version and error messages

Changelog

1.0.0

• Initial release
• Weatherstack API integration
• MCP server implementation
• TypeScript support
• Comprehensive error handling