<div align="center">

# mcp-usa-climate-risk

**Model Context Protocol server for real-time US climate risk and home insurance metrics.**

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-brightgreen.svg)](https://modelcontextprotocol.io)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933.svg)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178c6.svg)](https://www.typescriptlang.org)

</div>

---

## Overview

`mcp-usa-climate-risk` is an open-source [Model Context Protocol](https://modelcontextprotocol.io) server that exposes real-time US climate risk data to LLM agents. It provides a single, robust tool — `get_zip_climate_risk` — that queries the [RiskBeforeBuy API](https://www.riskbeforebuy.com/api-docs) to return parcel-level hazard scores, estimated homeowners insurance premiums, premium-to-income strain, and state insurance market pressure for any valid 5-digit US ZIP code.

Built for **Claude Desktop**, **Cursor IDE**, **Windsurf**, and any MCP-compatible AI environment.

---

## Installation

### Prerequisites

- **Node.js** >= 18.0.0
- **npm** or **pnpm**
- A supported MCP client (Claude Desktop, Cursor, Windsurf)

### Clone & Build

```bash
git clone https://github.com/opendata-collective/mcp-usa-climate-risk.git
cd mcp-usa-climate-risk
npm install
npm run build
```

---

## Client Configuration

### Claude Desktop

Add the following to your Claude Desktop MCP configuration file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "usa-climate-risk": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-usa-climate-risk/dist/index.js"]
    }
  }
}
```

After restarting Claude Desktop, the `get_zip_climate_risk` tool will appear in your available tools.

### Cursor IDE

Add the following to your Cursor MCP configuration (`.cursor/mcp.json` in your project root, or the global settings):

```json
{
  "mcpServers": {
    "usa-climate-risk": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-usa-climate-risk/dist/index.js"]
    }
  }
}
```

### Windsurf

Add the following to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "usa-climate-risk": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-usa-climate-risk/dist/index.js"]
    }
  }
}
```

### Development Mode

To run the server in development mode with hot-reloading via `tsx`:

```bash
npm run dev
```

---

## Tool Reference

### `get_zip_climate_risk`

Fetches comprehensive climate hazards, estimated home insurance premiums, premium-to-income strain, and market carrier pressure metrics for any valid 5-digit US ZIP Code.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `zip` | `string` | Yes | 5-digit US ZIP code (regex: `^\d{5}$`) |

**Response (HTTP 200):**

Returns a formatted Markdown summary:

```markdown
## Climate Risk Report — ZIP 28801

| Metric | Value |
|--------|-------|
| **Overall Risk** | high |
| **Est. Annual Premium** | $2,287 – $4,130 / year |
| **Premium Strain** | high |
| **Market Pressure** | high |

_Source: Risk Before Buy — Federal data (FEMA, NOAA, USGS, USDA, EPA)._
```

**Error Responses:**

| Status | Meaning | Message |
|--------|---------|---------|
| 404 | ZIP not found | "ZIP code not found in our climate registry." |
| 429 | Rate limited | "Rate limit exceeded for the public tier (5 req/min)..." |
| Network error | Connection failure | Graceful error message, never crashes |

---

## Data Sources

All risk metrics are derived from verified federal datasets:

| Agency | Dataset | Coverage |
|--------|---------|----------|
| **FEMA** | National Risk Index (NRI) | Flood, hurricane, wildfire, earthquake |
| **NOAA** | Storm Events Database | Historical severe weather claims |
| **USGS** | Earthquake Hazards Program | Seismic peak ground acceleration |
| **USDA** | Forest Service Wildfire Risk | Wildfire probability to communities |
| **EPA** | Climate Exposure Overlays | Environmental hazard proximity |

Powered by the [RiskBeforeBuy Official Platform](https://www.riskbeforebuy.com).

---

## API Rate Limits

The public tier allows **5 requests per minute** per IP. For bulk lookups and production integrations, consult the [RiskBeforeBuy API Documentation](https://www.riskbeforebuy.com/api-docs).

---

## Contributing

Contributions are welcome from data engineers, climate scientists, and MCP ecosystem developers. Areas of interest:

- Additional MCP tools (e.g., parcel-level flood zone lookup, insurance market deep-dive)
- Alternative transport implementations (Streamable HTTP, SSE)
- Client SDK wrappers for Python, Go, Rust
- Test coverage and data validation scripts

Please open an issue or submit a pull request.

---

## License

[MIT](https://opensource.org/licenses/MIT) — Open Data Collective © 2026

---

<div align="center">

**[RiskBeforeBuy.com](https://www.riskbeforebuy.com)** · [API Documentation](https://www.riskbeforebuy.com/api-docs) · [Methodology](https://www.riskbeforebuy.com/methodology)

</div>