The Tomorrow.io Model Context Protocol (MCP) server enables AI agents and MCP-compatible clients to access Tomorrow.io weather data through standardized tools.

This hosted MCP endpoint allows you to query real-time, forecast, historical, and event-based weather data using your Tomorrow.io API key.

Overview

With the Tomorrow.io MCP server, you can:

• Access weather data through MCP-compatible AI tools (e.g., Cursor, Claude, Windsurf)
• Retrieve real-time, forecast, and historical weather
• Analyze weather events and route-based risks
• Integrate weather intelligence directly into LLM workflows

Endpoint

Use the following MCP endpoint:

https://api.tomorrow.io/v4/tomorrow-weather/mcp

Authentication

Authenticate using your Tomorrow.io API key via request headers:

 X-Api-Key: <YOUR_TOMORROW_API_KEY

How It Works

The Tomorrow.io MCP server exposes weather capabilities as tools that can be called by MCP-compatible clients (such as Cursor, Claude, or Windsurf).

A typical flow:

1. Your MCP client connects to the Tomorrow.io MCP endpoint
2. The client discovers available tools (e.g., get_forecast_timeline)
3. An LLM or agent decides which tool to call based on user intent
4. The tool executes and returns structured weather data
5. The client uses the response to generate an answer or take action

Quick Start

Example MCP Configuration

Most MCP clients support a similar configuration format:

{
  "mcpServers": {
    "tomorrow-weather-mcp": {
      "type": "http",
      "url": "https://api.tomorrow.io/v4/tomorrow-weather/mcp",
      "headers": {
        "X-Api-Key": "${TOMORROW_API_KEY}"
      }
    }
  }
}

Client Integrations

Cursor

Add to your .mcp.json:

{
  "mcpServers": {
    "tomorrow-weather-mcp": {
      "type": "http",
      "url": "https://api.tomorrow.io/v4/tomorrow-weather/mcp",
      "headers": {
        "X-Api-Key": "${TOMORROW_API_KEY}"
      }
    }
  }
}

Claude Desktop (via mcp-remote)

Claude Desktop requires a bridge to connect to HTTP MCP servers:

{
  "mcpServers": {
    "tomorrow-weather-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.tomorrow.io/v4/tomorrow-weather/mcp",
        "--header",
        "X-Api-Key: ${TOMORROW_API_KEY}"
      ],
      "env": {
        "TOMORROW_API_KEY": "REPLACE_WITH_YOUR_API_KEY"
      }
    }
  }
}

Other MCP Clients (Cline, Roo, Windsurf)

Use the standard HTTP MCP configuration:

{
  "mcpServers": {
    "tomorrow-weather-mcp": {
      "type": "http",
      "url": "https://api.tomorrow.io/v4/tomorrow-weather/mcp",
      "headers": {
        "X-Api-Key": "${TOMORROW_API_KEY}"
      }
    }
  }
}

Available Tools

The MCP server exposes the following tools, grouped by capability:

Core Weather

Point and time-series weather for a location.

Weather Events

Condition-based event timelines and route-level weather risk.

AI Weather Intelligence (Gale AI)

Natural-language weather answers powered by Tomorrow.io's Gale AI.

Data Feeds

Query and inspect Tomorrow.io environmental data feeds (e.g., USGS water services, severe weather events, tropical cyclones).

Example: Natural Language to Tool Calls

User request:

"Will it rain in New York in the next 6 hours?"

Tool used:

• get_forecast_timeline

User request:

"Was it hotter than 30°C last week?"

Tool used:

• get_historical_weather

User request:

"What is the temperature right now in New York?"

Tool used:

• get_realtime_weather

Tool Reference

get_realtime_weather

Retrieve current weather conditions for a location.

Use cases

• “What is the weather right now?”
• Current conditions dashboards

Inputs

• location (required): "lat,lon" or place name
• units (optional): metric (default) or imperial

Returns

• Observation timestamp
• Temperature, humidity, wind, precipitation, visibility, pressure, UV index, and more

Example

Call:

