io.github.cyanheads/fema-mcp-server

Official8 toolsLive

by cyanheads · TypeScript

Query FEMA disaster declarations, public assistance grants, housing aid, and NFIP claims.

@cyanheads/fema-mcp-server (Model Context Protocol)

The io.github.cyanheads/fema-mcp-server is an MCP server that queries FEMA disaster declarations, public assistance grants, housing aid, and NFIP flood insurance claims. It exposes 8 tools and can run via STDIO or Streamable HTTP.

🛠️ Key Features

Query FEMA disaster declarations
Query public assistance grants
Query housing aid
Query NFIP claims
8 tools total

🚀 Use Cases

Retrieve FEMA-related declaration information for disaster response and planning
Look up public assistance grants and housing aid context
Fetch NFIP flood insurance claim details

⚡ Developer Benefits

MCP-compatible interface for integrating FEMA datasets into agent workflows
Works over STDIO or Streamable HTTP
Includes TypeScript and OpenFEMA-oriented tooling (per repository topics)

⚠️ Limitations

Description does not specify tool names, authentication, rate limits, or data coverage beyond the listed FEMA/NFIP categories.

Topics

ai-agentsai-toolscyanheadsdisasteremergencyfemamcpmcp-servermodel-context-protocolopenfematypescript

Captured live from the server via tools/list.

fema_search_disasters

Search federal disaster declarations by state, incident type, declaration type, date range, and county. Returns deduplicated declaration-level summaries — each disaster number appears once with a designatedAreaCount showing how many counties/municipalities were designated. The disaster number is the chain key for fema_get_disaster, fema_get_public_assistance, and fema_get_housing_assistance. Use declaration_type to filter: DR (major disaster, most common), EM (emergency), FM (fire management). Date filters apply to the declaration date. Use fema_get_disaster to retrieve all designated-area rows for a specific declaration. A search reads the most recent 10,000 designated-area rows; when more match, it returns the declarations dated after the day that window ends, sets truncated, and its notice names the date_to that continues with older declarations.

Parameters8

state	string	optional	Two-letter US state/territory code (e.g., TX, CA, FL, PR). Filters by state.
incident_type	string	optional	Incident type filter (e.g., Flood, Hurricane, Tornado, Fire, Earthquake, Severe Storm). Case-insensitive substring match.
declaration_type	string	optional	Declaration type: DR (major disaster declaration), EM (emergency declaration), FM (fire management assistance declaration).
date_from	any	optional	Start of the declaration date range as a calendar date in YYYY-MM-DD format (e.g., 2024-01-01). Inclusive.
date_to	any	optional	End of the declaration date range as a calendar date in YYYY-MM-DD format (e.g., 2024-12-31). Inclusive.
county	string	optional	Filter by designated area / county name substring (e.g., Harris, Los Angeles). Case-insensitive.
limit	integer	optional	Maximum number of unique disaster declarations to return (1–1000, default 50).
offset	integer	optional	Pagination offset in declarations (default 0). Use with limit to page through results.

Raw schema

