Weather Forecast MCP Server: Tool Design Plan

I haven't seen your API's docs, so this assumes a typical weather REST API with geocoding, current conditions, hourly and daily forecasts, and alerts. Send me the real endpoints and I'll adjust the plan.

1. Server basics

2. Tools

All tools are read-only, so each gets the annotations readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true.

weather_search_locations

Resolves a place name to coordinates. Forecast tools depend on this, since LLMs are bad at guessing lat/lon.

• query (string, 2–100 chars): e.g. "Paris" or "Portland, Oregon".
• country_code (optional string, ISO-3166 alpha-2): disambiguates results.
• limit (int, 1–50, default 10) and offset (int, default 0).
• Returns: location_id, name, admin_region, country, latitude, longitude, timezone, plus pagination metadata.

weather_get_current_conditions

• location: a shared location input (see below).
• units: metric or imperial (default metric).
• response_format: markdown or json (default markdown).
• Returns: temperature, feels-like, humidity, wind speed and direction, precipitation, condition text, observation time and the location's timezone.

weather_get_hourly_forecast

• location, units and response_format, as above.
• start_hour_offset (int, default 0) and limit (int, 1–48, default 24). These act as the pagination window.
• fields (optional enum array, e.g. temperature, precipitation_probability, wind). This trims the output, since hourly data is large.

weather_get_daily_forecast

• location, units and response_format, as above.
• days (int, 1–16, default 7), with offset for paging past the first window if the API supports it.
• Returns: high/low, precipitation total and probability, wind, UV index, sunrise/sunset, and a condition summary.

weather_get_alerts

• location.
• severity (optional enum: minor, moderate, severe, extreme).
• limit and offset.
• Returns: event, severity, onset/expiry, affected area, and description. An empty list is a valid result, reported as "no active alerts".

Optional, if the API supports them

• weather_get_historical_weather: location, start_date and end_date (ISO YYYY-MM-DD, with a max range), plus limit and offset.
• weather_get_air_quality: AQI and pollutants.

Shared location input

Every forecast tool accepts one of two forms, validated with a Zod union:

• { latitude: number (-90..90), longitude: number (-180..180) }
• { location_id: string } from weather_search_locations

I'd also consider letting forecast tools take a plain place_name and geocode internally. That saves the model a round trip, but it can silently pick the wrong "Springfield", so the response would have to echo the resolved place. My recommendation is to require explicit coordinates or an ID, because ambiguity is the most common failure here.

3. Pagination

Most weather data is small, so pagination only matters for location search, alerts, hourly data and history.

• Style: limit plus offset as inputs, even if the upstream API uses cursors or page numbers. The server translates between them. If the API is cursor-only, return an opaque next_cursor instead.
• Defaults: keep them small (10 for search, 24 hours for hourly) and enforce hard maximums in the schema.
• Response metadata, included in both text and structuredContent:

  { "total": 87, "count": 20, "offset": 0, "has_more": true, "next_offset": 20 }
  

• Truncation: cap output at about 25k characters. If exceeded, cut the result and add a note like "Truncated; use limit/fields or a smaller range."

4. Error handling

Errors are returned as tool results with isError: true, not as protocol errors. Each message should say what happened and what to do next.

Implementation notes:

• Use one shared handleApiError() helper that maps status codes to these messages. Never leak raw stack traces or the API key.
• Use a request timeout (about 10s). Retry once on 5xx or network errors with a short backoff, and never retry 4xx.
• Add a small in-memory cache (TTL of about 5–10 minutes for forecasts, 24 hours for geocoding) to cut rate-limit pressure.
• Validate inputs with Zod .strict() schemas, so bad inputs fail before any HTTP call.

5. Output conventions

• Each tool defines an outputSchema and returns structuredContent, plus a text rendering in the requested response_format.
• Always include units and the location's timezone in output, because "18°" and "3 pm" are ambiguous without them.
• Markdown output is human-readable (dates and place names, not raw IDs). JSON output is complete and meant for programmatic use.

6. Suggested project layout

weather-mcp-server/
├── src/
│   ├── index.ts            # server init, transport
│   ├── constants.ts        # base URL, CHARACTER_LIMIT, defaults
│   ├── schemas/            # shared Zod: location, units, pagination
│   ├── services/
│   │   └── weatherClient.ts  # HTTP, auth, retry, cache, handleApiError
│   ├── formatters.ts       # markdown/json rendering, truncation
│   └── tools/              # one file per tool group
└── package.json, tsconfig.json

7. Next steps

1. Send me the API docs or the name of the provider, and I'll finalize the tool list and field mappings.
2. Build the API client and shared helpers first, then the tools.
3. Test with npx @modelcontextprotocol/inspector.
4. Write about 10 read-only evaluation questions, such as "Which of Lisbon or Madrid has the higher forecast high on Friday?", to check that a model can chain search_locations into a forecast tool.

Questions that would change the plan:

• Which weather provider are you using?
• Is this server local or remote?
• Do you need history or air quality, or just forecasts and alerts?