Skip to main content
Glama

weather-mcp

deploy status

An MCP server built on AgentBack that exposes weather data from the free Open-Meteo API β€” no API key required. Decorator-driven tools with Zod input/output schemas, served over stdio, Streamable HTTP, or a dev console from one set of DI wiring.

πŸ”­ Live demo: agentback-demo.vercel.app β€” the AgentBack dev console (Context Β· API Β· MCP Β· Schema panels), deployed serverless on Vercel.

npm install
npm run build && npm start      # stdio MCP server (for Claude Desktop / Cursor)
npm run serve:http              # remote MCP server over HTTP at /mcp
npm test                        # in-memory MCP session, no process spawn
npm run console                 # dev web UI at http://localhost:3000/console

Architecture

Five layers, dependencies flowing strictly downward (Transports β†’ Composition β†’ Adapter β†’ Domain β†’ Contracts). Three transports share one DI wiring.

weather-mcp architecture

See docs/architecture.md for the layer-by-layer breakdown and runtime flow (with an editable Mermaid source). The diagram is also available as an interactive, exportable page β€” docs/architecture-diagram.html.

Related MCP server: wetter-mcp-server

Transports

The same tools and DI wiring (src/wiring.ts) are served three ways:

Entry

Command

Transport

Use

src/main.ts

npm start

stdio

Local β€” wire into Claude Desktop / Cursor.

src/serve-http.ts

npm run serve:http

Streamable HTTP at POST/GET/DELETE /mcp

Remote clients over the network.

src/console.ts

npm run console

HTTP web UI

Development inspector (see below).

HTTP transport

npm run serve:http exposes the server at http://localhost:3000/mcp (PORT=3939 npm run serve:http to change the port). Point any Streamable-HTTP MCP client at that URL.

Auth: every request needs a valid API key in the x-api-key header (or ?apiKey=). Keys come from MCP_API_KEYS (comma-separated); if unset, a dev-local-key is generated and printed to stderr so local runs still work.

MCP_API_KEYS=key1,key2 PORT=3939 npm run serve:http
# client must send:  x-api-key: key1

Rate limiting: tools/call is throttled per (caller, tool) β€” 60/min by default, with get_forecast capped tighter at 20/min. Over the limit returns a JSON-RPC 429 with Retry-After. Both are configured in src/serve-http.ts.

For public deployment also set allowedHosts/allowedOrigins on installMcpHttp (DNS-rebinding protection), and consider a Redis store for the rate limiter so buckets are shared across instances.

Dev console

npm run console starts the AgentBack console β€” a web UI that composes the MCP inspector (list and invoke your tools from a form), the OpenAPI/Swagger explorer, and a DI context explorer. Override the port with PORT=3737 npm run console.

The console serves over HTTP, so it runs a RestApplication (src/console.ts) that reuses the exact same tool wiring as the stdio server (src/wiring.ts). It's a development tool β€” the stdio entry point (src/main.ts) is what you wire into Claude Desktop / Cursor.

A hosted instance is live at agentback-demo.vercel.app. The same buildConsoleApp() runs there serverless: src/console.ts exposes it with listen: false (mounts every route, binds no port) and api/index.ts hands the Express app to Vercel. See vercel.json for the deploy config.

Tools

Tool

Purpose

geocode_location

Resolve a place name (e.g. "Tokyo") to candidate latitude/longitude.

get_current_weather

Current conditions by city name or latitude+longitude.

get_forecast

Daily forecast (1–16 days) by city or latitude+longitude.

Each tool accepts temperature_unit (celsius/fahrenheit) and wind_speed_unit (kmh/ms/mph/kn). When you pass a city, it is geocoded automatically; pass coordinates directly to skip that step.

