Skip to main content
Glama
WildFireBot MCP Server

WildFireBot MCP Server

by nycbagel

WildFireBot

Satellite fire detections and the forecast wind, turned into an hourly smoke-exposure score for one location.

Live MCP endpoint: https://wildfirebot.onrender.com/mcp

Inspiration

People downwind of a wildfire often find out from the sky, not from a monitor on their block. NASA FIRMS already sees the hotspots, including ultra-real-time detections over the US and Canada, and forecast models already know which way the wind is about to blow. This project is for the Berkeley x Stanford Grok Bot Hackathon, Most Technically Complex track: make that space data useful to someone standing in the plume.

The repository was renamed to WildFireBot and had no code yet. This tree is the first implementation.

Related MCP server: Wildfire MCP Server

What it does

aqi-smoke forecast --lat 37.8 --lon -122.3 --hours 48 prints, for that point:

  • fire clusters inside the search radius, with total FRP, distance, and whether a detection is ultra-real-time

  • a wind summary at 10 m and about 850 hPa, plus boundary-layer height

  • an hourly smoke-exposure score that is high when FRP is upwind, close, and trapped in a shallow boundary layer

  • the nearest PM2.5 readings, converted with the EPA 2024 breakpoints when a concentration is present

The score is a relative index. A value near 1 is roughly a 100 MW cluster sitting on the upwind path under an 800 m boundary layer. It is not micrograms per cubic meter, not a regulatory AQI, and not a health advisory. Use AirNow, local smoke outlooks, and public-health guidance for decisions about going outside.

aqi-smoke aqi --lat 37.8 --lon -122.3 gives an estimated PM2.5 and EPA AQI at +0, 6, 12, 24, and 48 hours. It adds a Gaussian smoke plume from each fire cluster (emission from FRP, carried by the forecast wind) to Open-Meteo's background PM2.5 forecast. It needs no history, so it works for a fire that started an hour ago. It is a screening estimate, not a regulatory AQI. Add --json for the same output the forecast_smoke_aqi tool returns.

If a feed is down, the command still prints what it has and labels the gap. Missing API keys, a failed satellite, a stale cache, and hours with no wind show up under DEGRADED MODE instead of a traceback or a fake zero.

How we built it (tech stack)

Python 3.11+ package wildfirebot, installable with pyproject.toml. Console scripts are aqi-smoke and wildfirebot. Tables are pandas. HTTP is the standard library, with retries, a disk cache, and redacted keys. Lint is ruff. Tests are pytest. GitHub Actions runs both on pull requests.

The package is split the way later milestones need it:

  • sources/ — FIRMS, Open-Meteo (wind and background PM2.5), AirNow, OpenAQ. Each one implements fetch(bbox, time_range) -> SourceResult.

  • fires/ — drop low-confidence and invalid hotspots, then cluster the rest by distance and FRP.

  • transport/ — fill short wind gaps, walk a back-trajectory, compute the score.

  • model/ — the EPA PM2.5-to-AQI conversion and the Gaussian plume (model/plume.py). The trained model is still a stub.

  • aqi_forecast.py — background PM2.5 plus plume smoke per horizon, converted to AQI.

  • tools.py and mcp.py — JSON tool handlers (forecast_smoke, forecast_smoke_aqi, pm25_to_aqi). The CLI uses the same forecast function. Milestone 3 is an MCP server over these handlers, not a second copy of the science.

Data sources, and the terms they ask users to keep:

Challenges we ran into

FIRMS does not have a separate ultra-real-time URL. URT and RT rows ride inside the NRT products and disappear once the NRT detection is processed, so the client has to read the version field.

Adding FRP from NOAA-21, NOAA-20, S-NPP, and MODIS for the same flame double-counts the fire. Lower-priority satellites only contribute hotspots that are not already next to a kept detection.

A back-trajectory that is scored by "distance from the fire to the nearest point, including the person" makes every nearby fire look upwind. The score only counts a fire when the upwind path actually gets closer to it. Fires within 5 km still count, because the people are already there.

Wind direction cannot be averaged in degrees. 350° and 10° would become south. Gaps are filled in east/north components.

The four feeds fail independently, and some need keys. The forecast has to keep a partial answer, say which source died, and refuse to print a confident score when the fires or the arrival wind never arrived.

Accomplishments

