mcp-meteoblue 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unixfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# mcp-meteoblue
+
+An MCP server for the [meteoblue Weather API](https://docs.meteoblue.com/en/weather-apis/introduction/overview), written in JavaScript. It lets MCP clients search for locations, fetch forecasts using packages available through the Free Weather API, and request forecast meteogram images.
+
+## Tools
+
+- `search_locations` resolves cities, postal codes, and IATA/ICAO airport codes with meteoblue Location Search.
+- `get_forecast` accepts either a place name or coordinates and returns forecast JSON. It defaults to current, hourly, and daily weather.
+- `get_forecast_image` accepts either a place name or coordinates and returns a forecast image directly to the MCP client.
+
+Place names passed to forecast or image tools are always resolved through the official meteoblue Location Search API. Forecast package inputs are restricted to the packages listed in the Free Weather API documentation.
+
+> [!NOTE]
+> meteoblue's current Free Weather API documentation says that images require a higher access level. The image tool is included for keys with an Image API entitlement and will return a clear authorization error otherwise.
+
+## Requirements
+
+- Node.js 20 or newer
+- A [meteoblue API key](https://www.meteoblue.com/en/weather-api)
+
+Keep the key private. This server reads it from `METEOBLUE_API_KEY`; it is never part of the package or MCP tool arguments.
+
+## Run from npm
+
+Add this stdio server to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "meteoblue": {
+      "command": "npx",
+      "args": ["-y", "mcp-meteoblue"],
+      "env": {
+        "METEOBLUE_API_KEY": "your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+Or run it directly:
+
+```sh
+METEOBLUE_API_KEY=your_api_key_here npx -y mcp-meteoblue
+```
+
+The server uses stdio, so it intentionally produces no normal terminal output while it waits for an MCP client.
+
+## Develop locally
+
+```sh
+npm install
+npm test
+METEOBLUE_API_KEY=your_api_key_here npm start
+```
+
+Point an MCP client at `node /absolute/path/to/mcp-meteoblue/src/index.js` and set the environment variable in that client's configuration.
+
+## Releases
+
+GitHub Actions runs the test suite and validates the npm tarball on Node.js 20, 22, 24, and 26 for every push and pull request.
+
+Publishing a GitHub release triggers `.github/workflows/publish.yml`. The workflow uses npm trusted publishing (OIDC) and automatically attaches provenance. Configure the npm trusted publisher with:
+
+- GitHub owner: `unixfox`
+- Repository: `mcp-meteoblue`
+- Workflow: `publish.yml`
+- Environment: `npm`
+
+No npm token is stored in GitHub when trusted publishing is configured.
+
+## API scope
+
+The server calls only:
+
+- `https://www.meteoblue.com/{language}/server/search/query3`
+- `https://my.meteoblue.com/packages/{packages}`
+- `https://my.meteoblue.com/images/{forecast-image-type}`
+
+It does not expose meteoblue History, Dataset, Maps, Measurements, or other APIs.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mcp-meteoblue",
+  "version": "1.0.0",
+  "description": "MCP server for meteoblue forecast, forecast image, and location search APIs",
+  "type": "module",
+  "bin": {
+    "mcp-meteoblue": "src/index.js"
+  },
+  "exports": "./src/index.js",
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node src/index.js",
+    "test": "node --test",
+    "check": "node --check src/index.js && node --check src/meteoblue.js && npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "meteoblue",
+    "weather",
+    "forecast"
+  ],
+  "author": "unixfox",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unixfox/mcp-meteoblue.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unixfox/mcp-meteoblue/issues"
+  },
+  "homepage": "https://github.com/unixfox/mcp-meteoblue#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/constants.js

@@ -0,0 +1,73 @@
+export const FREE_FORECAST_PACKAGES = [
+  "basic-15min",
+  "basic-1h",
+  "basic-3h",
+  "basic-day",
+  "current",
+  "clouds-1h",
+  "clouds-3h",
+  "clouds-day",
+  "sunmoon",
+  "agro-1h",
+  "agro-3h",
+  "agro-day",
+  "agromodelleafwetness-1h",
+  "agromodelsowing-1h",
+  "agromodelspray-1h",
+  "solar-15min",
+  "solar-1h",
+  "solar-3h",
+  "solar-day",
+  "solarensemble-1h",
+  "wind-15min",
+  "wind-1h",
+  "wind-3h",
+  "wind-day",
+  "wind80ensemble-1h",
+  "sea-1h",
+  "sea-3h",
+  "sea-day",
+  "air-1h",
+  "air-3h",
+  "air-day",
+  "airquality-1h",
+  "airquality-3h",
+  "airquality-day",
+  "multimodel-1h",
+  "multimodeltemperature-1h",
+  "multimodelprecipitation-1h",
+  "multimodelrh-1h",
+  "multimodelwind-1h",
+  "multimodelwind80-1h",
+  "multimodelclouds-1h",
+  "multimodelradiation-1h",
+  "trend-1h",
+  "trend-day",
+  "trendpro-1h",
+  "trendpro-day",
+  "ensemble-1h"
+];
+
+export const FORECAST_IMAGE_TYPES = [
+  "meteogram",
+  "meteogram_extended",
+  "meteogram_one",
+  "meteogram_snow",
+  "meteogram_agro",
+  "meteogram_sowing",
+  "meteogram_spraying",
+  "meteogram_soiltraffic",
+  "meteogram_air",
+  "meteogram_sounding",
+  "meteogram_stueve",
+  "meteogram_thermal",
+  "meteogram_14day",
+  "meteogram_multimodel",
+  "meteogram_multimodelensemble",
+  "meteogram_multimodelwind",
+  "meteogram_solar_forecast",
+  "meteogram_sea",
+  "meteogram_sea_7day",
+  "meteogram_surf",
+  "meteogram_seasonal"
+];

package/src/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+try {
+  const server = createServer();
+  await server.connect(new StdioServerTransport());
+} catch (error) {
+  console.error(`mcp-meteoblue: ${error.message}`);
+  process.exit(1);
+}

package/src/meteoblue.js

@@ -0,0 +1,125 @@
+const API_BASE_URL = "https://my.meteoblue.com";
+const LOCATION_BASE_URL = "https://www.meteoblue.com";
+
+export class MeteoblueApiError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "MeteoblueApiError";
+    this.status = status;
+  }
+}
+
+export class MeteoblueClient {
+  constructor({ apiKey, fetchImpl = globalThis.fetch, timeoutMs = 30_000 } = {}) {
+    if (!apiKey) {
+      throw new Error("METEOBLUE_API_KEY is required");
+    }
+    if (typeof fetchImpl !== "function") {
+      throw new Error("A fetch implementation is required");
+    }
+    this.apiKey = apiKey;
+    this.fetch = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async searchLocations(query, { language = "en", countryCode, page = 1, limit = 10 } = {}) {
+    const url = new URL(`/${encodeURIComponent(language)}/server/search/query3`, LOCATION_BASE_URL);
+    url.searchParams.set("query", query);
+    url.searchParams.set("apikey", this.apiKey);
+    url.searchParams.set("page", String(page));
+    url.searchParams.set("itemsPerPage", String(limit));
+    if (countryCode) url.searchParams.set("iso2", countryCode.toUpperCase());
+
+    return this.#requestJson(url, "location search");
+  }
+
+  async resolveLocation(query, options = {}) {
+    const data = await this.searchLocations(query, { ...options, page: 1, limit: 1 });
+    const location = data.results?.[0];
+    if (!location) {
+      throw new MeteoblueApiError(`No location found for “${query}”`, 404);
+    }
+    return location;
+  }
+
+  async getForecast({ packages, latitude, longitude, elevation, forecastDays, historyDays, timezone, temperatureUnit, windSpeedUnit, precipitationUnit }) {
+    const url = new URL(`/packages/${packages.join(",")}`, API_BASE_URL);
+    this.#addCoordinates(url, latitude, longitude, elevation);
+    url.searchParams.set("apikey", this.apiKey);
+    if (forecastDays !== undefined) url.searchParams.set("forecastDays", String(forecastDays));
+    if (historyDays !== undefined) url.searchParams.set("historyDays", String(historyDays));
+    if (timezone) url.searchParams.set("tz", timezone);
+    if (temperatureUnit) url.searchParams.set("temperatureUnit", temperatureUnit);
+    if (windSpeedUnit) url.searchParams.set("windSpeedUnit", windSpeedUnit);
+    if (precipitationUnit) url.searchParams.set("precipitationUnit", precipitationUnit);
+
+    return this.#requestJson(url, "forecast");
+  }
+
+  async getForecastImage({ type, latitude, longitude, elevation, options = {} }) {
+    const url = new URL(`/images/${type}`, API_BASE_URL);
+    this.#addCoordinates(url, latitude, longitude, elevation);
+    url.searchParams.set("apikey", this.apiKey);
+    for (const [key, value] of Object.entries(options)) {
+      if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+    }
+
+    const response = await this.#fetch(url);
+    if (!response.ok) throw await this.#apiError(response, "forecast image");
+    const contentType = response.headers.get("content-type")?.split(";", 1)[0] || "image/png";
+    if (!contentType.startsWith("image/")) {
+      throw new MeteoblueApiError("meteoblue returned a non-image response", response.status);
+    }
+    const data = Buffer.from(await response.arrayBuffer()).toString("base64");
+    return { data, mimeType: contentType };
+  }
+
+  #addCoordinates(url, latitude, longitude, elevation) {
+    url.searchParams.set("lat", String(latitude));
+    url.searchParams.set("lon", String(longitude));
+    if (elevation !== undefined) url.searchParams.set("asl", String(elevation));
+  }
+
+  async #requestJson(url, operation) {
+    const response = await this.#fetch(url);
+    if (!response.ok) throw await this.#apiError(response, operation);
+    try {
+      return await response.json();
+    } catch {
+      throw new MeteoblueApiError(`meteoblue returned invalid JSON for ${operation}`, response.status);
+    }
+  }
+
+  async #fetch(url) {
+    try {
+      return await this.fetch(url, {
+        headers: { "user-agent": "mcp-meteoblue/1.0.0" },
+        signal: AbortSignal.timeout(this.timeoutMs)
+      });
+    } catch (error) {
+      if (error.name === "TimeoutError" || error.name === "AbortError") {
+        throw new MeteoblueApiError("meteoblue request timed out");
+      }
+      throw new MeteoblueApiError(`Could not reach meteoblue: ${error.message}`);
+    }
+  }
+
+  async #apiError(response, operation) {
+    let detail = "";
+    try {
+      const body = await response.text();
+      if (body && body.length < 500) {
+        try {
+          const parsed = JSON.parse(body);
+          detail = parsed.message || parsed.error || parsed.detail || "";
+        } catch {
+          detail = body.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim();
+        }
+      }
+    } catch {
+      // Keep the status-only error when the body cannot be read.
+    }
+    const suffix = detail ? `: ${detail}` : "";
+    return new MeteoblueApiError(`meteoblue ${operation} request failed (${response.status})${suffix}`, response.status);
+  }
+}