{
  "tool": "get_realtime_weather",
  "arguments": {
    "location": "40.7128,-74.0060",
    "units": "metric"
  }
}

Response:

{
  "data": {
    "time": "2026-04-28T10:00:00Z",
    "values": {
      "temperature": 18.5,
      "temperatureApparent": 18.2,
      "humidity": 63,
      "windSpeed": 4.2,
      "windDirection": 210,
      "windGust": 6.8,
      "precipitationIntensity": 0,
      "visibility": 16,
      "cloudCover": 35,
      "pressureSurfaceLevel": 1015,
      "uvIndex": 5
    }
  },
  "location": {
    "lat": 40.7128,
    "lon": -74.0060,
    "name": "New York, USA"
  }
}

get_forecast_timeline

Retrieve forecast data across a time range.

Use cases

• Planning upcoming weather
• Forecast-based decision making

Inputs

• location (required)
• fields (required): weather parameters
• startTime, endTime (optional)
• timesteps (optional): 1h, 1d, 5m, 15m, 30m
• units
• timezone (optional)

Returns

• Time-series forecast intervals
• Field values per interval

Example

Call:

{
  "tool": "get_forecast_timeline",
  "arguments": {
    "location": "New York, NY",
    "fields": ["temperature", "precipitationProbability"],
    "timesteps": ["1h"],
    "startTime": "now",
    "endTime": "nowPlus6h",
    "units": "metric"
  }
}

Response:

{
  "timelines": [
    {
      "timestep": "1h",
      "intervals": [
        {
          "startTime": "2026-04-28T10:00:00Z",
          "values": {
            "temperature": 18.5,
            "precipitationProbability": 10
          }
        },
        {
          "startTime": "2026-04-28T11:00:00Z",
          "values": {
            "temperature": 19.2,
            "precipitationProbability": 15
          }
        }
      ]
    }
  ]
}

get_weather_summary

Generate a natural-language weather summary for a location across a specific time window, powered by Tomorrow.io's Gale AI weather intelligence.

Use cases

• “Summarize the weather in Boston this weekend.”
• Prose weather briefings for reports or notifications
• Prefer get_forecast_timeline when you need numeric values or a data table

Inputs

• Exactly ONE location form:
  • location: "lat,lon", a GeoJSON geometry string, or a place name
  • locationIds: array of pre-registered location UUIDs (1–50)
• startTime (required): ISO 8601 start of the window; must precede endTime
• endTime (required): ISO 8601 end of the window; must follow startTime
• units (optional): metric (default) or imperial
• timezone (optional): IANA timezone (e.g., "America/New_York")
• language (optional): response language override (e.g., "en", "es")

Returns

• answer: natural-language weather summary
• id: request identifier

Example

Call:

{
  "tool": "get_weather_summary",
  "arguments": {
    "location": "Boston, MA",
    "startTime": "2026-03-14T00:00:00Z",
    "endTime": "2026-03-16T00:00:00Z",
    "units": "imperial"
  }
}

Response:

{
  "answer": "This weekend in Boston will start mild and mostly sunny on Saturday with highs near 58°F. A cold front arrives Sunday afternoon, bringing scattered showers and gusty winds up to 25 mph, with temperatures dropping into the low 40s by evening.",
  "id": "162268957202136965"
}

ask_weather_question

Ask a free-text weather question and get a natural-language answer, powered by Tomorrow.io's Gale AI weather intelligence.

Use cases

• “Should I bring an umbrella to my meeting in London tomorrow afternoon?”
• Open-ended, conversational questions that mix locations, times, and conditions
• Prefer the structured tools (get_realtime_weather, get_forecast_timeline) when you need specific numeric values

Inputs

• question (required): the weather question in natural language. May contain {{0}}, {{1}} placeholders resolved from locationIds by index
• locationIds (optional): pre-registered location UUIDs referenced by {{index}} placeholders (1–50)
• includeLinks (optional): include an interactive map link (default false)
• units (optional): metric (default) or imperial
• timezone (optional): IANA timezone
• language (optional): response language override
• prompt (optional): extra guidance for how the answer should be shaped
• sessionId (optional): continue a previous conversation

