AI agents¶

IdroGEO's data answers questions people actually ask: is my town in a flood zone? How many landslides are there in this valley? Is anyone watching the one above the road? idrogeo-mcp lets an AI agent answer them from the source, with numbers it can cite, instead of from memory.

The MCP server¶

pip install "ispra-idrogeo[mcp]"

idrogeo-mcp is an MCP server, so Claude Desktop, an IDE or your own agent can answer questions like "how many people live in high landslide hazard areas in Sarno, and is anyone monitoring the landslides there?" or "is this address in a flood zone?". For Claude Desktop, add it to claude_desktop_config.json:

{
  "mcpServers": {
    "idrogeo": { "command": "idrogeo-mcp" }
  }
}

As an always-on service, for an agent that talks HTTP (for example mcp-geo-server's chat and map), serve it over streamable HTTP at /mcp:

idrogeo-mcp --transport streamable-http --host 0.0.0.0 --port 8767

Every option also reads an environment variable, so a compose file needs no command line, and GET /health answers {"status": "ok"}:

services:
  idrogeo-mcp:
    image: ghcr.io/astral-sh/uv:python3.12-bookworm-slim
    command: uvx --from "ispra-idrogeo[mcp]>=0.6" idrogeo-mcp
    environment:
      IDROGEO_MCP_TRANSPORT: streamable-http
      IDROGEO_MCP_HOST: 0.0.0.0
      IDROGEO_MCP_PORT: "8767"
      IDROGEO_DATA_DIR: /data/idrogeo  # for download_dataset
    volumes:
      - idrogeo-data:/data/idrogeo
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8767/health')"]

On 127.0.0.1 the SDK refuses requests with a foreign Host header (DNS rebinding protection); on 0.0.0.0 it does not, unless you list the names clients use: IDROGEO_MCP_ALLOWED_HOSTS=idrogeo-mcp:*,localhost:*.

Tool	What the agent gets
`hazard_at`	Landslide and flood hazard, municipality and slope of a point
`landslides_near`	The landslides around a point, nearest first
`find_area`	The ISTAT code of a region, province or municipality from its name
`area_risk`	Hazard and exposure: residents, buildings, heritage per hazard class
`area_landslides`	IFFI counts by type of movement, events, monitoring
`landslide`	One landslide in full, codes decoded
`search_landslides` / `search_events`	Landslides by type and activity; events by area and date
`monitoring_sites` / `webcams`	Who is watching, with which instruments
`rank_areas`	The top (or bottom) regions, provinces or municipalities by any indicator, optionally inside a region or province
`compare_areas`	Up to 20 areas side by side, so the agent does not do arithmetic in its head
`code_list`	Any code list, in four languages
`download_dataset`	A layer downloaded (only if changed) to the local folder
`warehouse_schema` / `warehouse_sql`	The tables of the local warehouse, and one read-only SQL query on them

Names are matched without accents or apostrophes (forli finds Forlì), and a name that matches nothing comes back with "did you mean" suggestions.

Resource	What it holds
`idrogeo://indicators`	What `popfrp3p4p`, `pop_idr_p2` and the other indicator keys mean
`idrogeo://datasets`	The layers, mosaics and area names `download_dataset` accepts
`idrogeo://codes/{name}`	One code list, in English

Two prompts, area_profile and recent_events, give a client ready-made questions ("a risk profile of Sarno", "landslide events in Liguria since October") that use the tools the right way and credit the source.

Every tool but download_dataset only reads. Searches stop at limit rows (100 by default, 1,000 at most), so an agent never receives 700,000 landslides at once, and IdroGEO's refusals come back as readable errors. rank_areas keeps the summaries it reads on disk for 30 days: the first national ranking of municipalities asks IdroGEO 7,899 times (a few minutes), a region's ranking a few hundred.

How an agent uses it¶

A typical question takes three or four tool calls. The agent turns a name into an ISTAT code, then reads the figures for that code:

sequenceDiagram
    autonumber
    participant U as You
    participant A as AI agent
    participant M as idrogeo-mcp
    participant I as IdroGEO API

    U->>A: "How many people live in high landslide hazard in Sarno?"
    A->>M: find_area("Sarno")
    M->>I: list of municipalities (once, then kept)
    M-->>A: [{"code": …, "name": "Sarno", "level": "comuni"}]
    A->>M: area_risk("comuni", code)
    M->>I: PIR indicators of that municipality
    M-->>A: residents per hazard class P1–P4, AA
    A->>M: monitoring_sites(municipality=code)
    M-->>A: sites, instruments, landslides watched
    A-->>U: answer, figures, "Source: ISPRA — IdroGEO"

Other clients¶

The server speaks MCP over stdio, so any MCP client can start it.

Claude CodeClaude DesktopWithout installing (uvx)

claude mcp add idrogeo -- idrogeo-mcp

{
  "mcpServers": {
    "idrogeo": { "command": "idrogeo-mcp" }
  }
}

{
  "mcpServers": {
    "idrogeo": {
      "command": "uvx",
      "args": ["--from", "ispra-idrogeo[mcp]", "idrogeo-mcp"]
    }
  }
}

Questions to try¶

Which province of Liguria has the largest share of residents in flood hazard P3?
Which landslide monitoring sites are active in the province of Belluno, and with which instruments?
Compare landslide hazard exposure (P3 + P4) of Sarno, Ischia and Casamicciola Terme.
What do the movement codes 1, 2 and 6 mean, in Italian and in English?
Download the Molise landslide points and tell me where the folder is.

Answers are information, not a safety assessment

PAI hazard maps and the IFFI inventory are official, but an agent's summary of them is not. For decisions about a building, a site or an emergency, refer to the competent basin authority, region or civil protection service.

For coding assistants: `llms.txt`¶

This site publishes llms.txt, a short plain-text guide to the library for AI coding assistants: what to call, in which order, and the traps to avoid. Point your assistant at https://agentengineering.it/ispra-idrogeo/llms.txt.