openair-3-mcp-oss

MCP server wrapping the openair R package (~39 tools). Use with Claude, Cursor, Codex, or VS Code via openair-3-mcp-plugin-oss.

Not affiliated with openair-project maintainers.

Quick start (self-host)

git clone https://github.com/miguel-escribano/openair-3-mcp-oss
cd openair-3-mcp-oss
python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -e .
cp .env.example .env

On the same machine, install R packages:

install.packages(c("openair", "jsonlite", "legendry"), repos = "https://cloud.r-project.org")

Verify:

python check_integrations.py

Run HTTP MCP (for IDE clients via mcp-remote):

fastmcp run server.py:mcp --transport http --port 8001

Copy .mcp.json.example from the plugin repo; set YOUR_MCP_TOKEN if you enable auth in .env.

Typical flows

CSV (global / IoT export)

Wide table: datetime column + pollutant columns. Metadata columns (battery, coords) — pass columns to select pollutants only.

1. load_series_from_csv — path on server disk
2. prepare_series_for_openair — series_name if multiple pollutants
3. One plot tool — time_plot, calendar_plot, …

See fixtures/sample_hourly.csv.

Public network (UK / EU)

1. import_aurn / import_europe / import_ukaq
2. prepare_series_for_openair
3. Plot tool

Optional: OPENAIR_SMOKE_NETWORK=1 python check_integrations.py for live import smoke.

Tool groups

Group	Examples
Data in	load_series_from_csv, import_aurn, import_europe, prepare_series_for_openair
Time / trend	time_plot, calendar_plot, time_variation, theil_sen
Polar / wind	polar_plot, pollution_rose, wind_rose (need ws/wd in data)
Stats	aq_stats, time_average, cor_plot
Health	ping, health_r, openair_docs

Full list: auto-discovered from r/scripts/ — see legacy sections in git history or run the server and list tools.

Requirements

• Python 3.11+
• R 4.1+ with openair 3.x (ggplot2 backend). Run health_r after install.
• R only on the server host, not on every IDE client.

Future (out of v0.1)

Package	Use case
worldmet	Meteo NOAA when CSV has no wind — planned v0.2
openairmaps	Leaflet maps — v0.3+ if community demand
deweather	Met normalisation — advanced / v1.x

Appendix — sensor export MCPs

prepare_series_for_openair accepts optional inbiot_exports for pipelines that expose JSON time-series exports. Standalone researchers use CSV or import_* only.

License

MIT — see LICENSE. Runtime uses R openair (GPL) on the server.