{
  "type": "object",
  "properties": {
    "state": {
      "description": "Two-letter US state/territory code (e.g., TX, CA, FL, PR). Filters by state.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "incident_type": {
      "description": "Incident type filter (e.g., Flood, Hurricane, Tornado, Fire, Earthquake, Severe Storm). Case-insensitive substring match.",
      "type": "string"
    },
    "declaration_type": {
      "description": "Declaration type: DR (major disaster declaration), EM (emergency declaration), FM (fire management assistance declaration).",
      "type": "string",
      "enum": [
        "DR",
        "EM",
        "FM"
      ]
    },
    "date_from": {
      "description": "Start of the declaration date range as a calendar date in YYYY-MM-DD format (e.g., 2024-01-01). Inclusive.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "format": "date",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
          "description": "Calendar date, YYYY-MM-DD."
        }
      ]
    },
    "date_to": {
      "description": "End of the declaration date range as a calendar date in YYYY-MM-DD format (e.g., 2024-12-31). Inclusive.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "format": "date",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$",
          "description": "Calendar date, YYYY-MM-DD."
        }
      ]
    },
    "county": {
      "description": "Filter by designated area / county name substring (e.g., Harris, Los Angeles). Case-insensitive.",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "description": "Maximum number of unique disaster declarations to return (1–1000, default 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset in declarations (default 0). Use with limit to page through results.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_get_disaster

Fetch all designated-area rows for a specific FEMA disaster by disaster number (e.g., 4781). Returns every county/municipality designated under the declaration along with programs activated, incident period, and state info. Use fema_search_disasters to find disaster numbers. The returned disaster_number chains to fema_get_public_assistance and fema_get_housing_assistance.

Parameters1

disaster_number

integer

required

FEMA disaster number (e.g., 4781). Obtain from fema_search_disasters.

Raw schema

{
  "type": "object",
  "properties": {
    "disaster_number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "FEMA disaster number (e.g., 4781). Obtain from fema_search_disasters."
    }
  },
  "required": [
    "disaster_number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_get_public_assistance

Retrieve Public Assistance (PA) funded project records for a disaster or state — shows where federal recovery money was obligated. Returns applicant, damage category, project size and status, federal share obligated, and total obligated amounts. Either disaster_number or state must be provided. Use disaster_number (from fema_search_disasters) to scope to a single declaration, or state to browse all PA projects for a state. PA projects are created only when the PA program is declared (pa_declared: true on the disaster).

Parameters5

disaster_number	integer	optional	FEMA disaster number to scope results to a single declaration. Numbers above 32767 match no declaration.
state	string	optional	Two-letter state code to browse all PA projects for a state.
county	string	optional	Filter by county name substring.
limit	integer	optional	Maximum number of projects to return (1–1000, default 100).
offset	integer	optional	Pagination offset (default 0).

Raw schema

{
  "type": "object",
  "properties": {
    "disaster_number": {
      "description": "FEMA disaster number to scope results to a single declaration. Numbers above 32767 match no declaration.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "state": {
      "description": "Two-letter state code to browse all PA projects for a state.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "county": {
      "description": "Filter by county name substring.",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Maximum number of projects to return (1–1000, default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_get_housing_assistance

Retrieve Individual Assistance (IA) housing data for a disaster by disaster number. Returns owner and/or renter breakdowns by county and ZIP code — valid registrations, total approved IHP amounts, repair/rental amounts, and inspection data. Use type to select owners, renters, or both (default). Use disaster_number from fema_search_disasters.

Parameters5

disaster_number	integer	required	FEMA disaster number. Obtain from fema_search_disasters. Numbers above 32767 match no declaration.
state	string	optional	Two-letter state code to narrow results when a disaster spans multiple states.
type	string	optional	Which housing assistance dataset to query: owners, renters, or both (default).
limit	integer	optional	Maximum records per dataset to return (default 100).
offset	integer	optional	Pagination offset (default 0).

Raw schema

{
  "type": "object",
  "properties": {
    "disaster_number": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "FEMA disaster number. Obtain from fema_search_disasters. Numbers above 32767 match no declaration."
    },
    "state": {
      "description": "Two-letter state code to narrow results when a disaster spans multiple states.",
      "type": "string",
      "minLength": 2,
      "maxLength": 2
    },
    "type": {
      "default": "both",
      "description": "Which housing assistance dataset to query: owners, renters, or both (default).",
      "type": "string",
      "enum": [
        "owners",
        "renters",
        "both"
      ]
    },
    "limit": {
      "default": 100,
      "description": "Maximum records per dataset to return (default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "disaster_number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_search_nfip

Search National Flood Insurance Program (NFIP) claims data by state, county, ZIP code, and year range. Returns the matching claim count and claim records — amounts paid on building and contents, damage estimates, flood zones, cause and occupancy codes, and loss dates — newest loss first. state is required — the full NFIP dataset is 2.7 million rows; unfiltered access is prohibited. Page the inline claims with limit and offset; a page holds at most 100,000 characters of claims. When DataCanvas is enabled (CANVAS_PROVIDER_TYPE=duckdb) and the match exceeds that inline budget, a call at offset 0 stages the match (up to 50,000 claims) on a canvas: inspect the staged table with fema_dataframe_describe, then aggregate it with SQL via fema_dataframe_query.

Parameters8

state	string	required	Two-letter US state code (required). NFIP dataset is 2.7M rows — state filter is mandatory.
county_code	string	optional	County code to narrow results within the state. Accepts the full 5-digit state+county FIPS (e.g., 48201 for Harris County TX) or the 3-digit county portion (e.g., 201) when state is provided — the server prepends the state FIPS automatically.
zip_code	string	optional	ZIP code to narrow results to a specific area (5-digit, e.g., 77002).
year_from	integer	optional	Start year of loss, inclusive (e.g., 2020).
year_to	integer	optional	End year of loss, inclusive (e.g., 2023).
limit	integer	optional	Maximum claims to return inline (1–10000, default 1000). A page also stops at 100,000 characters of claims (roughly 330 claims); when either bound leaves matching claims out, the notice names the offset to continue from. When DataCanvas is enabled and the match exceeds that character budget, a call at offset 0 stages the match on a canvas regardless of this value.
offset	integer	optional	Pagination offset into the matching claims, ordered newest date of loss first (default 0). Use with limit to page through a match. Only a call at offset 0 stages a match on a canvas; a later offset returns just its inline page. After a spill (spilled=true), read rows past the inline claims from the canvas table with fema_dataframe_query.
canvas_id	string	optional	Optional canvas ID from a prior call, to stage this match as another table on that canvas. Used only when the match is staged; omit it to stage on a fresh canvas. Pass the returned canvas_id to fema_dataframe_describe for the table columns, then to fema_dataframe_query for SQL.

Raw schema

{
  "type": "object",
  "properties": {
    "state": {
      "type": "string",
      "minLength": 2,
      "maxLength": 2,
      "description": "Two-letter US state code (required). NFIP dataset is 2.7M rows — state filter is mandatory."
    },
    "county_code": {
      "description": "County code to narrow results within the state. Accepts the full 5-digit state+county FIPS (e.g., 48201 for Harris County TX) or the 3-digit county portion (e.g., 201) when state is provided — the server prepends the state FIPS automatically.",
      "type": "string"
    },
    "zip_code": {
      "description": "ZIP code to narrow results to a specific area (5-digit, e.g., 77002).",
      "type": "string",
      "pattern": "^\\d{5}$"
    },
    "year_from": {
      "description": "Start year of loss, inclusive (e.g., 2020).",
      "type": "integer",
      "minimum": 1970,
      "maximum": 2100
    },
    "year_to": {
      "description": "End year of loss, inclusive (e.g., 2023).",
      "type": "integer",
      "minimum": 1970,
      "maximum": 2100
    },
    "limit": {
      "default": 1000,
      "description": "Maximum claims to return inline (1–10000, default 1000). A page also stops at 100,000 characters of claims (roughly 330 claims); when either bound leaves matching claims out, the notice names the offset to continue from. When DataCanvas is enabled and the match exceeds that character budget, a call at offset 0 stages the match on a canvas regardless of this value.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset into the matching claims, ordered newest date of loss first (default 0). Use with limit to page through a match. Only a call at offset 0 stages a match on a canvas; a later offset returns just its inline page. After a spill (spilled=true), read rows past the inline claims from the canvas table with fema_dataframe_query.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "canvas_id": {
      "description": "Optional canvas ID from a prior call, to stage this match as another table on that canvas. Used only when the match is staged; omit it to stage on a fresh canvas. Pass the returned canvas_id to fema_dataframe_describe for the table columns, then to fema_dataframe_query for SQL.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "required": [
    "state"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_dataframe_query

Run a read-only SQL SELECT against a DataCanvas table staged by fema_search_nfip. Enables aggregation, GROUP BY, SUM/COUNT, time-series, and filtered analysis over the full NFIP claims result without re-fetching from the API. Call fema_dataframe_describe first to get the exact table name and column names needed for valid SQL. Only SELECT statements are allowed — DDL, DML, COPY, and file-reading functions are blocked.

Parameters2

canvas_id	string	required	Canvas ID from the fema_search_nfip response (the canvas_id field).
query	string	required	SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit; append LIMIT/OFFSET to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: "SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss"

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID from the fema_search_nfip response (the canvas_id field)."
    },
    "query": {
      "type": "string",
      "description": "SQL SELECT statement to run against the staged table. Use the table name from fema_dataframe_describe. Results are capped at the canvas row limit; append LIMIT/OFFSET to page through additional rows, or aggregate (GROUP BY, COUNT, SUM) to summarize the full set in one query. Example: \"SELECT year_of_loss, COUNT(*) AS claims, SUM(amount_paid_building) AS total_building_paid FROM df_nfip_abc123 GROUP BY year_of_loss ORDER BY year_of_loss\""
    }
  },
  "required": [
    "canvas_id",
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_dataframe_describe

List tables and column schemas on a DataCanvas staged by fema_search_nfip. Call this before fema_dataframe_query to discover the exact table name, column names, and DuckDB data types needed to write valid SQL. Row count reflects what was actually staged — check truncated in the fema_search_nfip response to know whether the canvas holds the full matching set.

Parameters1

canvas_id

string

required

Canvas ID from the fema_search_nfip response.

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID from the fema_search_nfip response."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

fema_query_dataset

Generic OData query against any dataset in the OpenFEMA dataset catalog — the escape hatch for datasets the convenience tools do not cover (e.g., NfipPolicies, IndividualAssistanceHousingRegistrantsLargeDisasters, FemaWebDeclarationAreas, PublicAssistanceApplicants). Accepts raw OData filter, select, orderby, and pagination parameters. For NfipPolicies, use propertyState (not state) for the state and reportedZipCode for the ZIP code — it has no countyCode; always include a ZIP filter to avoid timeout. The dataset name must match the exact OpenFEMA entity name (case-sensitive, e.g., NfipClaims). Names missing from the catalog return an unknown_dataset error; a listed dataset OpenFEMA does not serve through the API returns dataset_not_served.

Parameters6

dataset	string	required	OpenFEMA dataset entity name (case-sensitive, e.g., NfipPolicies, FemaWebDeclarationAreas, PublicAssistanceApplicants).
filter	string	optional	OData $filter expression (e.g., "state eq 'TX' and declarationDate ge '2024-01-01T00:00:00.000Z'"). String values in single quotes.
select	string	optional	Comma-separated field names to return (e.g., "disasterNumber,state,declarationDate").
orderby	string	optional	OData $orderby expression (e.g., "declarationDate desc").
limit	integer	optional	Maximum records to return (1–10000, default 100).
offset	integer	optional	Pagination offset (default 0).

Raw schema

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "minLength": 1,
      "description": "OpenFEMA dataset entity name (case-sensitive, e.g., NfipPolicies, FemaWebDeclarationAreas, PublicAssistanceApplicants)."
    },
    "filter": {
      "description": "OData $filter expression (e.g., \"state eq 'TX' and declarationDate ge '2024-01-01T00:00:00.000Z'\"). String values in single quotes.",
      "type": "string"
    },
    "select": {
      "description": "Comma-separated field names to return (e.g., \"disasterNumber,state,declarationDate\").",
      "type": "string"
    },
    "orderby": {
      "description": "OData $orderby expression (e.g., \"declarationDate desc\").",
      "type": "string"
    },
    "limit": {
      "default": 100,
      "description": "Maximum records to return (1–10000, default 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "offset": {
      "default": 0,
      "description": "Pagination offset (default 0).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "dataset"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md19 KBView on GitHub

@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

MCP SDK TypeScript

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 callable and appears in tools/list only when FEMA_ENABLE_CANVAS_DROP=true. Its definition is always included in createApp(); while disabled, the HTTP landing page displays the enable hint. 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 full designated-area detail.

Capability reference

`fema_search_disasters` _tool

Filters: state, incident_type, declaration_type (DR/EM/FM), inclusive date_from/date_to (YYYY-MM-DD), and county; page with limit (1–1000, default 50) and offset.
Returns one summary per disaster number with designated_area_count, program flags, and declaration totals. Typed errors: invalid_state, no_results.
Searches the most recent 10,000 designated-area rows. When capped, returns complete declarations, marks truncated, reports declaration totals as lower bounds, and names the next date_to in notice.

`fema_get_disaster` _tool

Requires disaster_number from fema_search_disasters.
Returns all designated-area records, FIPS codes, incident period, and program flags combined across areas; a missing disaster returns not_found.

`fema_get_public_assistance` _tool

Requires disaster_number or state; optional county filter, limit (1–1000, default 100), and offset.
Returns applicants, damage categories, project size/status, and federal and total obligations. Typed errors: invalid_state, missing_filter, not_found, no_results.

`fema_get_housing_assistance` _tool

Requires disaster_number; optional state, type (owners/renters/both, default both), limit (1–1000, default 100), and offset.
Returns separate owners and renters arrays with county/ZIP registrations and approved amounts, plus owners_count/renters_count totals. Typed errors: invalid_state, not_found, no_results.

`fema_search_nfip` _tool

Requires state; optional county_code, zip_code, year_from/year_to, limit (1–10000, default 1000), and offset. Reads NfipClaims v3, newest loss first with claim ID breaking ties.
county_code accepts a full 5-digit FIPS code (e.g., 48201) or a 3-digit county code (e.g., 201); the server prefixes the latter with the state's FIPS code.
Inline claims stop at 100,000 characters, with a continuation offset in notice; cause_of_damage and occupancy_type retain OpenFEMA's published codes. Typed errors: invalid_state, no_results.
With CANVAS_PROVIDER_TYPE=duckdb, a first-page match exceeding the inline 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 retains the full match. Inspect the stage with fema_dataframe_describe, then query it with fema_dataframe_query.

`fema_dataframe_describe` _tool

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` _tool

Requires canvas_id and a single SQL query; only SELECT statements are permitted. DDL, DML, COPY, and file-reading functions are blocked.
Returns rows capped at the canvas row limit, with truncated/shown/cap and LIMIT/OFFSET guidance when capped. Typed errors: canvas_not_found, canvas_unavailable, invalid_query, 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. Typed errors: canvas_not_found, canvas_unavailable.
Opt-in through FEMA_ENABLE_CANVAS_DROP=true; disabled by default with an enable hint in the manifest. FEMA source data is unchanged.

`fema_query_dataset` _tool

Requires a case-sensitive OpenFEMA dataset; optional OData filter/select/orderby, limit (1–10000, default 100), and offset. Resolves each dataset's API version from the catalog.
Returns records and total_count; an empty page succeeds with filter or paging guidance. Typed errors: unknown_dataset, dataset_not_served, catalog_unavailable (retryable), invalid_filter, invalid_select, invalid_orderby, invalid_odata_syntax.
For NfipPolicies, use propertyState and reportedZipCode; 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 designated_area_count; not_found carries recovery guidance 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:

Disaster numbers are in OpenFEMA's range 1–32767; an offset past the last match returns an empty page with totals and a notice naming the last valid offset.
Canvas inputs accept the server-issued 10-character URL-safe canvas_id ([A-Za-z0-9_-]{10}); omit it on the first NFIP search.
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:

json

{
  "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.

json

{
  "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):

json

{
  "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:

json

{
  "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:

json

{
  "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`
`LOG_TOOL_FAILURE_PAYLOADS`	Log failed-call arguments and results, redacted by key name. Secrets in free-form values are retained.	`false`
`LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`	Per-payload UTF-8 byte cap for failed-call logging.	`16384`
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP base URL; traces append `/v1/traces`, metrics append `/v1/metrics`.	—
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Override the traces endpoint; used as-is.	—
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Override the metrics endpoint; used as-is.	—
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Opt into log export at this URL; the base endpoint alone never enables it.	—
`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 are cross-installed for the target architecture in a native build stage, with release-age and Socket checks; the Debian runtime excludes unused musl bindings.

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:

code

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

License

Apache-2.0 — see LICENSE for details.

Install

Tools (8)

fema_search_disastersfema_get_disasterfema_get_public_assistancefema_get_housing_assistancefema_search_nfipfema_dataframe_queryfema_dataframe_describefema_query_dataset

Configuration

Environment variables

FEMA_ENABLE_CANVAS_DROPdefault false

Enable the destructive fema_dataframe_drop tool for removing staged canvas data.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_TRANSPORT_TYPEdefault http

Selects the HTTP transport.

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "fema-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/fema-mcp-server@0.3.2"
      ],
      "env": {
        "FEMA_ENABLE_CANVAS_DROP": "false",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/fema-mcp-server (Model Context Protocol)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

fema_search_disasters

fema_get_disaster

fema_get_public_assistance

fema_get_housing_assistance

fema_search_nfip

fema_dataframe_query

fema_dataframe_describe

fema_query_dataset

@cyanheads/fema-mcp-server

Overview

Tools

Resources

Capability reference

fema_search_disasters tool

fema_get_disaster tool

fema_get_public_assistance tool

fema_get_housing_assistance tool

fema_search_nfip tool

fema_dataframe_describe tool

fema_dataframe_query tool

fema_dataframe_drop tool

fema_query_dataset tool

fema://disaster/{disasterNumber} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

Data source

License

Install

Configuration

Related servers

`fema_search_disasters` _tool

`fema_get_disaster` _tool

`fema_get_public_assistance` _tool

`fema_get_housing_assistance` _tool

`fema_search_nfip` _tool

`fema_dataframe_describe` _tool

`fema_dataframe_query` _tool

`fema_dataframe_drop` _tool

`fema_query_dataset` _tool

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