weatherport

weatherport

weatherport brings OpenWeather to the terminal and to MCP clients. It answers the questions people actually ask of that service: what is it like in a city right now, what is coming over the next five days in three-hour steps, what does the fuller One Call 3.0 view say for a precise point on the map, how clean is the air there, and where exactly is a place name? One binary serves both a command-line interface and a stdio MCP server.

An OpenWeather API key is required for every call. Put it in the OPENWEATHER_API_KEY environment variable; weatherport sends it to https://api.openweathermap.org as the appid query parameter and never prints it. When the variable is missing or blank, calls fail with an error that names it, before any request is made. Note that One Call 3.0 needs a separate upstream subscription in reality, even though it uses the same key.

Units are optional everywhere they apply: standard, metric, or imperial. Anything else is rejected before a request.

Install

npx @reneturcios/weatherport current Paris --units metric

Or run the container image:

docker run -i -e OPENWEATHER_API_KEY ghcr.io/cloudcorprecords/weatherport

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

export OPENWEATHER_API_KEY=<your key>

weatherport current Paris --units metric
weatherport forecast Berlin --units imperial --count 5
weatherport onecall 51.5 -0.12 --units metric
weatherport pollution 51.5 -0.12
weatherport geocode Paris --limit 3

weatherport --version

Each command prints the upstream JSON payload. Exit codes: 0 on success, 1 when a call fails (including a missing OPENWEATHER_API_KEY or an API error), 2 for usage errors.

MCP server

npx -y @reneturcios/weatherport mcp

MCP client configuration:

{
  "mcpServers": {
    "weatherport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/weatherport", "mcp"],
      "env": { "OPENWEATHER_API_KEY": "..." }
    }
  }
}

Tools

Tool	Input	What it returns
get_current_weather	location (required), units (optional)	Current weather for a city.
get_forecast	location (required), units, count (optional)	5-day forecast in 3-hour steps.
get_onecall_weather	lat, lon (required), units (optional)	One Call 3.0 current, hourly, and daily summaries.
get_air_pollution	lat, lon (required)	Current AQI and pollutant components.
geocode_location	query (required), limit (optional)	Coordinate matches for a place name.

Latitude must be in [-90, 90] and longitude in [-180, 180]; out-of-range values are rejected before any request. HTTP failures surface the status plus OpenWeather's message field when the upstream JSON provides one.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.