package/src/server.js

@@ -0,0 +1,124 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { FORECAST_IMAGE_TYPES, FREE_FORECAST_PACKAGES } from "./constants.js";
+import { MeteoblueClient } from "./meteoblue.js";
+
+const latitude = z.number().min(-90).max(90).optional().describe("WGS84 latitude; required with longitude when location is omitted");
+const longitude = z.number().min(-180).max(180).optional().describe("WGS84 longitude; required with latitude when location is omitted");
+const elevation = z.number().min(-500).max(9000).optional().describe("Elevation above sea level in metres");
+const location = z.string().min(2).optional().describe("Place name, postal code, IATA, or ICAO code; resolved with meteoblue Location Search");
+
+function textResult(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+function errorResult(error) {
+  return { isError: true, content: [{ type: "text", text: error.message || "Unexpected error" }] };
+}
+
+async function coordinatesFor(client, input) {
+  if (input.location) {
+    const resolved = await client.resolveLocation(input.location, {
+      language: input.language,
+      countryCode: input.countryCode
+    });
+    return {
+      latitude: resolved.lat,
+      longitude: resolved.lon,
+      elevation: input.elevation ?? resolved.asl,
+      resolvedLocation: resolved
+    };
+  }
+  if (input.latitude === undefined || input.longitude === undefined) {
+    throw new Error("Provide either location, or both latitude and longitude");
+  }
+  return { latitude: input.latitude, longitude: input.longitude, elevation: input.elevation };
+}
+
+export function createServer({ apiKey = process.env.METEOBLUE_API_KEY, client } = {}) {
+  const meteoblue = client || new MeteoblueClient({ apiKey });
+  const server = new McpServer({ name: "mcp-meteoblue", version: "1.0.0" });
+
+  server.registerTool(
+    "search_locations",
+    {
+      title: "Search meteoblue locations",
+      description: "Resolve a city, place, postal code, IATA code, or ICAO code to coordinates and elevation using the meteoblue Location Search API.",
+      inputSchema: {
+        query: z.string().min(2).describe("Location search text"),
+        language: z.string().regex(/^[a-z]{2}$/i).default("en").describe("Two-letter result language"),
+        countryCode: z.string().regex(/^[a-z]{2}$/i).optional().describe("Optional ISO 3166-1 alpha-2 country filter"),
+        page: z.number().int().min(1).default(1),
+        limit: z.number().int().min(1).max(100).default(10)
+      }
+    },
+    async (input) => {
+      try {
+        return textResult(await meteoblue.searchLocations(input.query, input));
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "get_forecast",
+    {
+      title: "Get meteoblue weather forecast",
+      description: "Get meteoblue forecast JSON by place name or coordinates. Place names are resolved through the Location Search API. Only packages documented for the Free Weather API are accepted.",
+      inputSchema: {
+        location,
+        latitude,
+        longitude,
+        elevation,
+        language: z.string().regex(/^[a-z]{2}$/i).default("en"),
+        countryCode: z.string().regex(/^[a-z]{2}$/i).optional(),
+        packages: z.array(z.enum(FREE_FORECAST_PACKAGES)).min(1).max(10).default(["current", "basic-1h", "basic-day"]),
+        forecastDays: z.number().int().min(0).max(7).default(7),
+        historyDays: z.number().int().min(0).max(4).default(0),
+        timezone: z.string().optional().describe("IANA timezone such as Europe/Paris; auto-detected when omitted"),
+        temperatureUnit: z.enum(["C", "K", "F"]).default("C"),
+        windSpeedUnit: z.enum(["m/s", "km/h", "mph", "kn", "bft"]).default("km/h"),
+        precipitationUnit: z.enum(["metric", "imperial"]).default("metric")
+      }
+    },
+    async (input) => {
+      try {
+        const coords = await coordinatesFor(meteoblue, input);
+        const forecast = await meteoblue.getForecast({ ...input, ...coords });
+        return textResult({ resolvedLocation: coords.resolvedLocation, forecast });
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  server.registerTool(
+    "get_forecast_image",
+    {
+      title: "Get meteoblue forecast image",
+      description: "Generate a meteoblue forecast meteogram by place name or coordinates. Returns the PNG directly. Image access depends on the API key's meteoblue entitlement.",
+      inputSchema: {
+        type: z.enum(FORECAST_IMAGE_TYPES).default("meteogram"),
+        location,
+        latitude,
+        longitude,
+        elevation,
+        language: z.string().regex(/^[a-z]{2}$/i).default("en"),
+        countryCode: z.string().regex(/^[a-z]{2}$/i).optional(),
+        options: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).default({}).describe("Image-specific meteoblue query parameters")
+      }
+    },
+    async (input) => {
+      try {
+        const coords = await coordinatesFor(meteoblue, input);
+        const image = await meteoblue.getForecastImage({ ...input, ...coords });
+        return { content: [{ type: "image", data: image.data, mimeType: image.mimeType }] };
+      } catch (error) {
+        return errorResult(error);
+      }
+    }
+  );
+
+  return server;
+}