How it's wired

  • src/schemas.ts β€” the single source of truth. Each Zod schema is simultaneously the runtime validator, the z.infer type, and the agent-visible MCP input/output schema.

  • src/keys.ts β€” typed DI keys. WEATHER_SERVICE = BindingKey.create<WeatherService>('services.weather') ties the key to its type, so the binding and every @inject(WEATHER_SERVICE) are type-checked.

  • src/weather-service.ts β€” WeatherService, a stateless Open-Meteo client. @injectable declares its own binding: the WEATHER_SERVICE key (ContextTags.KEY) and singleton scope β€” it's pure I/O, so one shared instance is reused.

  • src/tools/weather.tools.ts β€” the @mcpServer() tool class. @mcpServer is built on @injectable: it makes the class an extension of the MCP_SERVERS extension point (singleton by default). Each @tool carries its Zod schemas and delegates to the injected WeatherService.

  • src/component.ts β€” WeatherComponent packages the static DI contributions in one manifest: MCPComponent plus both services (WeatherTools, WeatherService). A tool class is a plain service β€” the MCP server discovers it as an MCP_SERVERS extension and resolves it through its binding, so constructor @inject is honored (no controller needed).

  • src/wiring.ts β€” registerWeatherMcp(app, stdio) adds WeatherComponent and applies the per-entry transport config (stdio on/off). Shared by all three entry points, so they stay in lockstep.

  • src/serve-http.ts β€” exports buildHttpApp() (builds, doesn't start) so tests can drive the api-key auth + rate-limit gate; the CLI run is guarded by isMain(import.meta).

Claude Desktop / Cursor config

{
  "mcpServers": {
    "weather-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp/dist/main.js"]
    }
  }
}

Available Tools

3 tools
geocode_locationGeocode a place nameA

Resolve a free-text place name (e.g. "Tokyo", "Springfield, Illinois") to candidate latitude/longitude coordinates. Use this first when a user names an ambiguous place, then pass the chosen coordinates to the weather tools.

Inputs: count (required), query (required). Returns: query, matches

get_current_weatherCurrent weatherA

Get current weather conditions for a location. Specify EITHER a "city" name (it will be geocoded automatically) OR explicit "latitude" and "longitude". Returns temperature, "feels like", humidity, precipitation, wind, and a human-readable condition.

Inputs: wind_speed_unit (required), temperature_unit (required), city, latitude, +1 more. Returns: is_day, location, condition, wind_speed, +9 more

get_forecastDaily forecastA

Get a daily weather forecast (1-16 days) for a location. Specify EITHER a "city" name OR "latitude"+"longitude". Returns per-day high/low temperatures, precipitation total and probability, peak wind, and condition.

Inputs: days (required), wind_speed_unit (required), temperature_unit (required), city, +2 more. Returns: days, location, wind_speed_unit, temperature_unit

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool targets a distinct operation: geocoding text to coordinates, current conditions, and multi-day forecast. The two weather tools are cleanly separated by time horizon, and the geocode tool's role (disambiguating place names) is explicitly stated, so an agent can pick correctly.

    Naming Consistency5/5

    All three names follow a snake_case verb_noun pattern (geocode_location, get_current_weather, get_forecast) with clear, domain-appropriate verbs. No mixed conventions or vague verbs.

    Tool Count4/5

    Three tools is on the lean side, but each earns its place: geocoding, current conditions, and forecast form a minimal coherent surface. Nothing extraneous, though the surface is small enough that it borders on thin.

    Completeness4/5

    Core weather workflows are covered: location resolution, current conditions, and forecasts up to 16 days with temperature, precipitation, and wind. Minor gaps remain, such as hourly forecasts, historical data, or severe-weather alerts, which agents cannot work around without another server.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides weather forecasts and active alerts for US locations using the National Weather Service API. It supports both local stdio and remote HTTP/SSE transport modes for flexible integration with MCP clients.
      ISC
    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server providing worldwide weather via the free Open-Meteo APIs (no API key needed). Runs fully self-contained in Docker as a streamable-HTTP MCP service.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server that provides tools to retrieve weather information from a weather API, supporting both local stdio and remote Streamable HTTP transports.
      547 npm
      1
      MIT