@cyanheads/fema-mcp-server

v0.3.1

Published

9 days ago

Query FEMA disaster declarations, public assistance grants, housing aid, and NFIP flood insurance claims via MCP. STDIO or Streamable HTTP.

Public Hosted Server: https://fema.caseyjhand.com/mcp

Overview

Federal disaster recovery data from FEMA's OpenFEMA API — disaster declarations, public assistance grants, individual housing assistance, and NFIP flood insurance claims. Search declarations by state or incident, drill into public assistance and housing assistance by disaster number, and run SQL analytics over large NFIP result sets via DataCanvas. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

| Tool | Description | |:---|:---| | fema_search_disasters | Search federal disaster declarations by state, incident type, declaration type, date range, and county | | fema_get_disaster | Fetch all designated-area records for a specific disaster by disaster number | | fema_get_public_assistance | Public assistance funded projects for a disaster or state — where federal recovery money went | | fema_get_housing_assistance | Individual assistance housing data for a disaster — owner and renter breakdowns by county/ZIP | | fema_search_nfip | NFIP flood insurance claims for a state, county, or ZIP, with optional DataCanvas spillover for SQL analytics | | fema_dataframe_describe | List columns and row counts for DataCanvas tables staged by fema_search_nfip | | fema_dataframe_query | Run a SELECT query against a DataCanvas table staged by fema_search_nfip | | fema_dataframe_drop | Remove a staged DataCanvas table or view — opt-in, absent from tools/list by default | | fema_query_dataset | Generic OData query against any dataset in the OpenFEMA catalog — escape hatch for datasets the convenience tools don't cover |

fema_dataframe_drop is registered only when FEMA_ENABLE_CANVAS_DROP=true; the other eight tools are always advertised.

Resources

| Resource | Description | |:---|:---| | fema://disaster/{disasterNumber} | Summary for a specific FEMA disaster declaration — title, state, incident type, programs, incident period |

All resource data is also reachable via tools. Use fema_get_disaster for the same data with pagination and full designated-area detail.

Capability reference

`fema_search_disasters` tool

Filters: state (2-letter code), incident_type (substring match), declaration_type (DR/EM/FM), date_from/date_to (inclusive declaration date range, calendar dates in YYYY-MM-DD form — anything else is rejected before a request is made), county (substring); paginated via limit (1–1000, default 50) / offset
Returns deduplicated declaration-level summaries — one row per unique disaster number, with designated_area_count and program flags (ia_declared/pa_declared/hm_declared)
Deduplicates the most recent 10,000 designated-area rows before paging. When total_area_rows exceeds 10,000, it drops the declarations dated on the oldest day in that window, so every returned declaration is complete; the response sets truncated: true, words its declaration totals as lower bounds, and its notice names the date_to (YYYY-MM-DD) that continues with older declarations
An offset at or past the last matching declaration returns an empty page with the totals and a notice naming the last valid offset (plus the date_to continuation when truncated)
Typed errors: invalid_state, no_results (nothing matches the filters)

`fema_get_disaster` tool

