fema-mcp-server

<div align="center">
  <h1>@cyanheads/fema-mcp-server</h1>
  <p><b>Query FEMA disaster declarations, public assistance grants, housing aid, and NFIP flood insurance claims via MCP. STDIO or Streamable HTTP.</b>
  <div>8 Tools • 1 Opt-in Tool • 1 Resource</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.4.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/fema-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/fema-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/fema-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/fema-mcp-server/releases/latest/download/fema-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=fema-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmVtYS1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22fema-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Ffema-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://fema.caseyjhand.com/mcp](https://fema.caseyjhand.com/mcp)

</div>

---

## Overview

Federal disaster recovery data from FEMA: disaster declarations, public assistance grants, individual housing assistance, and NFIP flood insurance claims. Search declarations by state or incident, see the public and housing assistance behind any disaster, and run SQL over large flood-claim result sets.

### Tools

| Tool | Description |
|:---|:---|
| `fema_search_disasters` | Search federal disaster declarations by state, incident type, declaration type, date range, and county |
| `fema_get_disaster` | Fetch up to 1,000 designated-area records for a specific disaster, with partial-coverage disclosure |
| `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 and inspection counts by county/ZIP, filterable by county or 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 opt-in: it appears in `tools/list` only when `FEMA_ENABLE_CANVAS_DROP=true`. The other eight tools are always listed.

### 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 designated-area detail (up to 1,000 rows).

## Capability reference

### `fema_search_disasters` <sub>tool</sub>

- Filters: `state`, `incident_type`, `declaration_type` (`DR`/`EM`/`FM`), inclusive `date_from`/`date_to` (`YYYY-MM-DD`), and `county`. `incident_type` and `county` are case-insensitive substring matches. Page with `limit` (1–1000, default 50) and `offset`; a page stops at 100,000 characters and `next_offset` says where to resume.
- Returns one summary per disaster number with `designated_area_count`, program flags, and declaration totals. With `county`, `total_area_rows` and `matched_areas` (FIPS codes and per-area flags) show the matching areas. Errors: `invalid_state`, `invalid_range` (`date_from` after `date_to`), `request_too_long`.
- Searches the most recent 10,000 designated-area rows. When capped, results are marked `truncated`, totals are lower bounds, and `notice` names the next `date_to`.

---

### `fema_get_disaster` <sub>tool</sub>

- Requires `disaster_number` from `fema_search_disasters`.
- Returns up to 1,000 designated-area records, FIPS codes, incident period, and program flags combined across fetched areas; a missing disaster returns `not_found`. When more rows exist, `areas_truncated`, `total_designated_area_count`, and `notice` disclose partial coverage. False flags do not exclude programs in unfetched rows; use `fema_query_dataset` for the full declaration.

---

### `fema_get_public_assistance` <sub>tool</sub>

- Requires `disaster_number` or `state`; optional `county` (case-insensitive substring), `limit` (1–10000, default 100), and `offset`. A page stops at 100,000 characters; `next_offset` says where to resume.
- Returns applicants, damage categories, project size/status, and federal and total obligations. Errors: `invalid_state`, `missing_filter`, `not_found`, `request_too_long`.

---

### `fema_get_housing_assistance` <sub>tool</sub>

- Requires `disaster_number`; optional `state`, `county` (case-insensitive substring), `zip_code` (5 digits), `type` (`owners`/`renters`/`both`, default `both`), `limit` (1–10000, default 100), and `offset`. A page stops at 100,000 characters; one `next_offset` continues both owners and renters.
- Returns separate `owners` and `renters` arrays with county/ZIP registrations, approved amounts, and inspection counts, plus `owners_count`/`renters_count`. Owners also carry inspected damage in USD; renters carry damage-degree counts only. Errors: `invalid_state`, `not_found`, `request_too_long`.

---

### `fema_search_nfip` <sub>tool</sub>

- Requires `state`; optional `county_code` (5-digit FIPS like `48201`, or a 3-digit code like `201` that gets the state prefix), `zip_code`, `year_from`/`year_to`, `limit` (1–10000, default 1000), and `offset`. Results come newest loss first.
- Inline claims stop at 100,000 characters; `next_offset` and `notice` say how to continue. Errors: `invalid_state`, `invalid_county_code` (anything but 1–5 digits, or a short code for FM, MH, or PW), `invalid_range` (`year_from` after `year_to`).
- County searches check for claims without a county code across the same state/year range, using one count-only exchange with no retries and a two-second deadline. The response uses the count only if ready with the primary page; otherwise it says coverage was not checked. These claims cannot be allocated to the selected county or ZIP. Removing `county_code` and optionally searching known ZIPs may help; ZIP results are not guaranteed complete or equivalent to a county.
- With `CANVAS_PROVIDER_TYPE=duckdb`, a first-page match over the inline limit stages up to 50,000 rows. `canvas_id`, `canvas_table`, and `staged_count` identify the stage, `truncated: true` marks its cap, and `total_count` is the full match. Inspect it with `fema_dataframe_describe`, then query it with `fema_dataframe_query`.

---

### `fema_dataframe_describe` <sub>tool</sub>

- Requires `canvas_id` from `fema_search_nfip`.
- Lists table/view names, column types, nullability, and staged row counts. Typed errors: `canvas_not_found`, `canvas_unavailable`.

---

### `fema_dataframe_query` <sub>tool</sub>

- Requires `canvas_id` and a single SQL `query`; only SELECT is allowed.
- Rows are capped at the canvas row limit and 100,000 characters; `truncated`/`shown` and OFFSET guidance appear when the result is cut. Errors: `canvas_unavailable`, `canvas_not_found`, `missing_table`, `invalid_sql`, `non_select_statement`, `multi_statement`, `denied_function`, `plan_operator_not_allowed`, `sql_read_only`, `sql_execution_error` (use `TRY_CAST` or filter incompatible values).

---

### `fema_dataframe_drop` <sub>tool</sub>

- Requires `canvas_id` and the exact `table_name` from `fema_dataframe_describe`.
- Removes one staged table or view; `dropped: false` means the name did not exist. Errors: `canvas_not_found`, `canvas_unavailable`.
- Opt-in through `FEMA_ENABLE_CANVAS_DROP=true`.

---

### `fema_query_dataset` <sub>tool</sub>

- Requires a case-sensitive OpenFEMA `dataset`; optional OData `filter`/`select`/`orderby`, `limit` (1–10000, default 100), and `offset`. A page stops at 100,000 characters; `next_offset` says where to resume.
- Returns records and `total_count`. Errors: `unknown_dataset`, `dataset_not_served`, `catalog_unavailable` (retryable), `invalid_filter`, `invalid_select`, `invalid_orderby`, `invalid_odata_syntax`, `request_too_long` (URL past about 8,900 characters), `filter_too_complex` (nested more than 100 levels).
- For a list of values, use `field in ('a','b')` instead of chained `or` comparisons (about 90 allowed). For `NfipPolicies`, use `propertyState` and `reportedZipCode`, and always include a ZIP filter to avoid timeout.

---

### `fem