HeatShield
The HeatShield server provides geospatial and environmental tools to help users stay safe during heat waves. It can:
Geocode locations (
geocode_location): Convert addresses or city names into precise coordinates.Get live weather & heat risk (
get_weather_and_heat_risk): Fetch temperature, humidity, UV index, and a WHO/CDC-based heat risk level (LOW to EXTREME).Check air quality (
get_air_quality): Retrieve PM2.5, PM10, and AQI to assess respiratory safety.Find cooling spots (
find_cooling_spots): Locate nearby parks, pools, libraries, and fountains within a radius.Get heat safety advice (
get_heat_safety_advice): Receive tailored recommendations based on heat risk and activity type.Get heatwave forecast (
get_heatwave_forecast): Obtain a 7-day forecast with climate aggravation risk to predict upcoming heatwaves.
Provides tools for geocoding locations and finding cooling spots such as parks, pools, fountains, and libraries using OpenStreetMap data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HeatShield Find cooling spots and heat safety advice for downtown Miami"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
User asks a question (e.g. "Find a cool place nearby").
LLM reasons and calls tools. It executes
find_cooling_spotspassing the user's localized coordinates.MCP Server executes the query, fetching deterministic JSON data from Overpass.
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.
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
Clone the repository.
Install Python dependencies:
uv syncInstall Frontend dependencies:
cd frontend && npm installStart the backend:
uv run uvicorn api:app --reloadStart the frontend:
cd frontend && npm run dev
Available Tools
6 toolsfind_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
The Google Maps MCP server is a fully-managed server provided by the Maps Grounding Lite API that connects AI applications to Google Maps Platform services. It provides three main tools for building LLM applications: searching for places, looking up weather information, and computing routes with details like distance and travel time. The server acts as a proxy that translates Google Maps data into a format that AI applications can understand, enabling agents to accurately answer real-world location and travel queries.
AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.1GPL 3.0
- AlicenseBqualityDmaintenanceA 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.30972 npm6MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to call weather tools, read resources, and use prompt templates for live weather data integration.2,530 npmMIT
- AlicenseAqualityDmaintenanceAn OpenStreetMap MCP server that provides location-based services including geocoding, route directions, points of interest search, and neighborhood analysis to enhance LLMs with geospatial capabilities.121MIT