Returns

• answer: natural-language answer
• sessionId: session id for follow-up questions
• id: request identifier
• links.map (optional): interactive map link (when includeLinks is true)

Example

Call:

{
  "tool": "ask_weather_question",
  "arguments": {
    "question": "Should I bring an umbrella to my meeting in London tomorrow afternoon?",
    "includeLinks": true,
    "units": "metric"
  }
}

Response:

{
  "answer": "Yes — light rain is likely in central London tomorrow afternoon, with a 70% chance of showers between 2 PM and 5 PM and temperatures around 14°C. An umbrella is a good idea.",
  "sessionId": "c0077d39-3ba7-431a-ab88-514f6ec8259e",
  "id": "162268957202136965",
  "links": {
    "map": "https://www.tomorrow.io/weather/..."
  }
}

query_feed_data

Query weather data from a Tomorrow.io data feed with filtering, sorting, and pagination.

Use cases

• Retrieve events, routes, or assets from data feeds (e.g., severe weather events, tropical cyclones)
• Filter by time range, geographic area, or attribute values

Inputs

• feedId (required): feed identifier
• timeRange (optional): { from, to } in ISO 8601
• geofence (optional): { geojsonGeometry, proximity } — proximity is a buffer distance in km (0–100)
• name (optional): case-insensitive substring name search
• filter (optional): MongoDB-style filter. Operators: $eq, $neq, $gt, $lt, $gte, $lte, $in, $nin, $contains, $startsWith, $endsWith, $and, $or, $not
• sortBy (optional): "createdAt", "startTime", "endTime", or an attribute name
• sortOrder (optional): "asc" or "desc" (default desc)
• pageSize (optional): results per page, 1–500 (default 500)
• nextPageToken (optional): pagination cursor

Returns

• Arrays of matching events items
• pagination: cursor tokens for additional pages

Example

Call:

{
  "tool": "query_feed_data",
  "arguments": {
    "feedId": "USGS_Water_Services",
    "timeRange": {
      "from": "2026-07-01T00:00:00Z",
      "to": "2026-07-14T00:00:00Z"
    },
    "filter": {
      "state": { "$eq": "TX" }
    },
    "sortBy": "startTime",
    "sortOrder": "desc",
    "pageSize": 100
  }
}

Response:

{
  "events": [
    {
      "id": "usgs-08167000",
      "name": "Guadalupe River at Comfort, TX",
      "startTime": "2026-07-12T14:00:00Z",
      "attributes": {
        "gageHeight": 12.4,
        "state": "TX"
      }
    }
  ],
  "routes": [],
  "assets": [],
  "pagination": {
    "nextPageToken": "eyJvZmZzZXQiOjEwMH0="
  }
}

get_feed_last_updated

Check when a data feed was last refreshed. Useful for verifying data freshness before querying a feed.

Inputs

• feedId (required): data feed identifier (e.g., "USGS_Water_Services", "AWC_METARS_BATCH")

Returns

• feedId
• updatedAt: timestamp of the last data update
• lastRunAt: timestamp of the last feed run

Example

Call:

{
  "tool": "get_feed_last_updated",
  "arguments": {
    "feedId": "USGS_Water_Services"
  }
}

Response:

{
  "feedId": "USGS_Water_Services",
  "updatedAt": "2026-07-14T09:45:00Z",
  "lastRunAt": "2026-07-14T09:40:00Z"
}

get_feed_count

Get the total number of items in a data feed. Useful for gauging feed size before querying, or checking whether a feed has any data.

Inputs

• feedId (required): data feed identifier (e.g., "USGS_Water_Services", "SEVERE_WEATHER_EVENTS")

Returns

• feedId
• count: total number of items in the feed

Example

Call:

{
  "tool": "get_feed_count",
  "arguments": {
    "feedId": "USGS_Water_Services"
  }
}

Response:

{
  "feedId": "USGS_Water_Services",
  "count": 11482
}