Skip to main content
Glama
nfip-mcp-server

nfip-mcp-server

by pgang002

nfip-mcp-server

CI License: MIT Python 3.10+

An MCP (Model Context Protocol) server exposing real US flood insurance claims data — sourced live from FEMA's public OpenFEMA API — as tools an AI agent can call: claim lookup, filtered search, aggregate stats, and flood event summaries.

Why this exists

Built as a hands-on project to learn MCP server design against a real, non-trivial dataset rather than mock data — the same pattern used to expose proprietary data (claims, policies, internal knowledge bases) to enterprise AI agents.

  • Real data — pulled directly from FEMA's OpenFEMA API, no key required, redacted for privacy, no PII.

  • Tested — unit tests against the query layer, integration tests against the real server subprocess, CI running both on every push.

  • Deployable — pip-installable package, Dockerfile included.

Related MCP server: fema-nfhl-mcp

Available Tools

Tool

Description

get_claim

Look up a single flood claim by its unique ID

search_claims

Filtered search by state, flood event, minimum building payment, and/or year

claims_summary

Aggregate stats (count, total/average payments, year range), optionally by state

list_flood_events

Distinct named flood events in the data with claim counts

Architecture

nfip-mcp-server/
├── src/nfip_mcp/
│   ├── db.py          ← pure query functions (no MCP dependency, easy to unit test)
│   └── server.py       ← FastMCP tool wrappers around db.py, entry point
├── data/
│   ├── nfip_raw.json   ← real claims data pulled from the OpenFEMA API
│   └── claims.db        ← SQLite database built from the raw data
├── scripts/
│   ├── build_db.py      ← loads nfip_raw.json into claims.db
│   ├── fetch_more_data.py ← pulls a larger, filtered dataset from the live API
│   └── demo_client.py    ← manual walkthrough of every tool
├── tests/
│   ├── test_db.py        ← unit tests against the query layer
│   └── test_integration.py ← spins up the real server and calls it over stdio
└── .github/workflows/ci.yml

The query logic in db.py is deliberately free of any MCP-specific code — it's plain functions taking a sqlite3.Connection and returning dicts, so it's testable without spinning up a server or client. server.py just wires thin @mcp.tool() wrappers around it.

Setup

git clone https://github.com/YOUR-USERNAME/nfip-mcp-server
cd nfip-mcp-server
pip install -e ".[dev]"
python scripts/build_db.py

Running the tests

pytest tests/                # everything
pytest tests/test_db.py      # fast unit tests only
pytest -m integration        # slower, spins up the real server subprocess

Running the server

nfip-mcp-server               # after pip install, runs over stdio
# or
python -m nfip_mcp.server

To see it working interactively without a full MCP host installed:

python scripts/demo_client.py

Connecting to Claude Desktop (or another MCP host)

Add to your MCP host's config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "nfip-claims": {
      "command": "nfip-mcp-server"
    }
  }
}

Running with Docker

docker build -t nfip-mcp-server .
docker run -i nfip-mcp-server

Point your MCP host's command at docker run -i nfip-mcp-server to use the containerized version instead.

Scaling up the data

The bundled data/claims.db has a small (~24 record) real sample, enough to prove the pipeline end to end. To pull a much larger, properly filtered slice of the real data (this defaults to flood-prone Northeast states):

python scripts/fetch_more_data.py
python scripts/build_db.py

License

MIT — see LICENSE.

Available Tools

4 tools
claims_summaryA

Get aggregate statistics across claims, optionally filtered to one state.

Args: state: Two-letter US state code to filter by. Omit for all states.

Returns: Claim count, total and average building payments, and the earliest/latest loss years in scope.

Inputs: state.

get_claimA

Look up a single NFIP flood claim by its unique claim ID.

Args: claim_id: The claim's unique identifier (UUID string).

Returns: The full claim record, or an error message if not found.

Inputs: claim_id (required).

list_flood_eventsA

List the distinct named flood events present in the claims data (e.g. 'Hurricane Katrina', 'Tropical Storm Allison'), with claim counts.

Returns: A dict mapping each flood event name to its claim count.

Inputs: no named parameters.

search_claimsA

Search NFIP flood claims with optional filters. All filters are combined with AND; omit any filter you don't need.

Args: state: Two-letter US state code, e.g. 'FL', 'NJ'. flood_event: Substring match against the named flood event, e.g. 'Katrina' matches 'Hurricane Katrina'. min_building_payment: Only return claims where the net building payment was at least this amount. year: Year the loss occurred. limit: Max number of results to return (default 10).

Returns: A dict with the matching claims and how many were found.

Inputs: year, limit, state, flood_event, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing flood events, retrieving a single claim, searching claims by filters, and producing aggregate statistics. There is minimal overlap in functionality, and descriptions make the boundaries obvious.

    Naming Consistency4/5

    Three tools follow a consistent verb_noun pattern: list_flood_events, get_claim, and search_claims. claims_summary breaks the pattern by using a noun phrase, though it is still clear and readable.

    Tool Count5/5

    Four tools is a well-scoped size for a read-only NFIP claims data server. Each tool covers a distinct query need without redundancy or bloat.

    Completeness4/5

    The surface covers the core read-only workflows: enumeration, single-record lookup, filtered search, and aggregate statistics. Minor gaps exist, such as summary filtering by flood event or year, but these do not create dead ends for common use cases.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that gives AI assistants direct access to the FEMA National Flood Hazard Layer (NFHL) for flood zone lookups, FIRM panel information, and flood map data in the United States.
      6
      9 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that gives AI agents grounded access to US natural-hazard data — weather alerts, forecasts, earthquakes, and FEMA flood zones — from free, keyless US government APIs.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Remote MCP server exposing US Census (ACS 5-year) and FEMA flood data. Works as a connector in both Claude and ChatGPT.
      -