Skip to main content
Glama

HeatShield: Geospatial MCP Agent

HeatShield is an AI-powered urban heat wave safety assistant designed to demonstrate the power of the Model Context Protocol (MCP) in grounding LLM agents with reliable, deterministic geospatial data.

The Problem with LLM "Freehanding" Spatial Data

When tasked with geospatial routing, weather analysis, or urban heat island (UHI) mapping, native LLMs suffer from severe hallucinations. They invent streets that don't exist, guess walking distances, and fabricate localized temperatures.

HeatShield solves this by entirely decoupling the intelligence layer from the data layer via MCP. Instead of the LLM generating markdown tables or estimating distances, it acts purely as a reasoning engine that orchestrates exact tool calls to deterministic APIs.

Related MCP server: OpenStreetMap MCP Server

Architecture & MCP Implementation

The core of HeatShield is an architecture where the LLM is tightly constrained to use server-side tools. The UI is designed for rapid prototyping, but the true value lies in the backend tool implementation.

Key MCP Tools Built for this Agent:

  • geocode_location: Resolves human-readable addresses to exact lat/lon coordinates via Nominatim.

  • find_cooling_spots: Queries the Overpass API for real-world infrastructure (parks, water fountains, cooling centers) based on the user's localized coordinates.

  • get_walking_route: Uses OSRM to calculate true walking distances and times, preventing the LLM from relying on "crow-flies" haversine estimations.

  • generate_walkability_isochrone: Generates an exact 15-minute reachable area polygon (GeoJSON).

  • get_urban_heat_island_heatmap: Pulls UHI surface temperature data to render deterministic heat blobs on the map.

  • get_occupational_heat_guidance: Calculates CDC/NIOSH work/rest cycles based strictly on current local wet-bulb globe temperature (WBGT) data.

How it Works

  1. User asks a question (e.g. "Find a cool place nearby").

  2. LLM reasons and calls tools. It executes find_cooling_spots passing the user's localized coordinates.

  3. MCP Server executes the query, fetching deterministic JSON data from Overpass.

  4. FastAPI intercepts the JSON payload. Instead of letting the LLM hallucinate prose about the data, FastAPI intercepts the structured GeoJSON and streams it directly to the React frontend.

  5. React Frontend renders natively. The UI renders the map pins and walking routes using standard Leaflet/React layers, bypassing LLM generation completely.

This architecture ensures that a user never receives a hallucinated safety route during an extreme weather event.

Tech Stack

  • Backend: FastAPI (Python), Model Context Protocol (MCP), Uvicorn, SQLite/DuckDB (Spatial Caching).

  • Frontend: React, Vite, React-Leaflet.

  • External Integrations: Overpass API, Open-Meteo, OSRM.

Setup & Running Locally

  1. Clone the repository.

  2. Install Python dependencies: uv sync

  3. Install Frontend dependencies: cd frontend && npm install

  4. Start the backend: uv run uvicorn api:app --reload

  5. Start the frontend: cd frontend && npm run dev

Available Tools

6 tools
find_cooling_spotsA

Use spatial analytics to find nearby cooling shelters (parks, pools, libraries, fountains). Requires latitude, longitude, and an optional radius in meters.

Inputs: latitude (required), longitude (required), radius. Returns: result

geocode_locationA

Get the latitude and longitude for a city, address, or location. Always use this tool first if you only have a city name and need coordinates for the other tools.

Args: query: The name of the city or location (e.g., "Karlsruhe, Germany")

Inputs: query (required). Returns: result

get_air_qualityA

Fetch live air quality data (PM2.5, PM10, AQI) to assess respiratory safety during heat waves. Requires latitude and longitude.

Inputs: latitude (required), longitude (required). Returns: result

get_heat_safety_adviceA

Get WHO/CDC safety recommendations based on the current heat risk level and the user's activity.

Args: heat_risk_level: Must be LOW, MODERATE, HIGH, or EXTREME (obtained from get_weather_and_heat_risk) activity_type: e.g., "jogging", "construction work", "elderly care", "general"

Inputs: activity_type (required), heat_risk_level (required). Returns: result

get_heatwave_forecastB

Fetches a 7-day weather forecast and calculates a Climate Aggravation Risk by correlating high temperatures with drought/soil moisture conditions. Use this to predict upcoming heatwaves and warn the user.

Inputs: latitude (required), longitude (required), days. Returns: result

get_weather_and_heat_riskB

Fetch live weather data (temperature, humidity, UV index) and a calculated WHO/CDC heat risk level. Requires latitude and longitude.

Inputs: latitude (required), longitude (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct function: geocoding, current heat risk, air quality, cooling spots, safety advice, and heatwave forecast. There is no overlap that would confuse an agent's selection.

    Naming Consistency5/5

    All tools follow a clear verb_noun pattern (geocode_location, get_weather_and_heat_risk, get_air_quality, find_cooling_spots, get_heat_safety_advice, get_heatwave_forecast). The verbs (geocode, get, find) are appropriate and consistently placed.

    Tool Count5/5

    With 6 tools, the server is well-scoped for a heat health domain. Each tool provides essential functionality without redundancy or bloat, making the set easy to navigate.

    Completeness5/5

    The tool set covers the full user workflow: location to coordinates, current heat risk, air quality, cooling shelter discovery, safety advice, and upcoming heatwave prediction. No obvious gaps exist for typical heat safety use cases.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to fetch real-time weather data for any location using the OpenWeatherMap API. Demonstrates how to build a simple MCP server that exposes weather information as a tool for LLMs.
      1
      GPL 3.0
    • A
      license
      B
      quality
      D
      maintenance
      A comprehensive MCP server providing 30 tools for geocoding, routing, and OpenStreetMap data analysis. It enables AI assistants to search for locations, calculate travel routes, and perform quality assurance checks on map data.
      30
      972 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to call weather tools, read resources, and use prompt templates for live weather data integration.
      2,530 npm
      MIT