Provides AI agents with analyst-grade US severe weather data including warnings, SPC outlooks, radar-derived products, and storm reports.
Also known as lostnumber07/shearline
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 92
- Latest version
- 1.1.0
- Last commit
- Nov 15, 2026
- License
- MIT
What is SHEARLINE MCP?
SHEARLINE provides AI agents with analyst-grade US severe weather data including warnings, SPC outlooks, radar-derived products, and storm reports.
Summary generated from the project's README
About SHEARLINE MCP server
SHEARLINE provides AI agents with specialized meteorological data focused on severe weather in the continental United States. Unlike standard weather services that offer basic forecasts, this server delivers analyst-grade information including active warning polygons with Impact-Based Warning tags, SPC convective outlooks, and radar-derived products like MRMS hail and rotation tracks. It is designed for developers building agents that need to understand complex storm dynamics rather than just temperature or precipitation.
The server runs locally via stdio or can be hosted as a remote service using an HTTP transport. It requires Python 3.12+ and the uv tool for installation. No API keys or accounts are necessary because all data is pulled from public sources. Users can access specific metrics like CAPE, shear, and the significant-tornado parameter, or use the threat brief tool to synthesize multiple data points into a single risk assessment with explained logic.
What you can do with it
- 1Verify historical hail damageAn agent can check if specific damaging hail hit a particular address on a past date for insurance purposes.
- 2Assess immediate tornado threatsA developer can task an agent with determining if a specific coordinate is currently inside a tornado warning polygon.
- 3Monitor atmospheric stability trendsAn agent can analyze whether the environment is becoming more or less dangerous by looking at forecast trajectories.
- 4Evaluate outdoor safety for lightningAn agent can provide safety guidance based on recent lightning activity from GOES satellites.
Written from the project's README. Every use case is checked against a quote from it.
How to install SHEARLINE MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall SHEARLINE MCP in Claude Code
$ claude mcp add shearline -- uvx shearlineInstall SHEARLINE MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"shearline": {
"command": "uvx",
"args": [
"shearline"
]
}
}
}Install SHEARLINE MCP in VS Code
.vscode/mcp.json
{
"servers": {
"shearline": {
"type": "stdio",
"command": "uvx",
"args": [
"shearline"
]
}
}
}Install SHEARLINE MCP in VS Code CLI
$ code --add-mcp '{"name":"shearline","type":"stdio","command":"uvx","args":["shearline"]}'Install SHEARLINE MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"shearline": {
"command": "uvx",
"args": [
"shearline"
]
}
}
}Install SHEARLINE MCP in Codex
$ codex mcp add shearline -- uvx shearlineInstall SHEARLINE MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.shearline] command = "uvx" args = ["shearline"]
Install SHEARLINE MCP in Gemini CLI
$ gemini mcp add -s user shearline uvx -- shearlineInstall SHEARLINE MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"shearline": {
"command": "uvx",
"args": [
"shearline"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablelostnumber07/shearline is public and reachablegithub.com/lostnumber07/shearline ↗Pass
- Package names this repository as its sourceshearline names lostnumber07/shearline as sourcepypi.org/project/shearline/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-14github.com/lostnumber07/shearline ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from shearlinePass
- No critical advisory in the package or its dependencies77 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubSHEARLINE
The severe-weather analyst your agent doesn't have. SHEARLINE is a free, MIT-licensed MCP server that gives AI agents analyst-grade US severe-weather tools: live warning polygons with Impact-Based Warning tags, SPC convective outlooks, RAP-derived point environments and forecast trends (CAPE/shear/SRH/STP computed with MetPy), MRMS radar-derived hail and rotation products, GOES lightning, ground-truth storm reports (real-time and historical), and a composite threat brief that synthesizes all of it. A dozen weather MCPs already wrap the basic forecast API; SHEARLINE deliberately skips everything they do and ships only what requires radar meteorology to expose correctly.
Informational only. Not a substitute for official NWS warnings. Every tool repeats this, because it matters: when weather threatens, follow official warnings from weather.gov and local authorities.
Tools
| Tool | What it returns |
|---|---|
get_active_warnings(lat, lon, radius_km=40) |
Active tornado/severe-thunderstorm/flash-flood warning polygons with IBW tags (max hail size, max gust, tornado detection/damage threat), parsed storm motion, expirations, and whether the exact point is inside a polygon. Watches listed separately. |
get_spc_outlook(lat, lon, day=1) |
SPC categorical risk (TSTM→HIGH) at the point plus tornado/hail/wind probabilities and significant-severe flags, days 1–3, with interpretation calibrated to the category. |
get_point_environment(lat, lon) |
Latest RAP 13-km analysis profile computed with MetPy: MLCAPE/MUCAPE/CINs, LCL, 0–1/0–6 km shear, 0–1/0–3 km SRH, Bunkers motion, effective inflow layer, effective SRH/shear, SCP, and significant-tornado parameter — interpreted like an analyst (pulse vs. cool-season high-shear vs. classic supercell parameter space). |
get_environment_trend(lat, lon) |
The anticipatory view: a short RAP forecast series (f00/f01/f03/f06, one consistent cycle) of MLCAPE, 0–6 km shear, 0–1 km SRH, SCP and STP, with an interpretation of the trajectory (intensifying / stabilizing / steady) — for "is this getting worse" rather than "what is it now." |
get_mrms_severe(lat, lon, radius_km=40) |
MRMS maxima within radius: 60-min MESH (hail, inches and mm), low-level and mid-level rotation tracks (azimuthal shear), VIL, composite reflectivity — each with valid time and distance/bearing of the max. |
get_storm_reports(lat, lon, radius_km=80, hours=6) |
Normalized Local Storm Reports: type, magnitude with units, time, location, distance/bearing, remarks. |
get_lightning(lat, lon, radius_km=40, minutes=15) |
GOES-East GLM total-lightning activity in the recent window: flash count and rate, nearest strike (distance/bearing/time), and a tiered outdoor-safety interpretation (overhead / within-striking-distance / in-the-area). |
get_historical_storm_reports(lat, lon, date, radius_km=80) |
What hail/wind/tornado hit a point on a specific past date (YYYY-MM-DD, UTC) — normalized reports with magnitude+units and distance/bearing, for the insurance / ag / forensic use case. Coverage from ~2005; preliminary LSRs, not the final NCEI record. |
get_threat_brief(lat, lon) |
The showpiece: runs everything above concurrently and synthesizes a threat level (none/marginal/elevated/significant/extreme) with stated logic, hazards ranked, environment summary, nearest storm signature, and a recommended attention window. |
get_radar_snapshot(lat, lon) |
Nearest WSR-88D's latest Level 2 volume metadata: VCP (scan strategy), max reflectivity with range/azimuth, coarse echo-top estimate. |
Every tool returns structured JSON with data (numeric fields, units stated), interpretation (plain-language analyst sentences), degraded (which upstream sources failed, if any — partial data instead of errors), the safety disclaimer, and a schema_version — the field contract is semver-stable (see ARCHITECTURE), so integrators can depend on it.
Example: threat brief during a real outbreak
Real output from 2026-06-10, point inside an active tornado warning in northern Missouri:
{
"threat_level": "extreme",
"threat_logic": [
"Tornado Warning in effect at the point, corroborated by confirmed tornado reports nearby — treat as an immediate life-safety situation.",
"Severe Thunderstorm Warning at the point tagged 'Considerable' (hail to 1.75\", gusts to 60 mph).",
"Significant-tornado parameter of 4.0 with storms ongoing — environment strongly supports tornadic supercells.",
"MRMS MESH of 2.3\" hail within radius in the last hour.",
"Intense rotation track (azimuthal shear 0.013 /s) nearby in the last hour.",
"6 tornado report(s) near the point in the report window."
],
"hazards_ranked": [
{"hazard": "tornado", "level": "extreme"},
{"hazard": "hail", "level": "extreme"},
{"hazard": "damaging_wind", "level": "extreme"},
{"hazard": "flash_flood", "level": "moderate"}
],
"nearest_storm_signature": {
"signature": "composite reflectivity", "value": "58.5 dBZ",
"distance_km": 18.0, "direction": "ENE", "valid_utc": "2026-06-10T22:14Z"
},
"attention_window": {"window": "now", "until_utc": "2026-06-10T21:00:00-05:00"}
}
And the same tool for a quiet coastal Maine point reads as confidently quiet — not as an error: "threat_level": "none" with the environment numbers shown so the agent can see why it's quiet.
Install
Requires Python 3.12+ and uv. No API keys — every data source is public and anonymous. uvx downloads and runs the published package in one step; nothing is installed permanently.
Claude Code:
claude mcp add shearline -- uvx shearline
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"shearline": {
"command": "uvx",
"args": ["shearline"]
}
}
}
Streamable HTTP (for remote/agent-platform use):
uvx shearline --http --port 8741
# serves at http://127.0.0.1:8741/mcp
On macOS you can also double-click scripts/launch.command to start the HTTP server in a Terminal window (honours SHEARLINE_PORT).
The HTTP transport is built to be hosted: it emits one structured JSON log line
per tool call (tool, coarse 1° lat/lon bucket, latency, degraded list, cache
hit/miss) and applies a per-client token-bucket rate limit, returning 429 with
Retry-After when exceeded. Both are HTTP-only — stdio behaviour is
unchanged. Configure via environment variables:
| Env var | Default | Effect |
|---|---|---|
SHEARLINE_RATE_RPM |
60 |
sustained requests/minute/client (0 disables the limit) |
SHEARLINE_RATE_BURST |
30 |
token-bucket capacity (max burst) |
SHEARLINE_HTTP_LOG |
1 |
set 0 to silence per-request logging |
SHEARLINE_LOG_LEVEL |
INFO |
log level for the shearline.http logger |
SHEARLINE_UPSTREAM_CONCURRENCY |
8 |
max concurrent upstream fetches (politeness toward NOAA) |
To run the latest unreleased main instead of the PyPI release, swap shearline for --from git+https://github.com/lostnumber07/shearline shearline.
Why these tools
A forecast API tells you it might rain. None of the questions that matter on a severe weather day — is this storm rotating, how big is the hail, is the environment loaded for tornadoes, am I inside the polygon — are answerable from a forecast endpoint. They require the warning's IBW tags, radar-derived products, and a real sounding:
- Warnings with IBW tags, not just warning text. A base-tier Severe Thunderstorm Warning and one tagged
DESTRUCTIVEwith 80 mph gusts are different planning problems. SHEARLINE parses the machine-readable tags (max hail size, max gust, tornado detection/damage threat) and the storm-motion vector, and does the point-in-polygon test for you. - The environment, computed honestly. CAPE without shear is a pulse-storm day; shear without CAPE is wind-driven rain. SHEARLINE pulls the current RAP analysis profile and computes the discriminating quantities with MetPy — including the effective inflow layer, effective SRH/shear, SCP, and STP — because high-CAPE/low-shear, low-CAPE/high-shear, and classic supercell parameter spaces produce very different hazards, and the interpretation says which one you're in.
- MRMS, because warnings lag storms. MESH tells you what hail a storm has already produced; rotation tracks show where mesocyclones have tracked in the last hour — both on a ~2-minute cadence from the national radar mosaic, often ahead of the next warning update.
- LSRs, because radar isn't ground truth. Spotter reports confirm what's actually reaching the ground — in real time, or for any past date (the insurance / forensic question, "what hit this address that day").
- Lightning, because it's the most common outdoor-safety trigger. GOES GLM total lightning, distance-tiered to the 30-30 / 10-mile rules — the signal that actually stops a ballgame, a job site, or a drone flight.
- Now and next. The point environment is the analysis now; the forecast trend (f00→f06 from one model cycle) says whether STP/CAPE is rising into the afternoon — the difference between "what is it" and "is it getting worse."
- One brief that reasons across all of it. The threat level is rule-based with the triggered rules quoted back, so an agent can audit the logic instead of trusting a vibe.
Data sources (all public, no keys)
- Warnings: api.weather.gov (NWS)
- Outlooks: Storm Prediction Center public GeoJSON
- Point environment: NOMADS RAP grib filter, derived with MetPy
- MRMS: NOAA MRMS on AWS Open Data
- Storm reports (real-time and historical): Iowa Environmental Mesonet LSR service
- NEXRAD Level 2: Unidata on AWS Open Data
- Lightning: GOES GLM on AWS Open Data (GOES-East GLM-L2-LCFA)
Coverage is continental US only — out-of-bounds coordinates are rejected with a clear error. Upstream fetches are cached (warnings 60 s, MRMS/lightning 120 s, LSRs 300 s, outlooks/RAP 30 min, historical reports 6 h) and degrade gracefully: if one source is down, you get partial data plus a degraded field, never a bare exception. A daily canary workflow checks every upstream's response shape and fails on schema drift (renamed fields, moved buckets) before it reaches you.
Recipes for non-meteorologists
You don't need to know what an STP is to use SHEARLINE. The .claude/skills/
directory ships three end-to-end recipes that name the exact tool sequence for a
domain task — drop them into any agent that has SHEARLINE connected:
- hail-claim-verification — did damaging hail occur at this address on this date? (insurance / forensic)
- chase-day-briefing — outlook → environment → trend → warnings → radar, into a go/no-go with a target window (chase / EM)
- event-day-lightning-watch — poll lightning proximity and issue suspend/shelter/resume calls by the 30-30 / 10-mile rules (venues / outdoor ops)
Architecture
SHEARLINE is a thin, layered async server: per-source fetch/parse modules feed a meteorology derivation layer, which feeds a uniform tool layer. Every tool returns the same {data, interpretation, degraded, disclaimer} envelope, every upstream call is TTL-cached, and one failing source degrades to partial data instead of an exception. See ARCHITECTURE.md for the module map, the request lifecycle of get_threat_brief, the concurrency model, and the upstream quirks each source module encodes.
Development
git clone https://github.com/lostnumber07/shearline && cd shearline
uv sync
uv run pytest # offline test suite against recorded fixtures
uv run ruff check .
uv run shearline # stdio
uv run python scripts/smoke.py # live smoke test, both transports
uv run python scripts/canary.py # live upstream drift check (shape-only)
See ARCHITECTURE.md for how to add a tool or data source.
License
MIT © Backshear LLC. Weather data is produced by NOAA/NWS and other public services; this project is not affiliated with or endorsed by NOAA.
SHEARLINE MCP questions
How do I add SHEARLINE MCP to Claude Code?
Run claude mcp add shearline -- uvx shearline in your terminal. Add --scope user to make it available in every project.
How do I add SHEARLINE MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Do I need an API key to use SHEARLINE?
No, every data source used by the server is public and anonymous.
Is the weather data provided by SHEARLINE official?
The information is for informational purposes only and is not a substitute for official NWS warnings.
What geographic area does the server cover?
The server provides coverage for the continental US only.
Can I use SHEARLINE for historical weather analysis?
Yes, it includes tools to retrieve historical storm reports for specific dates, useful for insurance or forensic use cases.