Fema Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.6.0Updated Nov 21, 2026

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

VerifiedStreamable HTTPWeb executableDatabasesFinanceData & Analytics

Overview

AI-generated overview

Queries FEMA disaster declarations, public assistance grants, housing aid and NFIP flood claims, with SQL analytics over large claim result sets.

What you can do
  • Search and read disaster declarations, including designated areas, programs and incident periods
  • Retrieve public assistance funded projects and individual housing assistance records by disaster, state, county or ZIP
  • Search NFIP flood insurance claims by state, county FIPS or ZIP and year range
  • Describe and run read-only SQL SELECT queries over staged NFIP claim tables
  • Run generic OData queries against any dataset in the OpenFEMA catalog
  • Read a disaster summary resource by disaster number
When to use it
Useful for disaster recovery research, grant and aid analysis, flood insurance claim analysis, or any question about FEMA declarations and OpenFEMA datasets where the assistant should pull the data directly instead of relying on memory.
Requirements
Either the hosted remote endpoint or a local process via npx (Node.js), Docker, or a source build with Bun 1.4.0+ or Node.js 24+. No API key: OpenFEMA is a free public API. Optional environment variables cover transport, HTTP host/port/path, auth mode, log level, DataCanvas provider and OpenTelemetry.
Before you install
Read-only data access, but fema_dataframe_drop deletes staged canvas tables and only appears when FEMA_ENABLE_CANVAS_DROP is enabled. Setting LOG_TOOL_FAILURE_PAYLOADS logs failed-call arguments and results, and secrets in free-form values are retained. Data comes from the third-party OpenFEMA API and is not endorsed by FEMA; results can be truncated or partial, and totals may be lower bounds.

Installation

In SourceWeft

  1. Open Fema Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Ffema-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

@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

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


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

ToolDescription
fema_search_disastersSearch federal disaster declarations by title, state, incident type, declaration type, date range, and county
fema_get_disasterLook up disaster-wide funding and designated areas with their program flags
fema_get_public_assistanceFind PA project obligations, applicants, mitigation amounts, and county FIPS by disaster or state
fema_get_housing_assistanceIndividual assistance housing data for a disaster — owner and renter breakdowns and inspection counts by county/ZIP, filterable by county or ZIP
fema_search_nfipFilter NFIP flood insurance claims by location, loss year, and named flood event
fema_dataframe_describeList columns and row counts for staged PA, housing, and NFIP tables
fema_dataframe_queryRun a SELECT query against staged FEMA records
fema_dataframe_dropRemove a staged DataCanvas table or view — opt-in, absent from tools/list by default
fema_query_datasetGeneric 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

ResourceDescription
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).

Skills

SkillDescription
fema-guideGates, identifier sources, and OData syntax for the fema_* tools: county naming across datasets, dollar totals, NFIP scoping, and fema_query_dataset filters

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:

sh
claude mcp add --transport http fema-mcp-server https://fema.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add fema-mcp-server -- npx -y @cyanheads/fema-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "fema-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/fema-mcp-server"]    }  }}

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:

VariableDescriptionDefault
FEMA_BASE_URLOpenFEMA API root.https://www.fema.gov/api/open
FEMA_REQUEST_TIMEOUT_MSTotal time budget in milliseconds for one upstream request, including retries.30000
CANVAS_PROVIDER_TYPESet duckdb for SQL over assistance and NFIP records or none for inline paging. The Claude Desktop bundle uses none.duckdb
FEMA_ENABLE_CANVAS_DROPEnable the fema_dataframe_drop tool.false
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_SESSION_MODESession mode: auto, stateful, or stateless.stateless
MCP_HTTP_PORTHTTP server port.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOG_TOOL_FAILURE_PAYLOADSLog failed-call arguments and results, redacted by key name. Secrets in free-form values are retained.false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTESByte cap per logged payload.16384
OTEL_EXPORTER_OTLP_ENDPOINTOTLP base URL for traces and metrics.—
OTEL_EXPORTER_OTLP_TRACES_ENDPOINTTraces endpoint, used as-is.—
OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMetrics endpoint, used as-is.—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTLog export endpoint; logs export only when this is set.—
LOGS_DIRDirectory for log files (Node.js only).<server-package-root>/logs
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false

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:

    sh
    git clone https://github.com/cyanheads/fema-mcp-server.gitcd fema-mcp-server && bun installcp .env.example .env   # no required variables
  • Build and run:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/fema-mcp-server:latest

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

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources and inits services.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/toolsTool definitions (*.tool.ts) — one file per tool.
src/mcp-server/resourcesResource definitions (*.resource.ts).
src/services/openfemaOpenFEMA REST API client, plus the case-insensitive name matcher and its bundled name vocabulary.
src/services/canvasDataCanvas integration for PA, housing, and NFIP analytics.
skills/Published agent skill (fema-guide), served over MCP via createApp({ skills }).
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:

