{
  "markdown": "# 🌍 WEMS - World Event Monitoring System\n\n[![PyPI version](https://badge.fury.io/py/wems-mcp-server.svg)](https://badge.fury.io/py/wems-mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)\n\n<!-- mcp-name: io.github.heliosarchitect/wems -->\n\n**🚨 Real-time Natural Hazard Monitoring for AI Agents**\n\nA powerful Model Context Protocol (MCP) server that connects AI assistants to authoritative natural hazard data sources. Monitor earthquakes, tsunamis, volcanoes, and solar events with configurable alerts and webhooks.\n\n> **🤖 AI Agents:** Skip scanning this repo. Read [`AI.TOC`](AI.TOC) first — it's a 500-token project map. Then use [`AI.INDEX`](AI.INDEX) to find specific functions and [`AI.REGISTER`](AI.REGISTER) for env vars, APIs, and config. This project uses the [LBF AI Navigation Standard](AI.CONTEXT.md).\n\n## ⚡ Key Features\n\n- 🌋 **9+ Authoritative Data Sources**: USGS, NOAA, Smithsonian GVP, NHC, NIFC, OpenAQ, DHS, State Dept, CISA, US Drought Monitor\n- 🎯 **Real-time Monitoring**: Live data feeds with customizable thresholds\n- 🔔 **Smart Alerts**: Webhook notifications for critical events\n- 🗺️ **Geographic Filtering**: Target specific regions or global coverage\n- 🔧 **Zero Configuration**: Works out-of-the-box, configure only what you need\n- 🐳 **Production Ready**: Docker support, comprehensive error handling\n\n### Natural Hazards Covered\n\n| Hazard Type | Data Source | Coverage |\n|-------------|-------------|----------|\n| 🌊 **Earthquakes** | USGS | Global, magnitude filtering |\n| 🌊 **Tsunamis** | NOAA PTWC + CTWC | Global ocean basins |\n| 🌋 **Volcanoes** | Smithsonian GVP + USGS | Global volcanic activity |\n| ☀️ **Solar Events** | NOAA SWPC | Solar flares, CMEs, geomagnetic storms |\n| 🌞 **Space Weather Alerts** | NOAA SWPC | Active space weather alerts & warnings |\n| 🌀 **Hurricanes** | NHC + NWS | Atlantic & Pacific tropical cyclones |\n| 🔥 **Wildfires** | NWS + NIFC | Fire weather alerts & active perimeters |\n| ⛈️ **Severe Weather** | NWS Alerts | Tornadoes, thunderstorms, floods, winter storms |\n| 💨 **Air Quality** | OpenAQ | Global AQI, PM2.5, PM10, O₃, NO₂, SO₂, CO |\n| 🌵 **Drought Conditions** | US Drought Monitor | US state drought levels (D0-D4) + trends |\n| 🛡️ **Threat Advisories** | DHS NTAS + State Dept + CISA | Terrorism, travel risk, cyber threats |\n\n## 🚀 Quick Start\n\n### Install via PyPI (Recommended)\n\n```bash\npip install wems-mcp-server\n```\n\n### Or install from source\n\n```bash\ngit clone https://github.com/heliosarchitect/wems-mcp-server.git\ncd wems-mcp-server\npip install -r requirements.txt\n```\n\n### Basic Usage\n\n```bash\n# Run as MCP server (connects to AI assistants)\npython -m wems_mcp_server\n\n# Test earthquake monitoring\npython -c \"\nimport asyncio\nfrom wems_mcp_server import check_earthquakes\nprint(asyncio.run(check_earthquakes(min_magnitude=6.0)))\n\"\n```\n\n### One-command AI Alerting Setup (Relay + n8n)\n\n```bash\nbash scripts/setup_wems_alerting_ai.sh\n```\n\nThis will:\n- install/start `wems-unified-relay.service`\n- upsert and activate the unified n8n ingest workflow\n- wire tracker posting credentials automatically\n\n### Example Output\n\n```json\n{\n  \"earthquakes_found\": 3,\n  \"events\": [\n    {\n      \"magnitude\": 7.2,\n      \"location\": \"67 km SW of Tres Picos, Mexico\",\n      \"time\": \"2024-02-13T14:30:15Z\",\n      \"depth\": 35.8,\n      \"tsunami_threat\": true\n    }\n  ]\n}\n```\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `check_earthquakes` | Query recent earthquake activity |\n| `check_solar` | Monitor space weather (K-index, flares, CMEs) |\n| `check_volcanoes` | Track volcanic activity alerts |\n| `check_tsunamis` | Monitor tsunami warnings |\n| `check_hurricanes` | Track tropical cyclones & forecast tracks |\n| `check_wildfires` | Fire weather alerts & active perimeters |\n| `check_severe_weather` | Monitor tornadoes, thunderstorms, flash floods |\n| `check_floods` | Flood warnings & USGS river gauge data |\n| `check_air_quality` | AQI monitoring with pollutant data |\n| `check_threat_advisories` | Terrorism, travel risk & cyber threat monitoring |\n| `check_space_weather_alerts` | Active space weather alerts & warnings from NOAA SWPC |\n| `check_drought_status` | US state drought conditions with D0-D4 levels (Premium) |\n| `configure_alerts` | Update alert thresholds and webhooks |\n| `fuse_multi_source_incidents` | Multi-source incident fusion (feature-flagged) |\n\n## Configuration\n\n```yaml\nalerts:\n  earthquake:\n    min_magnitude: 6.0\n    regions: [\"US\", \"Caribbean\", \"Pacific\"]\n    webhook: \"https://your-endpoint.com/earthquake\"\n  \n  solar:\n    min_kp_index: 7  # Geomagnetic storm threshold\n    webhook: \"https://your-endpoint.com/solar\"\n    \n  volcano:\n    alert_levels: [\"WARNING\", \"WATCH\"]\n    webhook: \"https://your-endpoint.com/volcano\"\n    \n  tsunami:\n    enabled: true\n    regions: [\"pacific\", \"atlantic\", \"indian\"]\n    webhook: \"https://your-endpoint.com/tsunami\"\n```\n\n## Data Sources\n\n- USGS Earthquake Hazards Program\n- NOAA Pacific Tsunami Warning Center\n- NOAA Central Tsunami Warning Center  \n- Smithsonian Global Volcanism Program\n- NOAA Space Weather Prediction Center\n- National Hurricane Center (NHC)\n- National Interagency Fire Center (NIFC)\n- NWS Alerts API\n- OpenAQ (Global Air Quality)\n- DHS National Terrorism Advisory System (NTAS)\n- U.S. State Department Travel Advisories\n- CISA Cybersecurity Advisories\n\n## OpenClaw Integration\n\nAdd to your OpenClaw configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"wems\": {\n      \"command\": \"python3\",\n      \"args\": [\"/path/to/wems-mcp-server/wems_mcp_server.py\"],\n      \"env\": {\n        \"WEMS_CONFIG\": \"/path/to/config.yaml\"\n      }\n    }\n  }\n}\n```\n\n## 🎯 Use Cases\n\n- **🏢 Enterprise Risk Management**: Automated threat assessment for global operations\n- **📺 News Organizations**: Real-time natural disaster reporting and alerts  \n- **🔬 Research Institutions**: Data collection for scientific analysis\n- **🏠 Personal Safety**: Location-specific hazard monitoring for families\n- **🤖 AI Emergency Response**: Integration with disaster response chatbots\n- **📱 Alert Systems**: Custom notification workflows for critical events\n\n## 🔧 Advanced Configuration\n\n```yaml\n# config.yaml - Full customization example\nalerts:\n  earthquake:\n    min_magnitude: 6.0\n    regions: [\"US\", \"Caribbean\", \"Pacific\"]\n    webhook: \"https://your-endpoint.com/earthquake\"\n    \n  solar:\n    min_kp_index: 7  # G3+ geomagnetic storm\n    webhook: \"https://your-endpoint.com/solar\"\n    \n  volcano:\n    alert_levels: [\"WARNING\", \"WATCH\"] \n    regions: [\"Cascade Range\", \"Ring of Fire\"]\n    webhook: \"https://your-endpoint.com/volcano\"\n    \n  tsunami:\n    enabled: true\n    regions: [\"pacific\", \"atlantic\", \"indian\"]\n    webhook: \"https://your-endpoint.com/tsunami\"\n```\n\n## 📊 Monitoring Dashboard\n\nPair with monitoring tools for comprehensive coverage:\n\n```bash\n# Example: Send earthquake data to monitoring system\ncurl -X POST https://your-monitoring.com/api/events \\\n  -H \"Content-Type: application/json\" \\\n  -d \"$(python -c 'import wems; print(wems.get_recent_earthquakes())')\"\n```\n\n## 💳 Billing & Monetization (Current)\n\nWEMS now includes Stripe metering scaffolding and affordable default pricing.\n\n### Current pricing defaults\n- Free tier: **5,000 calls per rolling 30 days**\n- 0–100,000 calls: **$0.0010/call**\n- 100,001–500,000 calls: **$0.0008/call**\n- 500,001+ calls: **$0.0006/call**\n\n### Accessory call weights (default)\n- Most tools: `1` unit\n- `check_space_weather_alerts`: `2` units\n- `fuse_multi_source_incidents`: `3` units\n\n### Billing config\nSee: `config/wems_stripe_billing.json`\n\nKey fields:\n- `event_name`\n- `api_key_to_customer`\n- `billing_units.default`\n- `billing_units.by_tool`\n- `pricing.free_calls_per_rolling_30d`\n- `pricing.tiers[]`\n\n### Stripe key source\n1. `STRIPE_API_KEY` or `STRIPE_SECRET_KEY` (direct env)\n\nWEMS uses best-effort lookup and never blocks alerting if billing key resolution fails.\n\n---\n\n**Built with ❤️ for the AI community by Helios** 🌞\n\n*Part of the expanding [OpenClaw](https://openclaw.ai) ecosystem*",
  "bytes": 8279,
  "sha": "d7b9fe32e6dc862932a0837af59f194498f210613b8a024a12afbdbc1b763c3d",
  "repo_slug": "heliosarchitect/wems-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_heliosarchitect_wems_cd0bb794/readme"
}