Us Drought Monitor Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.2.0Updated Oct 26, 2026

Query U.S. Drought Monitor severity, DSCI, population, and drought duration.

VerifiedStreamable HTTPWeb executableLocation & LifestyleData & Analytics

Overview

AI-generated overview

Queries U.S. Drought Monitor data: current and historical drought severity, DSCI, population, rankings and county drought durations.

What you can do
  • Look up drought categories, DSCI formulas, coverage and exact geography identifiers for states, counties, HUC watersheds, tribal areas, climate divisions and River Forecast Centers
  • Get current or dated severity snapshots with area percentages, square miles, population counts and DSCI with 4- and 52-week changes
  • Pull weekly time series for up to 100 areas, with missing-data runs and peak summaries
  • Rank states or counties by DSCI or D2+/D3+ coverage, optionally as change from a baseline week
  • Count consecutive or non-consecutive weeks a county has been in drought at a chosen category or worse
  • Stage large results as tables and inspect or page them with read-only DuckDB SQL
When to use it
Useful when you need authoritative U.S. drought statistics for reporting, research or regional comparisons, such as current conditions for a county, drought trends over time, or rankings of states and counties. It is a data retrieval and analysis tool, not an eligibility or advisory service.
Requirements
Either the hosted remote endpoint or a local process via npx (Node.js) or Docker; no API key or account is required. Outbound network access to the upstream USDM data services is needed. Optional environment variables control transport, HTTP host/port/path, auth mode, log level, limit clamping and staging behaviour; staging and SQL need native DuckDB, which is included in npm and Docker installs.
Before you install
Read-only against upstream data, but staged canvas tokens are described as shareable capabilities that expire and should be treated as credentials. The opt-in drought_dataframe_drop tool removes staged tables when DROUGHT_DATAFRAME_DROP_ENABLED is true. DSCI is an experimental upstream index, population figures are rough census-based estimates, and drought durations do not establish program eligibility. Setting MCP_AUTH_MODE to jwt or oauth requires configuring credentials.

Installation

In SourceWeft

  1. Open Us Drought Monitor 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%2Fus-drought-monitor-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": {
    "us-drought-monitor": {
      "type": "http",
      "url": "https://us-drought-monitor.caseyjhand.com/mcp"
    }
  }
}

README

@cyanheads/us-drought-monitor-mcp-server

Query U.S. Drought Monitor severity, DSCI, population, and drought duration via MCP. STDIO or Streamable HTTP.

8 Tools (1 opt-in)

Overview

Weekly drought statistics from the U.S. Drought Monitor (USDM) data services. Snapshot an area's current or dated severity, follow weekly history, rank states and counties, and count county weeks in drought across national, state, county, HUC watershed, tribal, climate-division and River Forecast Center geographies. Large results stage as tables for read-only SQL. No API key is required.

The caller guide covers interpretation and complete analytical retrieval; the server also serves it as a skill resource.

Tools

ToolDescription
drought_list_referenceBrowse drought categories, DSCI formulas, coverage and exact geography identifiers
drought_get_current_severityCurrent or dated snapshot with area, square miles, population, DSCI and 4/52-week DSCI change
drought_get_timeseriesWeekly metrics and DSCI for explicit areas, with missing-data runs and peak summaries
drought_compare_areasRank states or counties by DSCI or D2+/D3+ coverage, or by change from a baseline week
drought_get_weeks_in_droughtCounty consecutive streaks or non-consecutive week counts at a drought category or worse
drought_dataframe_describeInspect a staged canvas: tables, columns, expiry and full producer metadata
drought_dataframe_queryPage read-only SQL over staged drought tables
drought_dataframe_dropRemove one disposable staged table; opt-in via DROUGHT_DATAFRAME_DROP_ENABLED=true

Capability reference

drought_list_reference tool

  • topic: categories, dsci, area_types, coverage, states, counties, tribal, climate_divisions, river_forecast_centers or huc; nameContains token filter, state for counties or climate divisions, hucLevel (2, 4, 6 or 8) required for huc. Optional parentHuc selects descendants of an existing shorter HUC at level 2, 4 or 6
  • Default 25 records per page, clamped to 200; continued via nextCursor with unchanged filters. Explicit pages return the effective count, fewer only at exhaustion; totalCount counts every match
  • Records keep leading-zero identifiers, climate-state postal codes and source vintages; bundleVersion and topic-dependent sourceMetadata (source URLs and SHA-256 hashes) date the offline bundle. provenance.sourceUrls uses the same source selection

drought_get_current_severity tool

  • One area (areaType + aoi, plus hucLevel for HUC; aoi takes an exact identifier or exact state or "County Name, ST" name); unique suffix-free county names such as "King, WA" are accepted after exact-name matching. Optional date defaults to the latest published map; us selects both CONUS and Total
  • Each snapshot carries cumulative and categorical area percent, cumulative square miles, cumulative population (populationStatus unsupported outside US/state/county), dsci, and dsciChange4Weeks / dsciChange52Weeks against exactly 28 and 364 days earlier, each with an available / missing / before_coverage status
  • A date outside published coverage returns found: false with guidance
  • River Forecast Centers use areaType: "river_forecast_center" with an official code (for example CBRFC) or exact name (Colorado Basin); area percentages, square miles and DSCI are supported. Unknown RFCs fail local reference resolution

drought_get_timeseries tool

  • 1–100 areas sharing one areaType and HUC level; inclusive startDate / endDate; metric area_percent (default), area_sq_miles, population_percent or population_count (US/state/county only); statisticsType cumulative (default) or categorical
  • Rows carry the metric buckets plus dsci; missingAreas, missingObservations (date runs per metric and DSCI component) and per-area summary (every tied peak) cover the complete series
  • Rows past the inline budget stage behind a preview, with the table in staging; optional canvas_id stages into an existing canvas. Metadata remains complete inline whenever it fits. Overflow automatically retains complete rows and metadata, including zero-observation results; metadata_pages gives each array's total, returned count and next offset

drought_compare_areas tool

  • scope states or counties (optional state, else nationwide); metric dsci (default), d2_d4 or d3_d4; optional date (default latest) and baselineDate to rank the change; direction desc (default) or asc
  • Competition ranks share ties; excludedAreas names each area missing its target or baseline value; changeUnit is index or percentage_points
  • limit (default 20, clamped to 200) sizes the inline preview; the complete ranking stages, with optional canvas_id reuse

drought_get_weeks_in_drought tool

  • startDate, endDate, minCategory (D0–D4) and minWeeks required; mode consecutive (default) or non_consecutive; states or one county, never both, or neither for nationwide counties
  • Rows give fips, county, state, and either startDate / endDate / consecutiveWeeks or nonConsecutiveWeeks; a county qualifies when any part of it reaches the category or worse, and streaks are bounded by the requested window
  • Consecutive startMayExtendEarlier and endMayContinue flag boundaries touching the effective window; they express uncertainty about continuation. The Monday end is compared with the final map Tuesday plus six days. Non-consecutive rows omit these flags
  • Default 25 rows per page, clamped to 200; nextCursor stays valid five minutes with unchanged filters. Explicit pages return the effective count, fewer only at exhaustion. Counts are duration statistics, not program eligibility

drought_dataframe_describe tool

  • canvas_id from a staging response; tables with SQL column types, row counts and expiry
  • With table_name, that table's full producer metadata: requested and effective ranges, units, bucket-column mapping, missing data, summaries and provenance
  • Oversized metadata returns first-page prefixes with metadata_pages. To read a complete retained collection, supply table_name, metadata_field (areas, summary, missingAreas, missingObservations), metadata_offset and metadata_limit (default 20, clamped to 100); follow metadata_page.next_offset until null. Explicit pages return the effective count, fewer only at exhaustion, from the same snapshot without fetching upstream again

drought_dataframe_query tool

  • canvas_id plus one DuckDB read expression with an optional terminal semicolon; writes, multiple statements, external reads and system catalogs are refused
  • A column named current_schema must be table-qualified (t.current_schema); unqualified references are refused because DuckDB can bind them as an engine-settings function
  • limit (default 25, clamped to 500) and offset up to 250,000; continue next_offset with identical SQL until null. Explicit pages return the effective count, fewer only at exhaustion, regardless of cell width. SELECT * FROM <table_name> ORDER BY row_id returns the original rows in order
  • countIsExact is true only when one page from offset 0 holds every row; use SELECT COUNT(*) for totals

drought_dataframe_drop tool

  • canvas_id and table_name; removes the analytical copy only, returning dropped: false when the table is already gone; an expired canvas fails as canvas_not_found
  • Opt-in: absent from tools/list unless DROUGHT_DATAFRAME_DROP_ENABLED=true

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.

USDM-specific:

  • Fixed-origin client for the USDM data services (usdmdataservices.unl.edu): no key, at most 64 upstream requests and 64 MiB per call, three concurrent upstream requests, one retry that honors Retry-After
  • Dates snap to the containing Tuesday–Monday map week; coverage starts 2000-01-04, and the latest map (usually published Thursday) is discovered from upstream
  • Cumulative buckets (d1_d4 = D1 or worse) overlap; categorical buckets (d1_only) are exclusive. DSCI is upstream's experimental 0–500 index, never recomputed
  • Offline geography bundle: 52 states and jurisdictions, 3,230 counties (Connecticut planning regions included), 323 tribal areas, 357 climate divisions, 13 River Forecast Centers and 2,916 HUCs, refreshed by scripts/update-reference-data.ts
  • Staged tables live in DuckDB with a 30-minute sliding lifetime renewed by queries; canvas tokens are tenant-scoped, shareable capabilities, so treat them as credentials
  • At the four-canvas process cap, omitted-token staging reuses the tenant's most recently used service-owned canvas with a free slot (eight tables per canvas). Explicitly supplied canvases remain caller-owned; live tables are never evicted. staging_capacity_exhausted advises token reuse or expiry, while staging_busy advises waiting for active work. The two-workflow admission bound applies before fetching, including inline reads
  • Connecticut's eight legacy county FIPS remain discoverable but are omitted from comparison populations. Their empty observation lookups explain that USDM serves Connecticut by planning region; call drought_list_reference with topic: counties, state: CT. Counties are never mapped onto different planning-region boundaries; currentUsdm: false alone is not a historical-coverage rule
  • Node acquisition uses a private reusable Undici HTTP/1.1 dispatcher, released during server teardown; Bun retains native fetch

Agent-friendly output:

  • Reference records, query rows and describe columns use compact tables with JSON cells; empty cells distinguish absent optional fields from null values. Metadata, nested values and clickable URLs remain complete on both response surfaces
  • Positive integer page/preview limits above 200 (references, comparisons, duration), 500 (SQL), or 100 (metadata) are clamped; effectiveLimit and limitNotice disclose the result. Set DROUGHT_CLAMP_LIMITS=false to advertise and enforce these maxima instead. Clamps emit a request log and the drought.limit_clamps counter. Continuation retains every record. Nonpositive and fractional limits are rejected; count ceilings do not bound response bytes
  • Date inputs advertise YYYY-MM-DD and validate real calendar dates; blank optional snapshot and comparison dates retain their defaults. A duration threshold beyond its window advises lowering minWeeks or widening the dates
  • Provenance on every response: sourceUrls, retrievedAt, the USDM credit line and the experimental-DSCI citation
  • Supported population snapshots and population series add provenance.populationInterpretation, retained through dataframe describe/query: USDM population figures are rough census-based estimates assuming uniform population within counties, with artificial precision rather than exact contemporary headcounts. Source values remain unchanged; no census vintage is inferred
  • Missing data stays explicit: nulls with dsciStatus / populationStatus, missingAreas, missingObservations date runs and excludedAreas, never zero-filled
  • Range and identity echo: requestedRange / effectiveRange, latestMapDate, resolvedAreas, and staging handles that name drought_dataframe_describe and drought_dataframe_query

Getting started

Connect to the hosted instance:

sh
claude mcp add --transport http us-drought-monitor-mcp-server https://us-drought-monitor.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add us-drought-monitor-mcp-server -- npx -y @cyanheads/us-drought-monitor-mcp-server

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

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

No API key or account is required. Set DROUGHT_DATAFRAME_DROP_ENABLED=true to expose table removal. For Docker or a source build, see Running the server.

Configuration

VariableDescriptionDefault
DROUGHT_DATAFRAME_DROP_ENABLEDExpose drought_dataframe_drop for disposable staged tables.false
DROUGHT_CLAMP_LIMITSClamp oversized positive limits; false advertises and enforces maxima.true
CANVAS_PROVIDER_TYPEAnalytical engine: duckdb, or none to disable staging and SQL.duckdb
CANVAS_DEFAULT_MEMORY_LIMIT_MBMemory limit per canvas engine.128
CANVAS_MAX_CANVASES_PER_TENANTProvider canvas cap; the server separately admits four live canvases per process.4
CANVAS_DEFAULT_ROW_LIMITProvider query row cap; at least 501 when the canvas is enabled.10000
CANVAS_TTL_MSSliding canvas lifetime, in ms; staged tables expire after 30 minutes without use.86400000
CANVAS_ABSOLUTE_CAP_MSAbsolute canvas lifetime, in ms.604800000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_HOSTHTTP bind address.127.0.0.1
MCP_HTTP_PORTHTTP server port.3010
MCP_HTTP_ENDPOINT_PATHHTTP endpoint path./mcp
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto.stateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
LOGS_DIRDirectory for log files (Node.js only).<app-root>/logs
OTEL_ENABLEDEnable OpenTelemetry.false

See .env.example for every server setting and the common framework overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

sh
git clone https://github.com/cyanheads/us-drought-monitor-mcp-server.gitcd us-drought-monitor-mcp-serverbun installcp .env.example .env# optional: set DROUGHT_DATAFRAME_DROP_ENABLED or canvas limits

Staging and SQL need native DuckDB, included in npm and Docker installs. The portable Claude Desktop .mcpb bundle fixes CANVAS_PROVIDER_TYPE=none: producers return complete inline results within acquisition limits. Explicit canvas tokens and dataframe operations still require an analytical provider; invalid, expired or foreign tokens never fall back to inline success.

  • Build and run the production version:

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

  • Run checks and tests:

    sh
    bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suite

Docker

sh
docker run --rm -p 127.0.0.1:3010:3010 ghcr.io/cyanheads/us-drought-monitor-mcp-server:latest

The image runs on Bun with native DuckDB, defaults to HTTP on port 3010 in stateless session mode, and logs to /var/log/us-drought-monitor-mcp-server. OpenTelemetry peer dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit them.

To build locally, run docker build -t us-drought-monitor-mcp-server .. For stdio clients, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/us-drought-monitor-mcp-server:latest"].

Project structure

DirectoryPurpose
src/mcp-server/toolsTool definitions (*.tool.ts). Eight drought and dataframe tools.
src/services/droughtUSDM client, geography resolution, map-week dates, workflows, staging and rendering.
src/services/canvas-accessor.tsAccess to the framework DataCanvas configured at startup.
src/configEnvironment loading, canvas defaults, count schemas and clamp telemetry.
src/dataGenerated geography reference bundle (reference.json).
scripts/update-reference-data.tsMaintainer refresh of the reference bundle from official sources.
tests/Unit, contract and integration tests, mirroring the src/ structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Service errors carry the reason declared in each tool's inline errors[] contract
  • Register new tools in the createApp() arrays 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

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

The U.S. Drought Monitor is jointly produced by the National Drought Mitigation Center at the University of Nebraska-Lincoln, the United States Department of Agriculture, the National Oceanic and Atmospheric Administration and the National Aeronautics and Space Administration. Map courtesy of NDMC.

DSCI: Akyuz, F. A. 2017. Drought Severity and Coverage Index. United States Drought Monitor.

Source: README.md at commit fcb98a2

Tools

7

drought_list_reference

Look up drought reference data

Look up drought categories, DSCI formulas, metric support, publication coverage and exact geography identifiers. Filter complete families by nameContains before paging. Use state for counties or climate_divisions; huc requires hucLevel 2, 4, 6 or 8 and accepts a shorter parentHuc. Follow nextCursor with the same filters to browse every match.

ParameterslimitstatetopicrequiredcursorhucLevelparentHucnameContains

drought_get_current_severity

Get a drought severity snapshot

Get current or dated drought severity, cumulative and categorical area percentages, area square miles, supported population counts and experimental upstream DSCI. Resolve identifiers with drought_list_reference. DSCI changes use exactly 4 and 52 weeks earlier; missing observations remain null. US selects both CONUS and Total.

Parametersarearequireddate

drought_get_timeseries

Get weekly drought observations

Get weekly drought metrics and experimental DSCI for 1–100 explicit areas sharing one geography type and HUC level. Resolve identifiers with drought_list_reference. Dates select inclusive Tuesday map weeks. Missing values remain null; summaries include every tied peak. Large results are staged when analytics is enabled; use the returned dataframe tools to read every row and retained metadata page. Without analytics, complete results remain inline within acquisition limits.

ParametersareasrequiredmetricendDaterequiredcanvas_idstartDaterequiredstatisticsType

drought_compare_areas

Compare drought severity across areas

Rank all supported states, or counties within an optional state, on one published map. Omit state for nationwide supported counties. With baselineDate, rank target minus exact baseline; missing sides are excluded explicitly. Equal values share competition rank. limit controls a staged preview; without analytics, complete rankings remain inline within acquisition limits.

Takes no parameters.

drought_get_weeks_in_drought

Get county weeks in drought

Get authoritative consecutive streaks or non-consecutive week counts when any county area meets the selected drought category or worse. Supply states or one county, never both; omitted selectors mean supported nationwide counties. Counts are duration statistics, not program eligibility. Follow nextCursor with unchanged filters within five minutes.

ParametersmodelimitcountycursorstatesendDaterequiredminWeeksrequiredstartDaterequiredminCategoryrequired

drought_dataframe_query

Query staged drought data

Run one DuckDB read expression against staged drought tables, optionally ending with one semicolon. Get canvas_id from drought_get_timeseries or drought_compare_areas and inspect columns with drought_dataframe_describe. For every original row, SELECT * FROM the table ORDER BY row_id and follow next_offset until null. Arbitrary SQL pagination requires your own stable ORDER BY. Exact totals require SELECT COUNT(*).

Parameterssqlrequiredlimitoffsetcanvas_idrequired

drought_dataframe_describe

Describe staged drought tables

Inspect tables and column types in a canvas_id returned by drought_get_timeseries or drought_compare_areas. Supply table_name for its complete source query, area/date/metric, units, missing-data and provenance metadata. Omit table_name for bounded schema summaries. Tokens are shareable capabilities and expire; this tool never lists other tokens.

Parameterscanvas_idrequiredtable_namemetadata_fieldmetadata_limitmetadata_offset

Version history

4
  1. v0.2.0LatestOct 26, 2026
  2. v0.1.3Oct 24, 2026
  3. v0.1.2Oct 20, 2026
  4. v0.1.1Oct 20, 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