Milestone 1 runs end to end. The package installs, the CLI defaults to live data, and tests replay recorded fixtures so CI never hits the network. A live Open-Meteo call returns current 10 m wind, 850 hPa wind, and boundary-layer height without a key. FIRMS, AirNow, and OpenAQ run the same path when their keys are set; without those keys the CLI says which variable is missing and still prints the wind.

Quality checks remove low-confidence detections, bad coordinates, negative FRP, and MODIS hotspots that are not vegetation fires. Clusters are FRP-weighted. The hourly score responds to upwind versus downwind, to FRP, and to a shallower boundary layer. Short wind gaps are interpolated and flagged. Longer gaps and a dead feed are called out. The PM2.5 breakpoint table matches the 2024 EPA cut points, including values above AQI 500.

What we learned

The useful product at this stage is not a chart of raw hotspots. It is a sentence about whether those hotspots are lined up with the wind that will blow over a particular person, plus the monitor reading they can compare it with.

A uniform wind at one point is enough to make upwind and downwind differ sharply, and it is not enough to claim a concentration. Keeping that distinction in the output matters more than a more complicated formula.

Feeds that look like one API are several products. VIIRS NOAA-21 can be up while S-NPP is not, and an empty Landsat file over the ocean is a success, not an outage. The code has to tell those apart.

What's next

Milestone 2 trains a PM2.5 model on the smoke score plus monitor observations, with a time-based split and a persistence baseline. predict_pm25 raises until that exists. The breakpoint function stays the way a concentration becomes an AQI.

The MCP server is in place: an agent calls forecast_smoke and pm25_to_aqi over stdio or streamable HTTP. Milestone 2 is still the trained PM2.5 model. What remains of milestone 3 is a map and an hourly chart that call those same tools. See docs/roadmap.md and docs/methodology.md.

How Grok Bot helped build it

Dina Safreno and Dani Abay described the idea to Grok Bot: predict AQI for a location from NASA FIRMS fire detections and forecast winds. Dina and Dani made the product decisions (the idea, the California focus, the MCP direction, and the Most Technically Complex track) and reviewed and merged the pull requests. Grok Bot did the research, the project brief, and the agent work below. It can also call WildFireBot itself over MCP. See Grok Bot.

Planning. Grok Bot researched the data sources: the NASA FIRMS area API for MODIS, VIIRS NOAA-20, VIIRS NOAA-21, and Landsat; Open-Meteo winds at 10 m and about 850 hPa plus boundary-layer height; AirNow and OpenAQ PM2.5; and the EPA PM2.5-to-AQI breakpoints. It proposed the pipeline: FRP-weighted fire clusters, smoke transport along forecast winds, a PM2.5 model, then AQI.

Open-source structure. Grok Bot proposed the repository layout and the milestones, and wrote the brief that encodes the track's criteria: data depth, real current data, and robustness (satellite-source fallback, low-confidence filtering, retries, a cache with staleness warnings, missing-wind-hour flags, and live data by default).

Code. Grok Bot connected GitHub and launched a Cursor cloud agent on this repository, steering it across these pull requests:

Testing. Grok Bot installed the package fresh on its own computer, ran live CLI forecasts for the Bay Area and Los Angeles, and confirmed degraded mode when keys were missing. It found that the MCP server was still a placeholder and had it built for real, then verified the tools with a real MCP client: pm25_to_aqi(55) returned AQI 149, Unhealthy for Sensitive Groups.

The redacted session export is in grok history.

How to run it

Requires Python 3.11 or newer (python3 --version). On macOS the system python3 may be older; use brew install python@3.12 or uv python install 3.12.

git clone https://github.com/nycbagel/WildFireBot && cd WildFireBot
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Open-Meteo needs no key. The others do:

The CLI reads .env without overriding variables that are already set.

aqi-smoke forecast --lat 37.8 --lon -122.3 --hours 48
aqi-smoke aqi --lat 37.8 --lon -122.3            # plume AQI forecast, add --json for tool output

wildfirebot forecast is the same command. The default is live data. With only Open-Meteo reachable you still get the wind summary, and DEGRADED MODE names the fire and monitor feeds that were skipped. Responses are cached under ~/.cache/wildfirebot. --refresh skips a fresh cache. A stale cache is used only when the live feed fails, and the age is printed.

Tests and lint:

ruff check .
ruff format --check .
pytest

--fixture-dir tests/fixtures/cli replays recorded responses for development. It is not the default, and the banner says so. Do not commit raw downloads or .env.

This is an estimate of relative smoke exposure from satellite detections and forecast wind. It is not a health advisory and not a substitute for AirNow or local guidance.

Use with your AI agent

Quickest: use the hosted server (no keys)

A public instance is running at https://wildfirebot.onrender.com/mcp. No API keys and no token are needed, and there is nothing to install. It is rate limited to 60 requests per minute per IP. It runs on Render's free tier, which sleeps when idle, so the first call after a quiet period can take about a minute.

Cursor (~/.cursor/mcp.json) and other JSON configs:

{
  "mcpServers": {
    "wildfirebot": {
      "url": "https://wildfirebot.onrender.com/mcp"
    }
  }
}

Claude Code:

claude mcp add --transport http wildfirebot https://wildfirebot.onrender.com/mcp

OpenAI Codex:

codex mcp add wildfirebot --url https://wildfirebot.onrender.com/mcp

Claude Desktop only launches local servers from its config file, so bridge with mcp-remote (no header needed):

{
  "mcpServers": {
    "wildfirebot": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://wildfirebot.onrender.com/mcp"]
    }
  }
}

Grok Bot: paste "Add a custom MCP server named wildfirebot at https://wildfirebot.onrender.com/mcp" into a chat.

Try: "What will the smoke AQI be in Oakland over the next 24 hours?"

Run your own copy (needs your own API keys)

The sections below run the server on your machine or host it yourself. API keys are optional for users of the hosted server above; you only need them to run your own copy.

The MCP server is wildfirebot-mcp. Stdio is the default when you run it yourself. No clone is required once uv is installed (install uv):

uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

Keys:

Open-Meteo needs no key. If a key is missing, the tool result says so under notices and degraded instead of crashing. Every forecast includes a disclaimer: the score is a relative exposure index, not an official AQI and not a health advisory.

The tools are forecast_smoke (lat, lon, hours default 48, radius_km default 250, days default 2, lookback_hours default 12), forecast_smoke_aqi (Gaussian plume PM2.5 and EPA AQI), and pm25_to_aqi (concentration).

A prompt to try in any of the clients below: "What will the smoke AQI be in Oakland over the next 24 hours?"

Claude Desktop, Cursor, and other JSON configs (local, your own keys)

{
  "mcpServers": {
    "wildfirebot": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nycbagel/WildFireBot",
        "wildfirebot-mcp"
      ],
      "env": {
        "FIRMS_MAP_KEY": "your-firms-map-key",
        "AIRNOW_API_KEY": "your-airnow-key",
        "OPENAQ_API_KEY": "your-openaq-key"
      }
    }
  }
}

Needs uv on PATH. FIRMS_MAP_KEY is the fire feed. The AirNow and OpenAQ keys are optional.

Claude Code

Requires the Claude Code CLI and uv. FIRMS_MAP_KEY is required for fire data. Add AIRNOW_API_KEY and OPENAQ_API_KEY the same way if you have them.

Local scope is the default: private to you, and only the project you are in. -e is the short form of --env. Everything after -- is the server command, so Claude Code does not treat uvx flags as its own:

claude mcp add wildfirebot -e FIRMS_MAP_KEY=your-firms-map-key -- uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

Optional keys are more -e flags, before --:

claude mcp add wildfirebot \
  -e FIRMS_MAP_KEY=your-firms-map-key \
  -e AIRNOW_API_KEY=your-airnow-key \
  -e OPENAQ_API_KEY=your-openaq-key \
  -- uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

--scope (-s) chooses where that entry is stored:

Scope

Flag

Where it loads

Stored in

Local (default)

--scope local

This project, only you

~/.claude.json (under this project's path)

User

--scope user

All of your projects, only you

~/.claude.json (top-level mcpServers)

Project

--scope project

This project, shared with the team

.mcp.json in the project root

User scope, still private, for every project:

claude mcp add --scope user wildfirebot -e FIRMS_MAP_KEY=your-firms-map-key -- uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

Project scope writes .mcp.json and is meant to be committed. Do not put a real key in that command. Add the command without -e, then put the key only in a copy that stays off git, or keep the key in local or user scope.

The same project file, written by hand:

{
  "mcpServers": {
    "wildfirebot": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nycbagel/WildFireBot",
        "wildfirebot-mcp"
      ],
      "env": {
        "FIRMS_MAP_KEY": "your-firms-map-key"
      }
    }
  }
}

Claude Code reads .mcp.json when a session starts. The first time it sees a project server it asks you to approve it, because a cloned repo must not launch a process without consent. If you dismissed that prompt, run claude mcp reset-project-choices and start Claude Code again.

Check the connection from the shell. Added ... only means the entry was saved. The first claude mcp list can show ✘ Failed to connect while uvx downloads the package; run it again and look for ✔ Connected. A project server you have not approved yet shows ⏸ Pending approval (run claude to approve).

claude mcp list
claude mcp get wildfirebot

Inside a Claude Code session, /mcp shows the same status and the tool list. Restart the session after you edit .mcp.json.

Try: "What will the smoke AQI be in Oakland over the next 24 hours?"

OpenAI Codex (CLI and IDE)

Requires the Codex CLI and uv. The CLI, the IDE extension, and the ChatGPT desktop app share ~/.codex/config.toml. FIRMS_MAP_KEY is required for fire data. Repeat --env for each optional key. The official flag is --env, not -e.

codex mcp add wildfirebot --env FIRMS_MAP_KEY=your-firms-map-key -- uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

With the optional monitor keys:

codex mcp add wildfirebot \
  --env FIRMS_MAP_KEY=your-firms-map-key \
  --env AIRNOW_API_KEY=your-airnow-key \
  --env OPENAQ_API_KEY=your-openaq-key \
  -- uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp

The same entry in ~/.codex/config.toml (or a project-scoped .codex/config.toml, which Codex loads only after you trust the project):

[mcp_servers.wildfirebot]
command = "uvx"
args = ["--from", "git+https://github.com/nycbagel/WildFireBot", "wildfirebot-mcp"]

[mcp_servers.wildfirebot.env]
FIRMS_MAP_KEY = "your-firms-map-key"
AIRNOW_API_KEY = "your-airnow-key"
OPENAQ_API_KEY = "your-openaq-key"

In the IDE extension: open the gear menu, select MCP servers, select Add server, choose STDIO, and enter the same command. Save, then select Restart extension.

Verify from the shell with codex mcp list. In the Codex terminal UI, /mcp lists the active servers.

Try: "What will the smoke AQI be in Oakland over the next 24 hours?"

Grok Bot

Grok Bot adds a custom MCP server when you ask it in chat. It runs the server on its own computer. Paste this into a Grok Bot chat:

Add a custom MCP server named wildfirebot that runs uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp, with env FIRMS_MAP_KEY set to my key.

uv has to be available on the computer Grok Bot uses. FIRMS_MAP_KEY is required for fire data. Mention AIRNOW_API_KEY and OPENAQ_API_KEY in the same message if you want those monitors. Grok Bot asks for the key securely rather than taking it in plain chat, confirms, then starts the server.

If you are already hosting the server, give Grok Bot that HTTPS URL instead of the uvx command. Run wildfirebot-mcp --http (see below) and put HTTPS in front of it before sharing the URL.

Try: "What will the smoke AQI be in Oakland over the next 24 hours?"

Host it at a URL

Streamable HTTP serves the same tools. The local MCP endpoint is http://127.0.0.1:8000/mcp:

uvx --from git+https://github.com/nycbagel/WildFireBot wildfirebot-mcp --http --port 8000

--host defaults to 127.0.0.1. The tools are forecast_smoke (lat, lon, hours default 48, radius_km default 250, days default 2, lookback_hours default 12), forecast_smoke_aqi (Gaussian plume PM2.5 and EPA AQI), and pm25_to_aqi (concentration).

Claude Code adds that URL with claude mcp add --transport http wildfirebot https://your-host.example/mcp. Codex adds it with codex mcp add wildfirebot --url https://your-host.example/mcp, or with url = "https://your-host.example/mcp" under [mcp_servers.wildfirebot] instead of command and args.

Hosted server (no API keys for users)

The live instance at https://wildfirebot.onrender.com/mcp is deployed on Render as a Docker web service. Both the Blueprint path and the plain Web Service path (language Docker, health check path /health) work. WFB_ACCESS_TOKEN is optional, and the public instance currently runs without it, so it is open with only the rate limit.

Run the MCP server once with the operator's keys, and everyone else connects by URL. The keys stay in the host's environment and are never sent to clients.

Environment variables

Variable

Purpose

FIRMS_MAP_KEY, AIRNOW_API_KEY

Operator's keys (set as host secrets, never commit them)

PORT

Set by the host. When present the server serves HTTP on 0.0.0.0:$PORT at /mcp

WFB_ACCESS_TOKEN

Optional. If set, clients must send Authorization: Bearer <token>. If unset the server is open

WFB_RATE_LIMIT / WFB_RATE_WINDOW_S

Requests per client IP per window (default 60 per 60 s, 0 disables)

GET /health returns {"status":"ok"} without auth, for host health checks.

Deploy on Render: create a Render account, choose New > Blueprint, and point it at this repo (render.yaml). Paste FIRMS_MAP_KEY and AIRNOW_API_KEY when prompted, plus WFB_ACCESS_TOKEN if you want to require a token. The endpoint is https://<service>.onrender.com/mcp. The free tier sleeps when idle, so the first call can take about a minute.

Deploy on Fly.io: fly launch --copy-config --no-deploy, then fly secrets set FIRMS_MAP_KEY=... AIRNOW_API_KEY=... WFB_ACCESS_TOKEN=..., then fly deploy.

Any Docker host: docker build -t wildfirebot-mcp . then docker run -p 8000:8000 -e PORT=8000 -e FIRMS_MAP_KEY -e AIRNOW_API_KEY -e WFB_ACCESS_TOKEN wildfirebot-mcp.

Connect to your own self-hosted server (templates). Replace YOUR-HOST. Omit the headers line if you did not set WFB_ACCESS_TOKEN. For the public instance, use the quick setup above instead. Cursor (~/.cursor/mcp.json) or Claude Code:

{
  "mcpServers": {
    "wildfirebot": {
      "url": "https://YOUR-HOST/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Claude Desktop (self-host template with a token) bridges with mcp-remote:

{
  "mcpServers": {
    "wildfirebot": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://YOUR-HOST/mcp", "--header", "Authorization: Bearer ${WFB_TOKEN}"],
      "env": { "WFB_TOKEN": "YOUR_TOKEN" }
    }
  }
}

Available Tools

3 tools
forecast_smokeA

Estimate relative wildfire smoke exposure at one latitude and longitude from NASA FIRMS fire detections and an Open-Meteo wind forecast. Returns nearby fire clusters, a wind summary, an hourly smoke-exposure score, nearby PM2.5 readings when monitors respond, degraded-mode notices, and a disclaimer. The score is a relative exposure index, not an official AQI and not a health advisory. Reads FIRMS_MAP_KEY, AIRNOW_API_KEY, and OPENAQ_API_KEY from the environment. A missing key is named in notices; the server keeps running.

Inputs: lat (required), lon (required), days, hours, +2 more. Returns: object

forecast_smoke_aqiA

Forecast PM2.5 and the US EPA AQI at one latitude and longitude. Adds a Gaussian plume from each NASA FIRMS fire cluster, using fire radiative power and the Open-Meteo wind forecast, on top of Open-Meteo's background PM2.5. Works for a new fire because it does not need a history of observations. Returns horizons, degraded-mode notices, and a disclaimer. This is a screening estimate, not an official AQI and not a health advisory. Missing FIRMS_MAP_KEY, AIRNOW_API_KEY, or OPENAQ_API_KEY is reported in notices.

Inputs: lat (required), lon (required), days, radius_km, +3 more. Returns: object

pm25_to_aqiA

Convert one PM2.5 concentration in micrograms per cubic meter to the US EPA 2024 AQI with the breakpoint equation. Does not compute a 24-hour average or a NowCast. The result includes the AQI, the category, and a disclaimer that this is not a health advisory.

Inputs: concentration (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 3 tools

    Disambiguation4/5

    The three tools target distinct outputs: relative smoke exposure, unit conversion, and PM2.5/AQI forecasting. The two forecast tools share similar names and inputs, but their descriptions clearly separate a relative exposure index from a concentration-and-AQI plume estimate. An agent could still briefly hesitate between forecast_smoke and forecast_smoke_aqi, so it is not perfectly crisp.

    Naming Consistency4/5

    All names use consistent snake_case and readable domain terms. The patterns are not strictly identical: forecast_smoke and forecast_smoke_aqi are verb_noun forms, while pm25_to_aqi is a conversion-style name. This is a minor deviation, not a confusing mix of conventions.

    Tool Count5/5

    Three tools is lean but well matched to a focused smoke-exposure and AQI screening server. Each tool covers a distinct operation, and there are no redundant or filler tools. The surface is intentionally narrow rather than under-scoped.

    Completeness4/5

    The core workflow is covered: estimate smoke exposure, forecast PM2.5/AQI, and convert PM2.5 to AQI. Minor gaps exist, such as no direct tool to inspect raw FIRMS clusters or retrieve standalone PM2.5 observations, but agents can still complete the main screening tasks. These gaps are workable rather than blocking.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers