io.github.qinisolabs/floodwise

Official

by qinisolabs · TypeScript

England flood-risk by postcode for AI agents — verified Environment Agency data, not guesses.

Query England flood risk by postcode using verified Environment Agency data.

Topics

agentsenglandenvironment-agencyflood-riskinsurancellmmcpmodel-context-protocolpostcodetypescript

README.md5 KBView on GitHub

floodwise

England flood-risk by postcode for AI agents — verified Environment Agency data, not guesses.

Verified, trustworthy data tools for AI agents. "Qiniso" means "truth" in Zulu.

Website · npm · MCP Registry

</div>

Ask an LLM "what's the flood risk at SW1A 1AA?" and it will answer confidently — but it cannot know: per-postcode flood risk is specific, curated data that lives in a government dataset, not in a model's weights. floodwise looks the postcode up in the Environment Agency's official "Flood risk: postcode search tool" data and returns the real long-term risk band — or an honest "not found" instead of a guess.

⚠️ Read this first — what floodwise is and isn't

England only. The data is the Environment Agency's, which covers England. Wales (Natural Resources Wales), Scotland (SEPA) and Northern Ireland (DfI) are not covered. A valid Welsh/Scottish postcode returns "not found", never a guess.
Area-level, not property-level. The risk is for the area around the addresses in a postcode — not a specific building. The EA states this data is "generally not suitable for property level assessment".
Long-term risk, not a live warning. It reflects the long-term annual chance of flooding, not whether flooding is happening now or forecast. It is not insurance, underwriting, surveying or professional advice.

Add it to Claude

floodwise runs locally over stdio (no key, no login). Once it's on npm, add it under mcpServers in your client config:

json

{ "command": "npx", "args": ["-y", "floodwise"] }

Use it as a library

bash

npm i floodwise

import { floodRiskByPostcode, validatePostcode } from "floodwise";

floodRiskByPostcode("SW1A 1AA");
// {
//   postcode: "SW1A 1AA", found: true, headlineRisk: "Very Low",
//   addressesAtRisk: { high: 0, medium: 0, low: 0 }, groundwater: "Unlikely",
//   coverage: "England", dataset: "ea-official", ...
// }

floodRiskByPostcode("EH1 1AA").found;   // false — valid postcode, but Scotland (out of EA coverage), no guess
validatePostcode("ec1a1bb");            // { valid: true, postcode: "EC1A 1BB", outcode: "EC1A", incode: "1BB" }

Postcodes are accepted spaced or unspaced, any case. A well-formed postcode that isn't in the loaded England dataset returns found: false with a clear note — it never invents a risk level.

Tools — 2

Tool	What it answers
flood_risk_by_postcode	The EA long-term flood-risk band (High/Medium/Low/Very Low) for an England postcode, address counts per band, and the groundwater indication
validate_postcode	Is this a well-formed UK postcode? (deterministic format check + outcode/incode split)

Data

The flood data is the Environment Agency "Flood risk: postcode search tool data" (England), published as open data under the Open Government Licence v3.0. Each postcode carries the number of addresses whose surrounding area is at high (≥3.3%/yr), medium (1–3.3%) or low (0.1–1%) long-term risk from rivers, sea or surface water (the highest of these), plus a separate groundwater Possible/Unlikely indication. Refreshed roughly quarterly.

This repository ships an illustrative starter sample (non-geographic ZZ pseudo-postcodes) so tests run out of the box — every response from it is tagged dataset: "sample". To load the real data, download Postcodes_Risk_Assessment_All.csv from data.gov.uk / the Defra Data Services Platform and run:
bash
npm run build-data /path/to/Postcodes_Risk_Assessment_All.csv 2025-Q4
npm run build && npm test

Attribution: Contains public sector information licensed under the Open Government Licence v3.0. © Environment Agency copyright and/or database right. See NOTICE.

What it is not

Not advice. Not insurance, underwriting, surveying, mortgage or legal advice; not a property-level survey.
Not all flood types. Excludes flooding from highway drains, sewers and overland flow; groundwater is reported separately and isn't combined into the headline band.
Not the whole UK. England only (see above).
Not a guesser. Unknown/out-of-coverage postcodes return an honest "not found", never a fabricated risk level.

Architecture

A single TypeScript package exposing one MCP server over stdio (local / npx), driven by the same core.ts tool definitions that power the importable library. A Cloudflare Worker entry is included for a future hosted edge endpoint — note the full England dataset (~1.6M postcodes) exceeds the Worker bundle limit, so the hosted build will move the data into Cloudflare D1 (a follow-on); the npm library and stdio server run the full dataset directly.

bash

npm install
npm run build
npm test

Privacy

This tool runs locally on your machine and is built not to collect, store, or transmit your data — no analytics, no telemetry, no account. All reference data is bundled — no network calls, and nothing leaves your device. Full policy: https://qinisolabs.github.io/privacy.html.

License

Install

claude_desktop_config.json

{
  "mcpServers": {
    "floodwise": {
      "command": "npx",
      "args": [
        "-y",
        "floodwise@0.1.0"
      ]
    }
  }
}