Input: disaster_number (positive integer), obtained from fema_search_disasters
Returns every designated county/municipality row for the declaration, with FIPS codes, incident period, and program flags OR'd across all areas
Disaster numbers above 32767 (OpenFEMA's Int16 field limit) return not_found rather than a raw API type-mismatch error

`fema_get_public_assistance` tool

Requires disaster_number or state — at least one; optional county substring filter; paginated via limit (1–1000, default 100) / offset
Returns applicant, damage category, project size/status, federal share obligated, and total obligated per project
An offset at or past the last matching project returns an empty page with the total and a notice naming the last valid offset
Typed errors: invalid_state, missing_filter (neither disaster_number nor state given), not_found (disaster number above 32767, OpenFEMA's Int16 field limit — rejected before any request, same as fema_get_disaster), no_results (nothing matches the filters)

`fema_get_housing_assistance` tool

Input: disaster_number (required), optional state filter, type (owners/renters/both, default both); paginated via limit (1–1000, default 100) / offset
Returns separate owners and renters arrays — registrations, approved amounts, and repair/rental/other-needs breakdowns by county and ZIP — plus owners_count/renters_count totals, both stated on every response
An offset at or past the end of a queried dataset returns that dataset's empty page with its total and a notice naming its last valid offset
Typed errors: invalid_state, not_found (disaster number above 32767, OpenFEMA's Int16 field limit — rejected before any request, same as fema_get_disaster), no_results (no records for the disaster — IA housing data can take weeks to appear after a declaration)

`fema_search_nfip` tool

Reads OpenFEMA's NfipClaims v3 dataset (NFIP redacted claims)
state is required — the unfiltered NFIP Claims dataset is 2.7M rows; optional county_code (5-digit FIPS or a bare 3-digit code, auto-prefixed with the state FIPS), zip_code, year_from/year_to; paginated via limit (1–10000, default 1000) / offset
Claims come newest date of loss first, with claim ID breaking ties, so offset pages never repeat or skip a claim. An inline page also stops at 100,000 characters of claims (about 330 claims); whenever claims are left out, a notice names the offset to continue from
cause_of_damage and occupancy_type carry OpenFEMA's published codes unchanged; the output schema lists what each code means
When CANVAS_PROVIDER_TYPE=duckdb is set and the match exceeds the inline budget, a call at offset 0 stages the whole match (up to 50,000 rows) on a DataCanvas table. The response carries canvas_id, canvas_table, and staged_count, and its notice points to fema_dataframe_describe, then fema_dataframe_query; rows past the inline claims are read from that table. truncated: true marks a partial stage at the cap, where total_count still reports the full match. A match that fits inline never creates a canvas, and a call at a later offset returns its inline page without staging
An offset at or past the last matching claim returns an empty page with the total and a notice naming the last valid offset
Typed errors: invalid_state, no_results

`fema_dataframe_describe` tool

All four canvas inputs (fema_search_nfip, fema_dataframe_describe, fema_dataframe_query, and fema_dataframe_drop) require a server-issued 10-character URL-safe ID matching [A-Za-z0-9_-]{10} when supplied. Omit it on the first NFIP search.

Input: canvas_id from a fema_search_nfip response
Lists table/view names, DuckDB column types, and nullability; row count reflects what was actually staged, not the inline preview
Typed errors: canvas_not_found, canvas_unavailable (DataCanvas not enabled on this deployment)

`fema_dataframe_query` tool

Input: canvas_id plus a single SQL query; only SELECT statements are permitted — DDL, DML, COPY, and file-reading functions are blocked
Results are capped at the canvas row limit; a capped response sets truncated/shown/cap enrichment fields with LIMIT/OFFSET paging guidance
Typed errors: canvas_not_found, canvas_unavailable, invalid_query, sql_execution_error (use TRY_CAST or filter incompatible values)

`fema_dataframe_drop` tool

Opt-in: not registered (absent from tools/list) unless FEMA_ENABLE_CANVAS_DROP=true
Input: canvas_id and the exact table_name from fema_dataframe_describe
Removes one staged table or view only — never changes FEMA source data; dropped: false when the name doesn't exist
Typed errors: canvas_not_found, canvas_unavailable

`fema_query_dataset` tool

Input: dataset (case-sensitive OpenFEMA entity name), optional raw OData filter/select/orderby, limit (1–10000, default 100) / offset
Each dataset is queried at the API version the OpenFEMA dataset catalog lists for it (v1–v4, highest listed version wins); the catalog is cached in-process for 6 hours
Escape hatch for datasets the convenience tools don't cover (e.g. NfipPolicies, IndividualAssistanceHousingRegistrantsLargeDisasters, FemaWebDeclarationAreas); for NfipPolicies use propertyState (not state) and reportedZipCode — it has no countyCode — and always include a ZIP filter to avoid timeout
An empty page is a success with a notice: filter guidance when nothing matches (total_count 0), or the total and the last valid offset when offset is at or past the end of the matches
A dataset resolves by its webService path segment or its catalog name (OpenFemaDataSetFields or DataSetFields; DataSets or OpenFemaDataSets for the catalog itself)
Typed errors: unknown_dataset (name not in the catalog), dataset_not_served (listed in the catalog, but OpenFEMA serves no API endpoint for it), catalog_unavailable (catalog unreadable, retryable), invalid_filter / invalid_select / invalid_orderby (OpenFEMA rejected that parameter — the message names the field whenever OpenFEMA does), invalid_odata_syntax (unparseable, parameter not identified)

`fema://disaster/{disasterNumber}` resource

Params: disasterNumber as a string of digits
Returns title, state, incident type, declaration type/date, incident period, programs_declared array, and designated_area_count
Typed error: not_found for a malformed number (anything but digits), a number outside 1–32767 (neither reaches OpenFEMA), or a number with no declaration — with a recovery hint pointing to fema_search_disasters

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

OpenFEMA-specific:

Typed OpenFEMA REST client with %24-prefixed OData parameter encoding (an Akamai requirement), per-dataset API versions resolved from the OpenFEMA dataset catalog, and structured error classification distinguishing JSON 400 responses (by the failing filter/select/orderby clause) from HTML Drupal error pages
Automatic deduplication of DisasterDeclarationsSummaries — one row per designated area collapsed to declaration-level summaries with designated_area_count
NFIP Claims guard: state filter is required to prevent unbounded 2.7M-row fetches
DataCanvas spillover for NFIP analytics — large NFIP result sets materialize as DuckDB tables queryable via SQL without re-fetching
No API keys required — OpenFEMA is a free, public API

Agent-friendly output:

Disaster number is the explicit join key across all datasets — every tool that touches a disaster surfaces it prominently so agents can chain calls without re-searching
Typed error contracts on every tool — invalid_state, no_results, not_found, missing_filter, unknown_dataset, dataset_not_served, invalid_filter, invalid_select, invalid_orderby, invalid_odata_syntax, canvas_unavailable — with recovery hints telling agents the concrete next step
designated_area_count on search results so agents know whether to drill in with fema_get_disaster without having to fetch the full record first

Getting started

Public Hosted Instance

A public instance is available at https://fema.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "fema-mcp-server": {
      "type": "streamable-http",
      "url": "https://fema.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "fema-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fema-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "fema-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/fema-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "fema-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/fema-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

To enable DuckDB-backed SQL analytics for NFIP Claims:

{
  "mcpServers": {
    "fema-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/fema-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "CANVAS_PROVIDER_TYPE": "duckdb"
      }
    }
  }
}

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
No API keys required — OpenFEMA is a free, public API.
Optional: set CANVAS_PROVIDER_TYPE=duckdb to enable SQL analytics over large NFIP Claims result sets.

Installation

Clone the repository:

git clone https://github.com/cyanheads/fema-mcp-server.git

Navigate into the directory:

cd fema-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env — no required vars, but CANVAS_PROVIDER_TYPE=duckdb enables SQL analytics

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

| Variable | Description | Default | |:---------|:------------|:--------| | FEMA_BASE_URL | Override the OpenFEMA API root. Each dataset's version is appended per request; a trailing /v<N> segment is ignored. | https://www.fema.gov/api/open | | FEMA_REQUEST_TIMEOUT_MS | Total budget in milliseconds for one upstream exchange, including response body, retries, and backoff. NFIP county queries can be slow. | 30000 | | CANVAS_PROVIDER_TYPE | Set to duckdb to enable DataCanvas for NFIP Claims analytics. Without it, fema_search_nfip returns inline pages only, paged by offset. | — | | FEMA_ENABLE_CANVAS_DROP | Enable the destructive fema_dataframe_drop tool for removing staged tables and views. | false | | MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio | | MCP_SESSION_MODE | Session mode: auto, stateful, or stateless. Overrides this server's explicit stateless default. The framework schema default auto resolves to stateful. | stateless | | MCP_HTTP_PORT | HTTP server port. | 3010 | | MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none | | MCP_LOG_LEVEL | Log level (debug, info, warning, error, etc.). | info | | LOGS_DIR | Directory for log files (Node.js only). | <project-root>/logs | | OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |

See .env.example for the full list of optional overrides.

Running the server

Local development

Build and run:

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t fema-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio fema-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/fema-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. Production dependencies, including the DuckDB native binding, are installed directly in the runtime stage without lifecycle scripts.

Project structure

| Directory | Purpose | |:----------|:--------| | src/index.ts | createApp() entry point — registers tools/resources and inits services. | | src/config | Server-specific environment variable parsing and validation with Zod. | | src/mcp-server/tools | Tool definitions (*.tool.ts) — one file per tool. | | src/mcp-server/resources | Resource definitions (*.resource.ts). | | src/services/openfema | OpenFEMA REST API client — OData param builder, response parser, error classifier, retry wrapper. | | src/services/canvas | DataCanvas integration — DuckDB spillover for large NFIP result sets. | | tests/ | Unit and integration tests mirroring src/. |

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools and resources in src/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

Data source

Data is provided by the OpenFEMA API, a free public API maintained by the Federal Emergency Management Agency. Usage is subject to OpenFEMA Terms and Conditions.

This product uses the Federal Emergency Management Agency's OpenFEMA API, but is not endorsed by FEMA. The Federal Government or FEMA cannot vouch for the data or analyses derived from these data after the data have been retrieved from the Agency's website(s).

When citing OpenFEMA datasets in research or publications, use the format FEMA specifies:

Federal Emergency Management Agency (FEMA), OpenFEMA Dataset: <name>. Retrieved from <URL> on <date>.

License

Apache-2.0 — see LICENSE for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme