Wellness Air

io.github.davidmosiahPublished by GitHub account davidmosiahv0.5.6Updated Oct 24, 2026

Local-first air-quality MCP for AI agents — AirGradient, AirThings, PurpleAir, IQAir, Awair.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

A local-first MCP server that gives an AI assistant air-quality readings from public and owned sensors, with AQI checks, health bands and trends.

What you can do
Read current sensor readings (PM2.5, CO₂, AQI, temperature, humidity) and get a fast is-the-air-OK answer with band and recommendation, plus daily summaries and comparisons across 2–10 locations. Discover public AirGradient sensors and list devices on an authenticated AirThings account. Classify readings into WHO, EPA, ASHRAE and UBA bands and analyze windowed trends (mean, median, rate of change, peaks). Inspect capabilities, connection status, data inventory and a privacy audit of what is logged locally versus sent to providers. Read, update and onboard a shared local wellness profile, and preview example payloads before configuring anything.
When to use it
Useful when an assistant should factor room air quality into sleep, recovery, focus or training advice, or when you want to query nearby public sensors without any signup. Also fits setups that already track health data and want environmental context alongside it.
Requirements
Runs as a local process via npx (Node.js). Default transport is stdio; optional loopback-only HTTP can be enabled with WELLNESS_AIR_HOST, WELLNESS_AIR_PORT and WELLNESS_AIR_TRANSPORT. Public AirGradient reads need only a numeric locationId, set for example via WELLNESS_AIR_DEFAULT_LOCATION. Owned AirGradient sensors need AIRGRADIENT_API_TOKEN; AirThings and PurpleAir need your own provider credentials. Network access to the configured providers is required.
Before you install
Provider credentials such as AIRGRADIENT_API_TOKEN and AirThings/PurpleAir keys are configured locally and should be treated as secrets. Outbound calls go only to the providers you configure, and readings are cached under a local directory. Most tools are read-only, but air_profile_update writes to the local shared wellness profile and requires explicit intent. No biometric data is handled; outputs are environmental only.

Installation

In SourceWeft

  1. Open Wellness Air in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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:

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 [email protected] --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 [email protected] doctorWELLNESS_AIR_DEFAULT_LOCATION=89 npx -y [email protected] 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", "[email protected]"],      "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)

ToolPurpose
air_agent_manifestRuntime contract: tool list, supported clients, env vars, recommended first calls
air_capabilitiesSupported providers, configured providers, available metrics, privacy modes
air_connection_statusHealth check + warnings the agent should surface
air_privacy_auditWhat is logged locally vs sent to providers
air_data_inventoryMetric catalog + AQI band thresholds
air_current_readingLatest sensor reading (PM2.5, CO₂, AQI, temp, humidity)
air_list_devicesList devices on an authenticated provider account (AirThings)
air_aqi_checkFast 'is the air OK?' answer with band + recommendation
air_daily_summarySynthesized daily snapshot
air_compare_locationsCompare AQI across 2-10 locations
air_search_public_sensorsDiscovery helper for AirGradient public map
air_quickstartPersonalized 3-step setup walkthrough based on current env state
air_profile_getRead the shared Delx Wellness profile (location, sensitivities, units)
air_profile_updatePersist a non-secret patch to the shared wellness profile (explicit intent required)
air_onboarding11-question onboarding flow for the shared wellness profile
air_demoRealistic example payloads — preview output before configuring anything
air_health_recommendationPM2.5/CO₂/VOC → WHO/EPA bands + plain-language actions
air_health_bandsClassify PM2.5/PM10/CO₂/VOC into WHO 2021 / EPA / ASHRAE / UBA bands + citations
air_trendWindowed 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

License

MIT — see 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 can drive the same tools through the CLI when the client has no MCP:

bash
npx -y [email protected] call air_connection_status --json '{}'

Copy skill/SKILL.md into your agent skills dir.

0.8.0 — candidate (2026-11-02)

This is a release candidate, not evidence of an npm publication. Existing installations are not updated automatically.

Migration and security boundaries

  • HTTP transport accepts loopback only. LAN addresses and wildcard binds are rejected; use stdio or a local loopback client instead.
  • Wellness profiles are validated, limited to 256 KiB, and protected with a cooperative lock. Oversized or invalid existing profiles must be corrected before use. Symbolic links, including dangling links and legacy profile paths, are rejected. These checks do not guarantee safety against a hostile local filesystem or non-cooperating processes.
  • MCP inputs have a 10,000-element budget and HTTP bodies are limited to 1 MiB; compressed request bodies are rejected. Previously accepted oversized requests may now fail; reduce request sizes rather than disabling validation.
  • Dependency fixes are included. Upgrade explicitly after publication and restart the connector; old installations retain their previous behavior.

Source: README.md at commit 0cc0f1c

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.6LatestSep 16, 2026

Score

50% 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 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts