Environment Agency Flood Monitoring MCP Server

A Model Context Protocol (MCP) server that provides access to the UK Environment Agency's Real Time Flood Monitoring API. This server allows you to access near real-time flood warnings, water level measurements, flow data, and monitoring station information.

🆕 What's new in 1.1.0

Migrated to the modern MCP SDK (@modelcontextprotocol/sdk 1.x), added Zod input validation (range, format, and cross-field checks), 30s request timeouts with actionable errors, id sanitization, and response capping (polygon omission, default/max limits, and 60 KB truncation) to protect the client's context window.

🌊 Features

• 🚨 Flood Warnings & Alerts: Get current flood warnings and alerts with severity levels
• 📍 Flood Areas: Access information about flood alert and warning areas
• 🏭 Monitoring Stations: Find water level and flow monitoring stations across the UK
• 📊 Real-time Measurements: Access water levels, flows, and other measurements updated every 15 minutes
• 📈 Historical Data: Retrieve historical readings and measurements
• 🗺️ Geographic Filtering: Filter data by location using latitude, longitude, and distance
• 🔓 No API Key Required: Uses open government data with no registration needed

📦 Installation

For Claude Desktop Users

Add this to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "environment-agency": {
      "command": "npx",
      "args": ["-y", "mcp-server-environment-agency"]
    }
  }
}

For Developers

npm install -g mcp-server-environment-agency

🛠️ Available Tools

Flood Warning Tools

• get_flood_warnings - Get current flood warnings and alerts
• get_flood_warning - Get details of a specific flood warning
• get_flood_areas - Get flood areas (regions where warnings may apply)
• get_flood_area - Get details of a specific flood area

Monitoring Station Tools

• get_monitoring_stations - Get monitoring stations that measure water levels, flows, etc.
• get_monitoring_station - Get detailed information about a specific monitoring station
• get_measures - Get measurement types available across all stations
• get_station_measures - Get all measurement types from a specific station

Reading Tools

• get_readings - Get measurement readings from all stations
• get_measure_readings - Get readings for a specific measurement type
• get_station_readings - Get all readings from a specific monitoring station

💬 Usage Examples

Get detailed information for station 1029TH (Bourton Dickler)
Find monitoring stations within 25km of Cambridge
Find monitoring stations in Yorkshire
Show me today's water level readings from any 5 stations

📊 Data Types

Flood Warning Severity Levels

1. Severe Flood Warning - Severe Flooding, Danger to Life
2. Flood Warning - Flooding is Expected, Immediate Action Required
3. Flood Alert - Flooding is Possible, Be Prepared
4. Warning no Longer in Force - The warning is no longer in force

Measurement Parameters

• Water Level (level) - Water levels at monitoring stations
• Flow (flow) - Water flow rates
• Temperature (temperature) - Air temperature
• Wind (wind) - Wind direction and speed

Station Types

• SingleLevel - Single water level measurement
• MultiTraceLevel - Multiple level measurements
• Coastal - Coastal monitoring stations
• Groundwater - Groundwater level monitoring
• Meteorological - Weather measurements

🚀 Development

Prerequisites

• Node.js 20+
• TypeScript

Setup

git clone https://github.com/dwain-barnes/mcp-server-environment-agency.git
cd mcp-server-environment-agency
npm install

Build

npm run build

Test

# Build and run the end-to-end smoke test (spawns the server over stdio,
# lists tools, exercises a live query, and checks id sanitization)
npm test

Local Development

# Link for local testing
npm link

# Test with Claude Desktop using local version

📄 Data Attribution

This server uses Environment Agency flood and river level data from the real-time data API (Beta), provided under the Open Government Licence.

🔄 API Updates and Reliability

• Data is updated every 15 minutes
• The API may redirect during high load - the client follows redirects automatically
• Responses may be cached for short periods
• No service level guarantee - not suitable for safety-critical applications

📋 Rate Limits and Best Practices

• For tracking all measurements, use a single call every 15 minutes
• Use geographic and parameter filters to reduce response sizes
• The API has built-in limits: default 500 items, maximum 10,000 for readings
• Use pagination with limit and offset parameters for large datasets

📉 Response Limits

To keep responses friendly to LLM context windows, this server shapes and caps API results:

• Default page size: 50 items for stations, measures and flood areas; 100 for readings (applied when you don't pass limit).
• Maximum limit: 500 for any list tool. The Environment Agency API itself allows more, but this server caps for context safety — use offset to paginate.
• Polygon geometry omitted: flood-area and flood-warning polygons are replaced with a short placeholder, as they are the single largest field in the API.
• 60 KB truncation: if a rendered response still exceeds ~60,000 characters, the items list is progressively truncated and a note explains how many items were omitted and which filters (county, river_name, town, or lat+long+dist) or pagination to use.
• Responses use a compact { meta, count, items } envelope with the API @context field stripped.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Environment Agency for providing open flood monitoring data
• Model Context Protocol team for the excellent framework
• UK Government for open data initiatives

Built by Dwain Barnes 🇬🇧