Wellness Air

Local-first air-quality MCP for AI agents.
Plug an AirGradient/AirThings/PurpleAir sensor into your agent โ€” no tokens leave your machine.

npm version npm downloads License MIT Site

GitHub stars Built for MCP Hermes one-command setup OpenClaw one-command setup Delx Wellness Hub

๐Ÿ“ก Why this exists: your sleep / focus / training results are partly a room-quality problem. PM2.5 above 35, COโ‚‚ above 1,000 ppm, low humidity โ€” those wreck recovery and the agent can't see them. wellness-air gives any AI agent local-first environmental context to cross with WHOOP / Oura / Garmin / nourish.

> โšก **One-command install** โ€” pick your runtime: > - [Delx Wellness for Hermes](https://github.com/davidmosiah/delx-wellness-hermes): `npx -y delx-wellness-hermes setup` > - [Delx Wellness for OpenClaw](https://github.com/davidmosiah/delx-wellness-openclaw): `npx -y delx-wellness-openclaw setup` > > Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below. --- ## HTTP (v2 stateless) Default is **stdio**. Optional Streamable HTTP โ€” no session id, JSON responses, loopback only: ```bash npx -y wellness-air --http # GET http://127.0.0.1:3000/health # POST http://127.0.0.1:3000/mcp (sessionless) ``` Env: `WELLNESS_AIR_HOST`, `WELLNESS_AIR_PORT`, `WELLNESS_AIR_TRANSPORT=http`. ## Overview Wellness Air is a local MCP server that exposes air-quality readings to any MCP-aware AI agent. It ships with first-class **AirGradient** support (open hardware + free public API โ€” no auth needed for the 2,000+ public sensors in the worldwide feed). **AirThings** and **PurpleAir** are implemented (bring your own free API credentials); **IQAir AirVisual** and **Awair** are on the roadmap. > If wellness-air helps your agent, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure. ## Try It In 60 Seconds ```bash # 89 is a real, public AirGradient sensor (Prem Tinsulanonda School, Thailand). # Swap in one near you from https://www.airgradient.com/map/ โ€” copy the numeric # locationId from the URL. WELLNESS_AIR_DEFAULT_LOCATION=89 npx -y wellness-air doctor WELLNESS_AIR_DEFAULT_LOCATION=89 npx -y wellness-air current ``` That's it โ€” no token, no signup, no telemetry. Public reads use AirGradient's token-free worldwide feed, so any locationId in that feed works out of the box. ## Install in Claude Desktop / Cursor / ChatGPT Desktop / Codex ```jsonc { "mcpServers": { "wellness-air": { "command": "npx", "args": ["-y", "wellness-air"], "env": { "WELLNESS_AIR_DEFAULT_PROVIDER": "airgradient", "WELLNESS_AIR_DEFAULT_LOCATION": "89" } } } } ``` Reload your client. The agent now has 19 air-quality tools. ## Tools (19 total) | Tool | Purpose | |---|---| | `air_agent_manifest` | Runtime contract: tool list, supported clients, env vars, recommended first calls | | `air_capabilities` | Supported providers, configured providers, available metrics, privacy modes | | `air_connection_status` | Health check + warnings the agent should surface | | `air_privacy_audit` | What is logged locally vs sent to providers | | `air_data_inventory` | Metric catalog + AQI band thresholds | | **`air_current_reading`** | **Latest sensor reading (PM2.5, COโ‚‚, AQI, temp, humidity)** | | `air_list_devices` | List devices on an authenticated provider account (AirThings) | | **`air_aqi_check`** | **Fast 'is the air OK?' answer with band + recommendation** | | `air_daily_summary` | Synthesized daily snapshot | | `air_compare_locations` | Compare AQI across 2-10 locations | | `air_search_public_sensors` | Discovery helper for AirGradient public map | | `air_quickstart` | Personalized 3-step setup walkthrough based on current env state | | `air_profile_get` | Read the shared Delx Wellness profile (location, sensitivities, units) | | `air_profile_update` | Persist a non-secret patch to the shared wellness profile (explicit intent required) | | `air_onboarding` | 11-question onboarding flow for the shared wellness profile | | `air_demo` | Realistic example payloads โ€” preview output before configuring anything | | `air_health_recommendation` | PM2.5/COโ‚‚/VOC โ†’ WHO/EPA bands + plain-language actions | | `air_health_bands` | Classify PM2.5/PM10/COโ‚‚/VOC into WHO 2021 / EPA / ASHRAE / UBA bands + citations | | `air_trend` | Windowed trend analysis (mean/median/rate-of-change/peaks) for PM2.5/COโ‚‚/VOC | ## Why local-first? - **Public sensors require zero auth.** AirGradient runs an open public API; just pass a `locationId`. - **Owned-sensor tokens stay on your machine.** Set `AIRGRADIENT_API_TOKEN` only if you own a sensor. - **No telemetry.** wellness-air never phones home. The only outbound calls go to the providers you configure. - **Read-only.** No tool mutates anything upstream. (`air_profile_update` writes only to your local shared wellness profile, never to a provider, and requires explicit user intent.) ## Cross-connector wedge Where this gets interesting: pair it with the rest of the Delx Wellness stack. ``` WHOOP recovery 47 + wellness-air AQI 132 (unhealthy_sensitive) โ†“ โ†“ Coach: "Recovery's low AND the bedroom AQI was unhealthy last night. Skip outdoor cardio today โ€” try mobility + low-intensity strength indoors with HEPA running." ``` Most agents miss the room-quality variable entirely. wellness-air closes that gap. ## Privacy Run `wellness-air doctor` to inspect the local privacy posture. Highlights: - All readings cached under `~/.wellness-air` (configurable). - Provider tokens never returned to the agent. - No biometric data โ€” environmental only. - Tool outputs explicitly tagged with their data source for downstream auditability. ## Roadmap **Shipped:** AirGradient (public + owned) ยท AirThings ยท PurpleAir adapters ยท WHO/EPA/ASHRAE/UBA health bands ยท windowed trend analysis (`air_trend`) ยท shared Delx Wellness profile + onboarding. **Next:** - IQAir AirVisual + Awair adapters. - Cross-correlation helper (e.g. `air_correlate_with_sleep`) against the rest of the Delx Wellness stack. - Webhook trigger for AQI thresholds (agent gets notified when AQI crosses a band). ## ๐Ÿ“ง Contact & Support - ๐Ÿ“จ **support@delx.ai** โ€” general questions, integration help, partnerships - ๐Ÿ› **Bug reports / feature requests** โ€” [GitHub Issues](https://github.com/davidmosiah/wellness-air/issues) - ๐Ÿฆ **Updates** โ€” [@delx369](https://x.com/delx369) on X - ๐ŸŒ **Site** โ€” [wellness.delx.ai](https://wellness.delx.ai) ## License MIT โ€” see [LICENSE](LICENSE). wellness-air is an unofficial connector. AirGradient, AirThings, PurpleAir, IQAir, and Awair are trademarks of their respective owners. None of those companies are affiliated with or endorse this project. ## Skill or MCP Same package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP: ```bash npx -y wellness-air call air_connection_status --json '{}' ``` Copy `skill/SKILL.md` into your agent skills dir.