\n\n[](https://github.com/cyanheads/fema-mcp-server/releases/latest/download/fema-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=fema-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvZmVtYS1tY3Atc2VydmVyIl19) [](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)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nEight tools are advertised by default. Setting `FEMA_ENABLE_CANVAS_DROP=true` adds a ninth, destructive DataCanvas cleanup tool. Together they cover the OpenFEMA data surface — convenience tools for the headline datasets, SQL analytics over large NFIP result sets via DuckDB canvas, and a generic escape hatch for datasets the convenience tools don't cover:\n\n| Tool | Description |\n|:---|:---|\n| `fema_search_disasters` | Search federal disaster declarations by state, incident type, declaration type, date range, and county |\n| `fema_get_disaster` | Fetch all designated-area records for a specific disaster by disaster number |\n| `fema_get_public_assistance` | Public assistance funded projects for a disaster or state — where federal recovery money went |\n| `fema_get_housing_assistance` | Individual assistance housing data for a disaster — owner and renter breakdowns by county/ZIP |\n| `fema_search_nfip` | NFIP flood insurance claims for a state, county, or ZIP, with optional DataCanvas spillover for SQL analytics |\n| `fema_dataframe_describe` | List columns and row counts for DataCanvas tables staged by `fema_search_nfip` |\n| `fema_dataframe_query` | Run a SELECT query against a DataCanvas table staged by `fema_search_nfip` |\n| `fema_dataframe_drop` | Remove a staged DataCanvas table or view (disabled unless explicitly enabled) |\n| `fema_query_dataset` | Generic OData query against any OpenFEMA v2 dataset — escape hatch for datasets the convenience tools don't cover |\n\n### `fema_search_disasters`\n\nThe primary entry point — \"what disasters were declared in Texas in 2025?\"\n\n- Filter by state (2-letter code), incident type (Hurricane, Flood, Wildfire, etc.), declaration type (`DR`/`EM`/`FM`), date range, and county\n- Returns deduplicated declaration-level summaries — one row per declaration, not per designated area\n- Includes disaster number (the join key for PA and housing tools), title, state, incident type, declaration/incident dates, programs declared (IA/PA/HM), and `designatedAreaCount`\n- Paginated via `limit` / `offset`\n\n---\n\n### `fema_get_disaster`\n\nFetch all designated-area records for a specific FEMA disaster number.\n\n- Returns every county/municipality row for the declaration with programs activated, incident period, and FIPS codes\n- Use after `fema_search_disasters` to drill into a specific event; the disaster number chains to PA and housing tools\n- `DisasterDeclarationsSummaries` returns one row per designated area — a single declaration can span dozens of counties\n\n---\n\n### `fema_get_public_assistance`\n\nRetrieve PA funded project details — where federal recovery money went after a disaster.\n\n- Filter by `disaster_number`, `state`, or `county`; at least one of `disaster_number` or `state` is required\n- Returns applicant, damage category, project size/status, federal share obligated, and total obligated\n- Useful for journalists, researchers, and oversight analysts tracking federal grant flows\n\n---\n\n### `fema_get_housing_assistance`\n\nIndividual assistance housing data for a disaster, broken down by county and ZIP.\n\n- Returns owner and renter breakdowns via `type` param (`owners`/`renters`/`both`)\n- Fields include valid registrations, total inspected, total damage, approved IHP amounts, repair/rental/other-needs amounts, and max grants\n- Covers `HousingAssistanceOwners` and `HousingAssistanceRenters` datasets in a single call\n\n---\n\n### `fema_search_nfip`\n\nNFIP flood insurance claims with optional DuckDB-backed SQL analytics for large result sets.\n\n- Requires at minimum a `state` filter — unfiltered NFIP Claims is 2.7M rows\n- Additional filters: `county_code`, `zip_code`, `year_from`, `year_to`; pagination via `limit`\n- When `CANVAS_PROVIDER_TYPE=duckdb` is set and results exceed the inline cap, the full result set spills to a DataCanvas table and returns a `canvas_id` handle\n- Use `fema_dataframe_describe` to inspect the schema, then `fema_dataframe_query` for aggregation, grouping, and time-series analysis without re-fetching\n\n---\n\n### `fema_dataframe_describe` / `fema_dataframe_query` / `fema_dataframe_drop`\n\nIn-conversation SQL analytics over NFIP Claims data staged by `fema_search_nfip` on a DuckDB-backed DataCanvas.\n\n- `fema_dataframe_describe`: lists columns, types, and row count for a canvas table — use before writing a query\n- `fema_dataframe_query`: runs a single SELECT statement against the staged table; standard DuckDB SQL (GROUP BY, SUM, window functions, time-series)\n- `fema_dataframe_drop`: removes one staged table or view; disabled by default and enabled with `FEMA_ENABLE_CANVAS_DROP=true`\n- Workflow: `fema_search_nfip` (with canvas enabled) → `fema_dataframe_describe` → `fema_dataframe_query`\n- SQL queries are read-only — writes, DDL, and DROP statements are rejected by the framework SQL gate. The gated drop tool only removes staged canvas data and never changes FEMA source data.\n\n---\n\n### `fema_query_dataset`\n\nGeneric OData query against any OpenFEMA v2 dataset — the escape hatch for datasets the convenience tools don't cover.\n\n- Accepts raw `$filter`, `$select`, `$orderby`, `limit`, and `offset` params\n- Dataset name must match an actual OpenFEMA endpoint (e.g. `FimaNfipPolicies`, `IndividualAssistanceHousingRegistrantsLargeDisasters`)\n- Validates that the API returns JSON (Content-Type check) and surfaces structured error codes on 400 responses\n\n## Resources and prompts\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `fema://disaster/{disasterNumber}` | Summary for a specific FEMA disaster declaration — title, state, incident type, programs, incident period |\n\nAll resource data is also reachable via tools. Use `fema_get_disaster` for the same data with pagination and full designated-area detail.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nFEMA/OpenFEMA-specific:\n\n- Typed OpenFEMA REST client with OData parameter building (`%24`-encoded to satisfy Akamai's Drupal layer), response parsing, and structured error classification (JSON 400 vs HTML 404)\n- Automatic deduplication of `DisasterDeclarationsSummaries` — one row per designated area collapsed to declaration-level summaries with `designatedAreaCount`\n- NFIP Claims guard: `state` filter is required to prevent unbounded 2.7M-row fetches\n- DataCanvas spillover for NFIP analytics — large NFIP result sets materialize as DuckDB tables queryable via SQL without re-fetching\n- No API keys required — OpenFEMA is a free, public API\n\nAgent-friendly output:\n\n- 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\n- Typed error contracts on every tool — `invalid_state`, `no_results`, `missing_filter`, `unknown_dataset`, `invalid_filter`, `canvas_unavailable` — with recovery hints telling agents the concrete next step\n- `designatedAreaCount` on search results so agents know whether to drill in with `fema_get_disaster` without having to fetch the full record first\n\n## Getting started\n\n### Public Hosted Instance\n\nA public instance is available at `https://fema.caseyjhand.com/mcp` — no installation required. Point any MCP client at it via Streamable HTTP:\n\n```json\n{\n \"mcpServers\": {\n \"fema-mcp-server\": {\n \"type\": \"streamable-http\",\n \"url\": \"https://fema.caseyjhand.com/mcp\"\n }\n }\n}\n```\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"fema-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/fema-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"fema-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/fema-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"fema-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/fema-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\nTo enable DuckDB-backed SQL analytics for NFIP Claims:\n\n```json\n{\n \"mcpServers\": {\n \"fema-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/fema-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"CANVAS_PROVIDER_TYPE\": \"duckdb\"\n }\n }\n }\n}\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No API keys required — OpenFEMA is a free, public API.\n- Optional: set `CANVAS_PROVIDER_TYPE=duckdb` to enable SQL analytics over large NFIP Claims result sets.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/fema-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd fema-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# edit .env — no required vars, but CANVAS_PROVIDER_TYPE=duckdb enables SQL analytics\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `FEMA_BASE_URL` | Override the OpenFEMA API base URL. | `https://www.fema.gov/api/open/v2` |\n| `FEMA_REQUEST_TIMEOUT_MS` | Per-request HTTP timeout in milliseconds. NFIP county queries can be slow. | `30000` |\n| `CANVAS_PROVIDER_TYPE` | Set to `duckdb` to enable DataCanvas for NFIP Claims analytics. Without it, `fema_search_nfip` inlines results up to the cap. | — |\n| `FEMA_ENABLE_CANVAS_DROP` | Enable the destructive `fema_dataframe_drop` tool for removing staged tables and views. | `false` |\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |\n| `MCP_SESSION_MODE` | Session mode: `auto`, `stateful`, or `stateless`. This server explicitly uses stateless; schema default `auto` resolves to stateful when no value is provided. | `stateless` |\n| `MCP_HTTP_PORT` | HTTP server port. | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |\n| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t fema-mcp-server .\ndocker run --rm -e MCP_TRANSPORT_TYPE=stdio fema-mcp-server\n```\n\nThe 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.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools/resources and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) — one file per tool. |\n| `src/mcp-server/resources` | Resource definitions (`*.resource.ts`). |\n| `src/services/openfema` | OpenFEMA REST API client — OData param builder, response parser, error classifier, retry wrapper. |\n| `src/services/canvas` | DataCanvas integration — DuckDB spillover for large NFIP result sets. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources in `src/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## Data source\n\nData is provided by the [OpenFEMA API](https://www.fema.gov/about/openfema/api), a free public API maintained by the Federal Emergency Management Agency. Usage is subject to [OpenFEMA Terms and Conditions](https://www.fema.gov/about/openfema/terms-conditions).\n\n> 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).\n\nWhen citing OpenFEMA datasets in research or publications, use the format FEMA specifies:\n\n```\nFederal Emergency Management Agency (FEMA), OpenFEMA Dataset: . Retrieved from on .\n```\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE) for details.\n",
"bytes": 16677,
"sha": "e8cd2152d5c70f32d23dbc8df76305ee1d1e6f54b4bb56c71d00ea760a77a3ec",
"repo_slug": "cyanheads/fema-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_fema_mcp_server_98f91241/readme"
}