@cyanheads/fema-mcp-server
Query FEMA disaster declarations, public assistance grants, housing aid, and NFIP flood insurance claims via MCP. STDIO or Streamable HTTP.
8 Tools • 1 Opt-in Tool • 1 Resource • 1 Skill
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 staged PA projects, housing records, and flood claims.
Tools
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
All resource data is also reachable via tools. Use fema_get_disaster for designated-area detail (up to 1,000 rows).
Skills
Plugin installs pick up the root skills/ tree; MCP clients that support the Skills extension read it as skill://fema-guide/SKILL.md.
Capability reference
fema_search_disasters tool
- Filters:
title, state, incident_type, declaration_type (DR/EM/FM), inclusive date_from/date_to (YYYY-MM-DD), and county. title, incident_type, and county are case-insensitive substring matches. A title such as harvey also matches unrelated names such as HARVEYTOWN FIRE. 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.
County filters across declarations, housing, and PA recognize terminal County, Parish, Borough, and Census Area forms with or without parentheses (Harris County and Harris (County)). Recognized names use the stored counterpart spelling; unknown names retain exact/case fallbacks. Bare harris still matches Harrison; a suffixed name retains its type. IA flags combine legacy IA and IHP declarations; they do not guarantee housing records.
fema_get_disaster tool
- Requires
disaster_number from fema_search_disasters.
funding reports the IA approval count, IHP/HA/ONA approved dollars, PA and HMGP obligations, and IA/PA load dates from FemaWebDisasterSummaries. A null field means FEMA has no reported value. An absent summary or failed funding lookup gets a notice.
- Returns up to 1,000 designated-area records with FIPS codes and each area's
ia_declared, pa_declared, and hm_declared flags, 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 tool
- 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 applicant IDs and available names, project titles, damage categories, obligations, mitigation amounts, county FIPS, process steps, and obligation dates. Errors include
invalid_state, missing_filter, not_found, request_too_long, and canvas_not_found.
fema_get_housing_assistance tool
- 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.
- On the first page, both assistance tools stage the match when it exceeds the inline page and DataCanvas is enabled. PA stages one table. Housing stages one table per nonempty selected dataset. Pass an earlier
canvas_id to keep tables together. Read canvas_tables for each dataset’s table_name, staged_count, and truncated flag. Each table holds up to 50,000 records. Check truncated before treating a SQL aggregate as the total for the entire match. Inline next_offset still works.
- 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 include invalid_state, not_found, request_too_long, and canvas_not_found.
fema_search_nfip tool
- 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, exact-case flood_event (such as Hurricane Harvey), 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, loss-year range, and optional flood event, 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 DataCanvas on (the default), a first-page match over the character budget 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 tool
- Requires
canvas_id from an assistance or NFIP staging response.
- Lists table/view names, column types, nullability, and staged row counts. Typed errors:
canvas_not_found, canvas_unavailable.
fema_dataframe_query tool
- Requires
canvas_id and one read-only SQL query. Use SELECT to query staged data or SHOW <table> to inspect its schema. Constant range() and generate_series() can supply a series for gap-filling.
- 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 tool
- 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 tool
- 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.
fema://disaster/{disasterNumber} resource
- Requires
disasterNumber as a string of digits.
- Returns title, state, incident type, declaration type/date, incident period,
programs_declared, and fetched designated_area_count (up to 500). When more rows exist, the summary includes areas_truncated, total_designated_area_count, and notice: programs describe only fetched rows, and an empty list does not establish absence. Use fema_query_dataset for full rows. not_found points 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:
- Case-insensitive county and incident type filters, using bundled declaration names plus exact PA county spellings. Refresh with
bun run vocabulary:build: sequential full exports read declarations in ID order and nonnull PA counties without a sort, with bounded transient retries. Each export must match its reported count; a failed or incomplete refresh leaves the snapshot unchanged.
DisasterDeclarationsSummaries rows collapse to one summary per declaration, with designated_area_count
fema_search_nfip requires state, which prevents unbounded 2.7M-row fetches
- Aggregate PA obligations, housing assistance, and NFIP losses in DuckDB through DataCanvas
- No API keys required — OpenFEMA is a free, public API
Agent-friendly output:
- Disaster number is the join key across tools, so calls chain without re-searching
- Empty searches return empty arrays, zero totals, and a
notice with guidance for supplied filters on both response surfaces; assistance calls can check declared programs with fema_get_disaster. Paging past a nonzero total has separate offset guidance.
- Typed errors on every tool (
invalid_state, invalid_county_code, invalid_range, not_found, missing_filter, unknown_dataset, dataset_not_served, invalid_filter, invalid_select, invalid_orderby, invalid_odata_syntax, request_too_long, filter_too_complex, canvas_unavailable), each with a recovery hint
designated_area_count on search results shows whether fema_get_disaster is worth a follow-up
Getting started
Connect to the hosted instance, no install:
Or run it locally:
For other clients, add this to the MCP config file:
No API key is required — OpenFEMA is a free, public API. For Docker or a source build, see Running the server.
Configuration
All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
-
Clone and install:
-
Build and run:
-
Run checks and tests:
Docker
The image defaults to HTTP transport, stateless session mode, and logs to /var/log/fema-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/fema-mcp-server:latest"]. To build locally, docker build -t fema-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
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:
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:
License
Apache-2.0 — see LICENSE for details.