weatherapi-mcp 1.0.0

package/README.md

@@ -0,0 +1,115 @@
+# weatherapi-mcp
+
+Official MCP (Model Context Protocol) server for [WeatherAPI.com](https://www.weatherapi.com). Gives AI agents like Claude direct access to real-time weather, forecasts, historical data, astronomy, marine weather, air quality, and more.
+
+## Quick Start
+
+```bash
+# Run directly with npx (no install needed)
+WEATHERAPI_KEY=your_api_key npx weatherapi-mcp
+```
+
+Get a free API key at [weatherapi.com/signup.aspx](https://www.weatherapi.com/signup.aspx)
+
+## Setup in Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "weatherapi": {
+      "command": "npx",
+      "args": ["-y", "weatherapi-mcp"],
+      "env": {
+        "WEATHERAPI_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Config file locations:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+Restart Claude Desktop after editing.
+
+## Setup in Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "weatherapi": {
+      "command": "npx",
+      "args": ["-y", "weatherapi-mcp"],
+      "env": {
+        "WEATHERAPI_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_current_weather` | Real-time conditions — temp, wind, humidity, UV, pressure, AQI |
+| `get_forecast` | Up to 14-day forecast with hourly breakdown and alerts |
+| `get_history` | Historical weather from 1 Jan 2010 onwards |
+| `get_future_weather` | Long-range forecast 14–300 days ahead (Pro+ plan) |
+| `get_marine_weather` | Wave height, swell, tide data for coastal/ocean points |
+| `get_astronomy` | Sunrise, sunset, moonrise, moon phase, illumination |
+| `get_timezone` | IANA timezone and local time for any location |
+| `search_locations` | Autocomplete city/town search with coordinates |
+| `ip_lookup` | Geolocate an IP address or auto-detect caller's location |
+| `get_alerts` | Government weather warnings (USA, UK, Europe, worldwide) |
+| `get_sports` | Upcoming football, cricket, and golf events |
+
+## Location Formats
+
+The `q` parameter accepts:
+- City name: `London`, `New York`, `Tokyo`
+- Coordinates: `51.5,-0.1`
+- US zip: `10001`
+- UK postcode: `SW1A 1AA`
+- IATA airport: `iata:LHR`
+- IP address: `100.0.0.1`
+- Auto-detect: `auto:ip`
+
+## Example Prompts
+
+Once connected, ask Claude:
+- *"What's the weather like in Glasgow right now?"*
+- *"Will it rain in London this weekend? Show me hourly."*
+- *"What was the weather in Paris on 15 June 2024?"*
+- *"What time does the sun rise in Tokyo tomorrow?"*
+- *"Are there any weather warnings active for New York?"*
+- *"What's the wave height off the coast of Cornwall today?"*
+- *"What timezone is Sydney in and what time is it there now?"*
+
+## Plans
+
+| Plan | Price | Calls/month |
+|------|-------|-------------|
+| Free | $0 | 100,000 |
+| Starter | $7/mo | 3,000,000 |
+| Pro+ | $25/mo | 5,000,000 |
+| Business | $65/mo | 10,000,000 |
+| Enterprise | Custom | Custom |
+
+## Links
+
+- [Documentation](https://www.weatherapi.com/docs/)
+- [API Explorer](https://www.weatherapi.com/api-explorer.aspx)
+- [Sign Up Free](https://www.weatherapi.com/signup.aspx)
+- [OpenAPI Spec](https://www.weatherapi.com/openapi.json)
+- [Pricing](https://www.weatherapi.com/pricing.aspx)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,332 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const API_KEY = process.env.WEATHERAPI_KEY;
+const BASE_URL = "https://api.weatherapi.com/v1";
+if (!API_KEY) {
+    console.error("Error: WEATHERAPI_KEY environment variable is required.");
+    console.error("Get a free key at https://www.weatherapi.com/signup.aspx");
+    process.exit(1);
+}
+// Helper: make a GET request to WeatherAPI
+async function weatherRequest(endpoint, params) {
+    const searchParams = new URLSearchParams({ key: API_KEY });
+    for (const [k, v] of Object.entries(params)) {
+        searchParams.set(k, String(v));
+    }
+    const url = `${BASE_URL}${endpoint}?${searchParams.toString()}`;
+    const res = await fetch(url);
+    const data = await res.json();
+    if (!res.ok) {
+        const err = data;
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `WeatherAPI error ${err.error?.code}: ${err.error?.message ?? res.statusText}`);
+    }
+    return data;
+}
+const server = new index_js_1.Server({
+    name: "weatherapi-mcp",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// LIST TOOLS
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "get_current_weather",
+            description: "Get real-time current weather for any location. Returns temperature, wind speed and direction, humidity, pressure, UV index, visibility, feels-like temperature, and weather condition. Optionally includes air quality (AQI) data.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query. Accepts: city name (London), lat/lon (51.5,-0.1), US zip (10001), UK postcode (SW1), IATA airport code (iata:LHR), IP address, or auto:ip for caller's location.",
+                    },
+                    aqi: {
+                        type: "string",
+                        enum: ["yes", "no"],
+                        description: "Include air quality data (CO, NO2, O3, SO2, PM2.5, PM10). Default: no.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "get_forecast",
+            description: "Get weather forecast for 1 to 14 days. Returns daily summaries (max/min/avg temp, rain chance, UV, wind) and hourly breakdowns. Also returns current conditions, astronomy data (sunrise/sunset/moon phase), and optionally weather alerts and air quality.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                    days: {
+                        type: "number",
+                        description: "Number of forecast days (1–14). Default: 3.",
+                    },
+                    alerts: {
+                        type: "string",
+                        enum: ["yes", "no"],
+                        description: "Include government weather alerts. Default: no.",
+                    },
+                    aqi: {
+                        type: "string",
+                        enum: ["yes", "no"],
+                        description: "Include air quality data. Default: no.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "get_history",
+            description: "Get historical weather data for a specific date from 1 January 2010 onwards. Returns daily summary and full hourly breakdown. Useful for past weather lookups, analytics, and backtesting.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                    dt: {
+                        type: "string",
+                        description: "Date in yyyy-MM-dd format. Must be on or after 2010-01-01.",
+                    },
+                    end_dt: {
+                        type: "string",
+                        description: "Optional end date for a date range (Pro+ plan only). Max 30 days range. yyyy-MM-dd.",
+                    },
+                },
+                required: ["q", "dt"],
+            },
+        },
+        {
+            name: "get_future_weather",
+            description: "Get future weather forecast for a date between 14 and 300 days from today. Returns 3-hourly data. Available on Pro+ plan and above.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                    dt: {
+                        type: "string",
+                        description: "Future date in yyyy-MM-dd format. Must be between 14 and 300 days from today.",
+                    },
+                },
+                required: ["q", "dt"],
+            },
+        },
+        {
+            name: "get_marine_weather",
+            description: "Get marine and sailing weather forecast including significant wave height, swell height, swell direction, swell period, and optionally tide data. Useful for nautical and coastal planning.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Coastal or ocean coordinates as lat,lon (e.g. 51.5,-1.8).",
+                    },
+                    days: {
+                        type: "number",
+                        description: "Forecast days (1–7 depending on plan). Default: 1.",
+                    },
+                    tides: {
+                        type: "string",
+                        enum: ["yes", "no"],
+                        description: "Include tide data (Pro+ plan and above). Default: no.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "get_astronomy",
+            description: "Get astronomy data for a location and date: sunrise, sunset, moonrise, moonset, moon phase, and moon illumination percentage.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                    dt: {
+                        type: "string",
+                        description: "Date in yyyy-MM-dd format.",
+                    },
+                },
+                required: ["q", "dt"],
+            },
+        },
+        {
+            name: "get_timezone",
+            description: "Get timezone and current local time for any location. Returns IANA timezone ID (e.g. Europe/London), local time string, and unix epoch.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "search_locations",
+            description: "Search for cities and towns by partial name or postcode. Returns an array of matching locations with their coordinates, region, country, and URL slug. Useful for building location pickers or resolving ambiguous place names.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Partial city name, postcode, or coordinates to search. E.g. 'lond', 'SW1', 'paris'.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "ip_lookup",
+            description: "Look up geolocation data for an IP address: city, region, country, coordinates, timezone, and whether it's in the EU. Pass 'auto:ip' to geolocate the caller's own IP address.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "IPv4 address, IPv6 address, or 'auto:ip' for caller's IP.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "get_alerts",
+            description: "Get active government weather alerts and warnings for a location. Covers USA, UK, Europe, and rest of world. Returns headline, severity, urgency, affected areas, and full description.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+        {
+            name: "get_sports",
+            description: "Get upcoming sports events (football/soccer, cricket, golf) for a location, with stadium, country, tournament name, and start time.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    q: {
+                        type: "string",
+                        description: "Location query — city name, lat/lon, zip, postcode, or IATA.",
+                    },
+                },
+                required: ["q"],
+            },
+        },
+    ],
+}));
+// CALL TOOL
+server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "get_current_weather": {
+                const { q, aqi = "no" } = args;
+                result = await weatherRequest("/current.json", { q, aqi });
+                break;
+            }
+            case "get_forecast": {
+                const { q, days = 3, alerts = "no", aqi = "no" } = args;
+                result = await weatherRequest("/forecast.json", { q, days, alerts, aqi });
+                break;
+            }
+            case "get_history": {
+                const { q, dt, end_dt } = args;
+                const params = { q, dt };
+                if (end_dt)
+                    params.end_dt = end_dt;
+                result = await weatherRequest("/history.json", params);
+                break;
+            }
+            case "get_future_weather": {
+                const { q, dt } = args;
+                result = await weatherRequest("/future.json", { q, dt });
+                break;
+            }
+            case "get_marine_weather": {
+                const { q, days = 1, tides = "no" } = args;
+                result = await weatherRequest("/marine.json", { q, days, tides });
+                break;
+            }
+            case "get_astronomy": {
+                const { q, dt } = args;
+                result = await weatherRequest("/astronomy.json", { q, dt });
+                break;
+            }
+            case "get_timezone": {
+                const { q } = args;
+                result = await weatherRequest("/timezone.json", { q });
+                break;
+            }
+            case "search_locations": {
+                const { q } = args;
+                result = await weatherRequest("/search.json", { q });
+                break;
+            }
+            case "ip_lookup": {
+                const { q } = args;
+                result = await weatherRequest("/ip.json", { q });
+                break;
+            }
+            case "get_alerts": {
+                const { q } = args;
+                result = await weatherRequest("/alerts.json", { q });
+                break;
+            }
+            case "get_sports": {
+                const { q } = args;
+                result = await weatherRequest("/sports.json", { q });
+                break;
+            }
+            default:
+                throw new types_js_1.McpError(types_js_1.ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof types_js_1.McpError)
+            throw error;
+        throw new types_js_1.McpError(types_js_1.ErrorCode.InternalError, `Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+});
+// START
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error("WeatherAPI MCP server running. Set WEATHERAPI_KEY env var to authenticate.");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "weatherapi-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for WeatherAPI.com — real-time weather, forecasts, history, marine, astronomy, air quality and more for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "weatherapi-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "weather",
+    "weatherapi",
+    "forecast",
+    "ai",
+    "claude",
+    "model-context-protocol",
+    "agent",
+    "geolocation",
+    "astronomy"
+  ],
+  "author": "WeatherAPI.com",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/weatherapicom/weatherapi-mcp"
+  },
+  "homepage": "https://www.weatherapi.com",
+  "bugs": {
+    "url": "https://www.weatherapi.com/contact.aspx"
+  }
+}

package/src/index.ts

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_KEY = process.env.WEATHERAPI_KEY;
+const BASE_URL = "https://api.weatherapi.com/v1";
+
+if (!API_KEY) {
+  console.error("Error: WEATHERAPI_KEY environment variable is required.");
+  console.error("Get a free key at https://www.weatherapi.com/signup.aspx");
+  process.exit(1);
+}
+
+// Helper: make a GET request to WeatherAPI
+async function weatherRequest(
+  endpoint: string,
+  params: Record<string, string | number>
+): Promise<unknown> {
+  const searchParams = new URLSearchParams({ key: API_KEY! });
+  for (const [k, v] of Object.entries(params)) {
+    searchParams.set(k, String(v));
+  }
+  const url = `${BASE_URL}${endpoint}?${searchParams.toString()}`;
+  const res = await fetch(url);
+  const data = await res.json();
+  if (!res.ok) {
+    const err = data as { error?: { code: number; message: string } };
+    throw new McpError(
+      ErrorCode.InternalError,
+      `WeatherAPI error ${err.error?.code}: ${err.error?.message ?? res.statusText}`
+    );
+  }
+  return data;
+}
+
+const server = new Server(
+  {
+    name: "weatherapi-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// LIST TOOLS
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "get_current_weather",
+      description:
+        "Get real-time current weather for any location. Returns temperature, wind speed and direction, humidity, pressure, UV index, visibility, feels-like temperature, and weather condition. Optionally includes air quality (AQI) data.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description:
+              "Location query. Accepts: city name (London), lat/lon (51.5,-0.1), US zip (10001), UK postcode (SW1), IATA airport code (iata:LHR), IP address, or auto:ip for caller's location.",
+          },
+          aqi: {
+            type: "string",
+            enum: ["yes", "no"],
+            description: "Include air quality data (CO, NO2, O3, SO2, PM2.5, PM10). Default: no.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "get_forecast",
+      description:
+        "Get weather forecast for 1 to 14 days. Returns daily summaries (max/min/avg temp, rain chance, UV, wind) and hourly breakdowns. Also returns current conditions, astronomy data (sunrise/sunset/moon phase), and optionally weather alerts and air quality.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+          days: {
+            type: "number",
+            description: "Number of forecast days (1–14). Default: 3.",
+          },
+          alerts: {
+            type: "string",
+            enum: ["yes", "no"],
+            description: "Include government weather alerts. Default: no.",
+          },
+          aqi: {
+            type: "string",
+            enum: ["yes", "no"],
+            description: "Include air quality data. Default: no.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "get_history",
+      description:
+        "Get historical weather data for a specific date from 1 January 2010 onwards. Returns daily summary and full hourly breakdown. Useful for past weather lookups, analytics, and backtesting.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+          dt: {
+            type: "string",
+            description: "Date in yyyy-MM-dd format. Must be on or after 2010-01-01.",
+          },
+          end_dt: {
+            type: "string",
+            description:
+              "Optional end date for a date range (Pro+ plan only). Max 30 days range. yyyy-MM-dd.",
+          },
+        },
+        required: ["q", "dt"],
+      },
+    },
+    {
+      name: "get_future_weather",
+      description:
+        "Get future weather forecast for a date between 14 and 300 days from today. Returns 3-hourly data. Available on Pro+ plan and above.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+          dt: {
+            type: "string",
+            description:
+              "Future date in yyyy-MM-dd format. Must be between 14 and 300 days from today.",
+          },
+        },
+        required: ["q", "dt"],
+      },
+    },
+    {
+      name: "get_marine_weather",
+      description:
+        "Get marine and sailing weather forecast including significant wave height, swell height, swell direction, swell period, and optionally tide data. Useful for nautical and coastal planning.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Coastal or ocean coordinates as lat,lon (e.g. 51.5,-1.8).",
+          },
+          days: {
+            type: "number",
+            description: "Forecast days (1–7 depending on plan). Default: 1.",
+          },
+          tides: {
+            type: "string",
+            enum: ["yes", "no"],
+            description: "Include tide data (Pro+ plan and above). Default: no.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "get_astronomy",
+      description:
+        "Get astronomy data for a location and date: sunrise, sunset, moonrise, moonset, moon phase, and moon illumination percentage.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+          dt: {
+            type: "string",
+            description: "Date in yyyy-MM-dd format.",
+          },
+        },
+        required: ["q", "dt"],
+      },
+    },
+    {
+      name: "get_timezone",
+      description:
+        "Get timezone and current local time for any location. Returns IANA timezone ID (e.g. Europe/London), local time string, and unix epoch.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "search_locations",
+      description:
+        "Search for cities and towns by partial name or postcode. Returns an array of matching locations with their coordinates, region, country, and URL slug. Useful for building location pickers or resolving ambiguous place names.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Partial city name, postcode, or coordinates to search. E.g. 'lond', 'SW1', 'paris'.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "ip_lookup",
+      description:
+        "Look up geolocation data for an IP address: city, region, country, coordinates, timezone, and whether it's in the EU. Pass 'auto:ip' to geolocate the caller's own IP address.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "IPv4 address, IPv6 address, or 'auto:ip' for caller's IP.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "get_alerts",
+      description:
+        "Get active government weather alerts and warnings for a location. Covers USA, UK, Europe, and rest of world. Returns headline, severity, urgency, affected areas, and full description.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, IATA, or IP.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+    {
+      name: "get_sports",
+      description:
+        "Get upcoming sports events (football/soccer, cricket, golf) for a location, with stadium, country, tournament name, and start time.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          q: {
+            type: "string",
+            description: "Location query — city name, lat/lon, zip, postcode, or IATA.",
+          },
+        },
+        required: ["q"],
+      },
+    },
+  ],
+}));
+
+// CALL TOOL
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result: unknown;
+
+    switch (name) {
+      case "get_current_weather": {
+        const { q, aqi = "no" } = args as { q: string; aqi?: string };
+        result = await weatherRequest("/current.json", { q, aqi });
+        break;
+      }
+      case "get_forecast": {
+        const { q, days = 3, alerts = "no", aqi = "no" } = args as {
+          q: string;
+          days?: number;
+          alerts?: string;
+          aqi?: string;
+        };
+        result = await weatherRequest("/forecast.json", { q, days, alerts, aqi });
+        break;
+      }
+      case "get_history": {
+        const { q, dt, end_dt } = args as { q: string; dt: string; end_dt?: string };
+        const params: Record<string, string | number> = { q, dt };
+        if (end_dt) params.end_dt = end_dt;
+        result = await weatherRequest("/history.json", params);
+        break;
+      }
+      case "get_future_weather": {
+        const { q, dt } = args as { q: string; dt: string };
+        result = await weatherRequest("/future.json", { q, dt });
+        break;
+      }
+      case "get_marine_weather": {
+        const { q, days = 1, tides = "no" } = args as {
+          q: string;
+          days?: number;
+          tides?: string;
+        };
+        result = await weatherRequest("/marine.json", { q, days, tides });
+        break;
+      }
+      case "get_astronomy": {
+        const { q, dt } = args as { q: string; dt: string };
+        result = await weatherRequest("/astronomy.json", { q, dt });
+        break;
+      }
+      case "get_timezone": {
+        const { q } = args as { q: string };
+        result = await weatherRequest("/timezone.json", { q });
+        break;
+      }
+      case "search_locations": {
+        const { q } = args as { q: string };
+        result = await weatherRequest("/search.json", { q });
+        break;
+      }
+      case "ip_lookup": {
+        const { q } = args as { q: string };
+        result = await weatherRequest("/ip.json", { q });
+        break;
+      }
+      case "get_alerts": {
+        const { q } = args as { q: string };
+        result = await weatherRequest("/alerts.json", { q });
+        break;
+      }
+      case "get_sports": {
+        const { q } = args as { q: string };
+        result = await weatherRequest("/sports.json", { q });
+        break;
+      }
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify(result, null, 2),
+        },
+      ],
+    };
+  } catch (error) {
+    if (error instanceof McpError) throw error;
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Unexpected error: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+});
+
+// START
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("WeatherAPI MCP server running. Set WEATHERAPI_KEY env var to authenticate.");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}