sh
bun run devcheckbun 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.

Source: README.md at commit 02d6a0f

Tools

8

fema_search_disasters

Search FEMA Disaster Declarations

Search federal disaster declarations by title, state, incident type, declaration type, date range, and county. Returns deduplicated declaration-level summaries — each disaster number appears once with a designated_area_count 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. county selects the declarations that designated a matching area; their area counts and program flags still describe the whole declaration, and matched_areas lists the matching areas with their own program flags. 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. A page holds at most 100,000 characters of declarations; when declarations remain past it, next_offset is the offset to continue from.

Parameterslimitstatetitlecountyoffsetdate_todate_fromincident_typedeclaration_type

fema_get_disaster

Get FEMA Disaster Details

Fetch up to 1,000 designated-area rows for a specific FEMA disaster by disaster number (e.g., 4781). Discloses partial area and program coverage when more rows exist. Returns counties and municipalities, programs observed, incident period, and disaster-wide funding totals when available. Use fema_search_disasters to find disaster numbers. The returned disaster_number chains to fema_get_public_assistance and fema_get_housing_assistance.

Parametersdisaster_numberrequired

fema_get_public_assistance

Get FEMA Public Assistance Projects

Retrieve Public Assistance (PA) funded project records, including recipient name, damage category, project status, and federal obligations. Supply disaster_number from fema_search_disasters or a state code. A page holds up to 100,000 characters of projects. Use next_offset to continue. With DataCanvas enabled, an overflowing first page also stages up to 50,000 matching rows for fema_dataframe_query.

Parameterslimitstatecountyoffsetcanvas_iddisaster_number

fema_get_housing_assistance

Get FEMA Housing Assistance Data

Retrieve Individual Assistance (IA) housing data for a disaster by disaster number. Returns owner and/or renter records aggregated by county, city, and ZIP code — valid registrations, total approved IHP amounts, repair/rental/other-needs amounts, and inspection counts (owners also carry inspected damage in USD). Narrow with state, county, or zip_code; owners_count, renters_count, and offset then count the filtered records. Use type to select owners, renters, or both (default). A page holds at most 100,000 characters of records, owners and renters cut at the same row count so one offset continues both; when records remain past it, next_offset is the offset to continue from. When either dataset exceeds the first inline page and DataCanvas is enabled, stage each nonempty queried dataset for SQL in fema_dataframe_query. Use disaster_number from fema_search_disasters.

Parameterstypelimitstatecountyoffsetzip_codecanvas_iddisaster_numberrequired

fema_search_nfip

Search NFIP Flood Insurance Claims

Search National Flood Insurance Program (NFIP) claims data by state, county, ZIP code, year range, and exact flood event name. 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, and while claims remain past it, next_offset is the offset to continue from. When DataCanvas is enabled 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.

Parameterslimitstaterequiredoffsetyear_tozip_codecanvas_idyear_fromcounty_codeflood_event

fema_dataframe_query

Query FEMA DataCanvas Table

Query staged NFIP claims, PA projects, or housing records with read-only SQL. Use GROUP BY, SUM, or COUNT to aggregate staged records without re-fetching from the API. Call fema_dataframe_describe first to get the exact table name and column names needed for valid SQL. Read-only queries can inspect columns with SHOW <table> and fill gaps with range() or generate_series() over constant arguments. DDL, DML, COPY, and file-reading functions are blocked. A response holds at most 100,000 characters of rows; when it holds fewer rows than the query returned, truncated and shown are set and the notice says how to page with OFFSET.

Parametersqueryrequiredcanvas_idrequired

fema_dataframe_describe

Describe FEMA DataCanvas Tables

List tables and column schemas for staged NFIP claims, PA projects, and housing records. Call this before fema_dataframe_query to discover the exact table name, column names, and DuckDB data types needed to write valid SQL. Compare each staged count with the source tool’s total before using it for a full-match aggregate.

Parameterscanvas_idrequired

fema_query_dataset

Query Any OpenFEMA 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, or a retired version, returns dataset_not_served. A page holds at most 100,000 characters of records; when records remain past it, next_offset is the offset to continue from.

Parameterslimitfilteroffsetselectdatasetrequiredorderby

Version history

9
  1. v0.6.0LatestNov 21, 2026
  2. v0.5.1Nov 4, 2026
  3. v0.5.0Oct 29, 2026
  4. v0.4.1Oct 19, 2026
  5. v0.4.0Oct 16, 2026
  6. v0.3.2Oct 4, 2026
  7. v0.3.1Sep 24, 2026
  8. v0.2.0Sep 20, 2026
  9. v0.1.14Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts