us-drought-monitor-mcp-server

v0.1.3 pre-1.0

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

us-drought-monitor.caseyjhand.com/mcp
claude mcp add --transport http us-drought-monitor-mcp-server https://us-drought-monitor.caseyjhand.com/mcp
codex mcp add us-drought-monitor-mcp-server --url https://us-drought-monitor.caseyjhand.com/mcp
{
  "mcpServers": {
    "us-drought-monitor-mcp-server": {
      "url": "https://us-drought-monitor.caseyjhand.com/mcp"
    }
  }
}
gemini mcp add --transport http us-drought-monitor-mcp-server https://us-drought-monitor.caseyjhand.com/mcp
{
  "mcpServers": {
    "us-drought-monitor-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://us-drought-monitor.caseyjhand.com/mcp"
      ]
    }
  }
}
{
  "mcpServers": {
    "us-drought-monitor-mcp-server": {
      "type": "http",
      "url": "https://us-drought-monitor.caseyjhand.com/mcp"
    }
  }
}
curl -X POST https://us-drought-monitor.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Tools

8

read 7

drought_list_reference

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.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_list_reference",
    "arguments": {
      "topic": "<topic>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "enum": [
        "categories",
        "dsci",
        "area_types",
        "coverage",
        "states",
        "counties",
        "tribal",
        "climate_divisions",
        "huc"
      ],
      "description": "Reference family to browse."
    },
    "nameContains": {
      "description": "All normalized tokens must appear in the reference name.",
      "type": "string",
      "maxLength": 200
    },
    "state": {
      "description": "County or climate-division filter: exact state postal code, two-digit FIPS or full name.",
      "type": "string",
      "maxLength": 200
    },
    "hucLevel": {
      "description": "Required for huc; exact identifier width.",
      "anyOf": [
        {
          "type": "number",
          "const": 2
        },
        {
          "type": "number",
          "const": 4
        },
        {
          "type": "number",
          "const": 6
        },
        {
          "type": "number",
          "const": 8
        }
      ]
    },
    "parentHuc": {
      "description": "Existing parent HUC at level 2, 4 or 6, shorter than hucLevel; blank is omitted.",
      "type": "string",
      "maxLength": 6
    },
    "cursor": {
      "description": "Continuation cursor from the previous page with the same filters.",
      "type": "string",
      "maxLength": 2048
    },
    "limit": {
      "default": 50,
      "description": "Maximum records on this page; values above 200 are clamped with disclosure.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "topic",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

drought_get_current_severity

open-world

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.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_get_current_severity",
    "arguments": {
      "area": "<area>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "area": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "us",
              "description": "National geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            }
          },
          "required": [
            "areaType",
            "aoi"
          ],
          "additionalProperties": false,
          "description": "National coverage selector."
        },
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "state",
              "description": "State geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            }
          },
          "required": [
            "areaType",
            "aoi"
          ],
          "additionalProperties": false,
          "description": "Exact state selector."
        },
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "county",
              "description": "County geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            }
          },
          "required": [
            "areaType",
            "aoi"
          ],
          "additionalProperties": false,
          "description": "Exact county selector."
        },
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "tribal",
              "description": "Tribal geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            }
          },
          "required": [
            "areaType",
            "aoi"
          ],
          "additionalProperties": false,
          "description": "Exact tribal selector."
        },
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "climate_division",
              "description": "Climate division geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            }
          },
          "required": [
            "areaType",
            "aoi"
          ],
          "additionalProperties": false,
          "description": "Exact climate division selector."
        },
        {
          "type": "object",
          "properties": {
            "areaType": {
              "type": "string",
              "const": "huc",
              "description": "Watershed geography."
            },
            "aoi": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
            },
            "hucLevel": {
              "anyOf": [
                {
                  "type": "number",
                  "const": 2
                },
                {
                  "type": "number",
                  "const": 4
                },
                {
                  "type": "number",
                  "const": 6
                },
                {
                  "type": "number",
                  "const": 8
                }
              ],
              "description": "Exact HUC identifier width."
            }
          },
          "required": [
            "areaType",
            "aoi",
            "hucLevel"
          ],
          "additionalProperties": false,
          "description": "Exact watershed selector with matching HUC width."
        }
      ],
      "description": "One exact geography selector."
    },
    "date": {
      "description": "Calendar date YYYY-MM-DD; defaults to latest published map.",
      "type": "string",
      "maxLength": 10,
      "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
    }
  },
  "required": [
    "area"
  ],
  "additionalProperties": false
}
view source ↗

drought_get_timeseries

open-world

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. Complete large results are staged; use the returned dataframe tools to read every row.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_get_timeseries",
    "arguments": {
      "areas": "<areas>",
      "startDate": "<startDate>",
      "endDate": "<endDate>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "areas": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "us",
                "description": "National geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              }
            },
            "required": [
              "areaType",
              "aoi"
            ],
            "additionalProperties": false,
            "description": "National coverage selector."
          },
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "state",
                "description": "State geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              }
            },
            "required": [
              "areaType",
              "aoi"
            ],
            "additionalProperties": false,
            "description": "Exact state selector."
          },
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "county",
                "description": "County geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              }
            },
            "required": [
              "areaType",
              "aoi"
            ],
            "additionalProperties": false,
            "description": "Exact county selector."
          },
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "tribal",
                "description": "Tribal geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              }
            },
            "required": [
              "areaType",
              "aoi"
            ],
            "additionalProperties": false,
            "description": "Exact tribal selector."
          },
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "climate_division",
                "description": "Climate division geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              }
            },
            "required": [
              "areaType",
              "aoi"
            ],
            "additionalProperties": false,
            "description": "Exact climate division selector."
          },
          {
            "type": "object",
            "properties": {
              "areaType": {
                "type": "string",
                "const": "huc",
                "description": "Watershed geography."
              },
              "aoi": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200,
                "description": "Exact geography identifier or state name; county names require a state and resolve exact names before unique suffix-free aliases."
              },
              "hucLevel": {
                "anyOf": [
                  {
                    "type": "number",
                    "const": 2
                  },
                  {
                    "type": "number",
                    "const": 4
                  },
                  {
                    "type": "number",
                    "const": 6
                  },
                  {
                    "type": "number",
                    "const": 8
                  }
                ],
                "description": "Exact HUC identifier width."
              }
            },
            "required": [
              "areaType",
              "aoi",
              "hucLevel"
            ],
            "additionalProperties": false,
            "description": "Exact watershed selector with matching HUC width."
          }
        ],
        "description": "One supported geography and its exact identifier."
      },
      "description": "Explicit homogeneous geographies."
    },
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First requested calendar date, YYYY-MM-DD."
    },
    "endDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last requested calendar date, YYYY-MM-DD."
    },
    "metric": {
      "default": "area_percent",
      "description": "Measure; population supports US, state and county only.",
      "type": "string",
      "enum": [
        "area_percent",
        "area_sq_miles",
        "population_percent",
        "population_count"
      ]
    },
    "statisticsType": {
      "default": "cumulative",
      "description": "Overlapping cumulative or exclusive categorical buckets.",
      "type": "string",
      "enum": [
        "cumulative",
        "categorical"
      ]
    },
    "canvas_id": {
      "description": "Canvas token from a previous drought producer to reuse when staging.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[A-Za-z0-9_-]{10}$",
          "description": "Canvas ID as an earlier response on this server returned it — exactly 10 characters of letters, digits, hyphens, and underscores."
        }
      ]
    }
  },
  "required": [
    "areas",
    "startDate",
    "endDate",
    "metric",
    "statisticsType"
  ],
  "additionalProperties": false
}
view source ↗

drought_compare_areas

open-world

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, never discards comparable rows.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_compare_areas",
    "arguments": {
      "scope": "states",
      "metric": "<metric>",
      "direction": "<direction>",
      "limit": "<limit>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "const": "states",
          "description": "All supported states."
        },
        "date": {
          "description": "Target calendar date; defaults to latest published map.",
          "type": "string",
          "maxLength": 10,
          "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
        },
        "baselineDate": {
          "description": "Optional exact baseline date, no later than target.",
          "type": "string",
          "maxLength": 10,
          "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
        },
        "metric": {
          "default": "dsci",
          "description": "Experimental DSCI or cumulative area percentage.",
          "type": "string",
          "enum": [
            "dsci",
            "d2_d4",
            "d3_d4"
          ]
        },
        "direction": {
          "default": "desc",
          "description": "Order by severity or baseline change.",
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "limit": {
          "default": 20,
          "description": "Preview row limit, clamped to 200 with disclosure; complete rankings remain staged.",
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        "canvas_id": {
          "description": "Canvas token from an earlier drought producer to reuse.",
          "anyOf": [
            {
              "type": "string",
              "const": ""
            },
            {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{10}$",
              "description": "Canvas ID as an earlier response on this server returned it — exactly 10 characters of letters, digits, hyphens, and underscores."
            }
          ]
        }
      },
      "required": [
        "scope",
        "metric",
        "direction",
        "limit"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "scope": {
          "type": "string",
          "const": "counties",
          "description": "Supported counties."
        },
        "state": {
          "description": "Exact state postal, FIPS or full name; omitted means nationwide.",
          "type": "string",
          "maxLength": 200
        },
        "date": {
          "description": "Target calendar date; defaults to latest published map.",
          "type": "string",
          "maxLength": 10,
          "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
        },
        "baselineDate": {
          "description": "Optional exact baseline date, no later than target.",
          "type": "string",
          "maxLength": 10,
          "pattern": "^(?:|\\d{4}-\\d{2}-\\d{2})$"
        },
        "metric": {
          "default": "dsci",
          "description": "Experimental DSCI or cumulative area percentage.",
          "type": "string",
          "enum": [
            "dsci",
            "d2_d4",
            "d3_d4"
          ]
        },
        "direction": {
          "default": "desc",
          "description": "Order by severity or baseline change.",
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ]
        },
        "limit": {
          "default": 20,
          "description": "Preview row limit, clamped to 200 with disclosure; complete rankings remain staged.",
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        "canvas_id": {
          "description": "Canvas token from an earlier drought producer to reuse.",
          "anyOf": [
            {
              "type": "string",
              "const": ""
            },
            {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{10}$",
              "description": "Canvas ID as an earlier response on this server returned it — exactly 10 characters of letters, digits, hyphens, and underscores."
            }
          ]
        }
      },
      "required": [
        "scope",
        "metric",
        "direction",
        "limit"
      ],
      "additionalProperties": false
    }
  ]
}
view source ↗

drought_get_weeks_in_drought

open-world

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.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_get_weeks_in_drought",
    "arguments": {
      "startDate": "<startDate>",
      "endDate": "<endDate>",
      "minCategory": "<minCategory>",
      "minWeeks": "<minWeeks>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "startDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "First requested date, YYYY-MM-DD."
    },
    "endDate": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Last requested date, YYYY-MM-DD."
    },
    "minCategory": {
      "description": "Minimum drought category.",
      "type": "string",
      "enum": [
        "D0",
        "D1",
        "D2",
        "D3",
        "D4"
      ]
    },
    "minWeeks": {
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991,
      "description": "Minimum weeks, no more than requested inclusive map weeks."
    },
    "mode": {
      "default": "consecutive",
      "description": "Window-bounded consecutive streaks or qualifying week counts.",
      "type": "string",
      "enum": [
        "consecutive",
        "non_consecutive"
      ]
    },
    "states": {
      "description": "Exact state postal, FIPS or full names; mutually exclusive with county.",
      "minItems": 1,
      "maxItems": 54,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 200
      }
    },
    "county": {
      "description": "County FIPS or exact/unique suffix-free county name, state; mutually exclusive with states.",
      "type": "string",
      "maxLength": 200
    },
    "cursor": {
      "description": "Continuation returned with identical filters.",
      "type": "string",
      "maxLength": 2048
    },
    "limit": {
      "default": 50,
      "description": "Maximum rows on this page; values above 200 are clamped with disclosure.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "startDate",
    "endDate",
    "minCategory",
    "minWeeks",
    "mode",
    "limit"
  ],
  "additionalProperties": false
}
view source ↗

drought_dataframe_query

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(*).

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_dataframe_query",
    "arguments": {
      "canvas_id": "<canvas_id>",
      "sql": "<sql>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Token returned by a drought producer."
    },
    "sql": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16384,
      "description": "One DuckDB read expression with an optional terminal semicolon; staged tables only."
    },
    "limit": {
      "default": 100,
      "description": "Maximum returned rows, clamped to 500 with disclosure and further bounded by complete response size.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "offset": {
      "default": 0,
      "description": "Rows to skip in the stable ordered query.",
      "type": "integer",
      "minimum": 0,
      "maximum": 250000
    }
  },
  "required": [
    "canvas_id",
    "sql",
    "limit",
    "offset"
  ],
  "additionalProperties": false
}
view source ↗

drought_dataframe_describe

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.

read
invocation
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "drought_dataframe_describe",
    "arguments": {
      "canvas_id": "<canvas_id>"
    }
  }
}
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Token returned by a drought producer."
    },
    "table_name": {
      "description": "Table name from the stage handle; omit for schema summaries.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
          "description": "SQL identifier of an existing staged table."
        }
      ]
    },
    "metadata_field": {
      "description": "Retained metadata collection to page; requires table_name.",
      "type": "string",
      "enum": [
        "areas",
        "summary",
        "missingAreas",
        "missingObservations"
      ]
    },
    "metadata_offset": {
      "default": 0,
      "description": "Items to skip in the retained metadata snapshot.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "metadata_limit": {
      "default": 20,
      "description": "Maximum metadata items, further bounded by response budgets.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "canvas_id",
    "metadata_offset",
    "metadata_limit"
  ],
  "additionalProperties": false
}
view source ↗

disabled 1

drought_dataframe_drop

Remove one disposable staged drought table using its exact canvas_id and table_name. This deletes only the analytical copy, never source data. dropped false means the table was already absent. This operation is available only when table removal is enabled.

disabledwould be destructive

Disabled. Disposable table removal is disabled.

Set DROUGHT_DATAFRAME_DROP_ENABLED=true to enable.
schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Token returned by a drought producer."
    },
    "table_name": {
      "type": "string",
      "pattern": "^[A-Za-z_][A-Za-z0-9_]{0,62}$",
      "description": "Exact staged table to remove."
    }
  },
  "required": [
    "canvas_id",
    "table_name"
  ],
  "additionalProperties": false
}
view source ↗