openair-3-mcp-server-oss

The server — run on any machine with R (your laptop, lab VM, or cloud). MCP clients connect via stdio (local) or HTTP (local 127.0.0.1 or remote host via mcp-remote).

Give your AI agent the ability to analyse air quality — import public networks, load CSV exports, and produce publication-grade openair charts from chat.

Pair with the client plugin for your IDE: openair-3-mcp-client-plugin-oss (Claude, Cursor, Codex, VS Code).

Not affiliated with openair-project maintainers.

• 43 tools — 35 R-backed plots/imports/stats + 8 Python pipeline tools (CSV, Excel, upload, prepare, health, docs)

• 2 transports — stdio (IDE and R on the same machine) or HTTP (localhost or remote via mcp-remote)

• Agent skills — plugin v0.3 manuals + workflows (skills/)

• Self-hosted — you choose where R runs; the default path is local on your own machine

Architecture

flowchart LR
  subgraph laptop ["Your laptop"]
    IDE["IDE + client-plugin"]
  end

  Link[".mcp.json · mcp-remote"]

  subgraph srv ["Server you run"]
    S["server-oss + R"]
  end

  IDE <--> Link <--> S

client-plugin on your MCP client · server-oss + R on the host you choose · use stdio when both are on the same machine, HTTP + mcp-remote when the server is elsewhere (including 127.0.0.1).

Choose your setup

See Installation for config snippets.

vs R console / openair GUI

Quick start

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

Install R packages on the same machine:

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

Run HTTP MCP (same machine or remote host; IDE connects via mcp-remote):

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

Run stdio (IDE and R on the same machine — no mcp-remote, no separate HTTP process):

fastmcp run server.py:mcp --transport stdio

Then install the client plugin and wire MCP — local stdio, localhost HTTP, or remote URL.

Getting your data in

Another MCP: fetch/query runs on the upstream MCP (Postgres read MCP, REST API MCP, Airtable MCP, etc.). Pass its export JSON to prepare_series_for_openair. The export must include series_v1 or a compatible parameters[].data bucket layout — see export_bridge.py and schemas/series.v1.json. Do not build series arrays in the client.

Related MCP server: Weather MCP Server

Data pipeline

flowchart TB
  agent["Agent / chat — orchestrates the pipeline"]

  subgraph in ["Data in (deterministic tools)"]
    disk["load_series_from_*"]
    export["export_local_series.py"]
    net["import_*"]
    mcp["json_exports"]
  end

  v1["SeriesV1"]
  prep["prepare_series_for_openair"]
  df["R data.frame"]
  plot["openair plot"]
  png["PNG"]

  agent --> disk & export & net & mcp
  disk --> v1
  export --> v1
  net --> v1
  mcp --> prep
  agent --> prep --> df --> plot --> png
  v1 --> prep

The agent orchestrates every step. Calculation (parse, align, plot) stays on the server — no LLM-invented JSON or date parsing in the client.

1. Ingest — disk load, client export script, public import, or JSON from another MCP → SeriesV1

2. prepare — align timestamps, granularity, timezone, gaps

3. R — build data.frame(date, …) then call openair::timePlot (etc.)

4. Return — PNG (+ short text summary)

Typical flows

CSV (global / sensor export)

Wide table: datetime column + pollutant columns. Skip metadata (battery, lat, …) with optional columns.

1. load_series_from_csv — path on server disk (ISO or EU day-first dates, e.g. 23/06/2026 00:00h)

2. prepare_series_for_openair — set series_name when multiple pollutants; timezone / timezone_name for local exports

3. One plot tool — time_plot, calendar_plot, …

Sample files: fixtures/sample_hourly.csv, fixtures/sample_spain_hourly.csv. Walkthrough: csv-calendar-plot.md.

Excel (regional / government exports)

Same pipeline with load_series_from_excel — .xlsx on server disk. Handles Spanish-style Fecha/hora and duplicate-hour dedupe. Walkthrough: local-excel-spain.md.

Local file on your PC (remote MCP)

If the MCP server runs elsewhere, paths on your laptop are invisible to load_series_from_*.

Preferred: run scripts/export_local_series.py on your machine (pip install -e . from this repo — no R required). Read the JSON and call prepare_series_for_openair(data=…) on the remote MCP. See the client ingest-local-export skill.

Alternatives: copy the file to server disk, use local stdio MCP, or load_series_from_upload (base64, max 1 MB raw). See the client ingest-local skill.

Public network (UK / EU)

1. import_aurn / import_europe / import_ukaq

2. prepare_series_for_openair

3. Plot tool

Walkthrough: aurn-time-plot.md.

Another MCP (API, database, spreadsheet, …)

1. Configure a second MCP in your client (REST API, Postgres, Airtable, custom sensor API, etc.).

2. Call the upstream tool that returns hourly/time-series JSON.

3. prepare_series_for_openair(json_exports=[export]) — optional series_name, parameter, granularity, timezone_name.

4. Plot tool.

The upstream MCP owns fetch and query; this server owns alignment and openair plots.

Optional live smoke: OPENAIR_SMOKE_NETWORK=1 python check_integrations.py

Available tools

Plot and import tools are auto-discovered from r/scripts/*.R manifest headers at startup.

Pipeline (Python)

Data import (R)

Time series plots (R)

Polar / wind (R)

Requires wind speed (ws) and direction (wd) in prepared data.

Trajectory (R)

Stats & transforms (R)

Plot tools return [text, image] MCP blocks so clients can show the chart inline. Stats tools return structured JSON.

Prerequisite: R 4.1+ with openair 3.x (ggplot2 backend) on the server host. Run health_r after install.

Installation

Method 1: HTTP + mcp-remote (local or remote)

Run the server on any machine with R — your laptop (127.0.0.1) or a remote host:

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

Point the client plugin at that URL via mcp-remote (.mcp.json.example):

{
  "mcpServers": {
    "openair-3-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:8001/sse",
        "--header",
        "X-MCP-Token: YOUR_MCP_TOKEN"
      ]
    }
  }
}

• Local: use http://127.0.0.1:8001/sse — omit --header if you did not configure auth.

• Remote: replace the URL with your server (HTTPS behind nginx/Caddy is typical). Add --header X-MCP-Token: … when your proxy requires it.

Requires Node.js 18+ on the MCP client for npx mcp-remote.

Method 2: stdio (local all-in-one)

When the IDE and R run on the same machine, the client can spawn the server directly — no HTTP port, no mcp-remote:

{
  "mcpServers": {
    "openair-3-mcp": {
      "command": "/path/to/openair-3-mcp-server-oss/.venv/bin/python",
      "args": ["-m", "fastmcp", "run", "server.py:mcp", "--transport", "stdio"],
      "cwd": "/path/to/openair-3-mcp-server-oss"
    }
  }
}

Windows: use .venv\\Scripts\\python.exe instead of .venv/bin/python.

Server configuration

Copy .env.example → .env:

R only needs to run on the server — not on every IDE client.

Development

git clone https://github.com/miguel-escribano/openair-3-mcp-server-oss
cd openair-3-mcp-server-oss
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
python check_integrations.py
pytest

Project structure

server.py                 # FastMCP entry — tool registration
openair_mcp/
├── prepare.py            # prepare_series_for_openair
├── export_bridge.py      # json_exports merge / SeriesV1
├── r_bridge.py           # R subprocess + manifest discovery
├── contracts.py          # Pydantic SeriesV1, WindSeriesV1, …
└── utils.py              # CSV → SeriesV1
r/
├── scripts/              # One .R file = one MCP tool (MANIFEST header)
└── common/               # Shared R helpers
schemas/                  # JSON Schema for series contracts
fixtures/                 # Sample CSV for smoke tests
tests/                    # Python unit tests
check_integrations.py     # Smoke suite (Python always; R when available)

Add a new tool: drop an R script in r/scripts/ with a # MANIFEST: {...} line — no Python edit required.

Tech stack

• Python 3.11+ — MCP server, CSV pipeline, contracts

• FastMCP 3.x — MCP protocol

• Pydantic — SeriesV1 / request validation

• R + openair 3.x — Plots, imports, statistics (openair MIT on CRAN)

• jsonlite — R JSON bridge

Use cases

• Researcher with AURN data — “Import Marylebone Road PM2.5 for 2023 and calendar plot it”

• IoT / indoor CSV — Load hourly export from disk → time plot or diurnal pattern

• Source apportionment hint — Polar plot when wind columns exist

• Trend reporting — Theil–Sen or smooth trend for long series

• Multi-pollutant screening — Correlation matrix across prepared series

• Ex-GUI habit — Same openair charts you know, alongside your usual R workflow — from Claude / Cursor / Codex when chat fits

Roadmap

Optional: JSON from other MCPs

prepare_series_for_openair(json_exports=[…]) accepts generic time-series JSON (series_v1 or bucketed parameters). Standalone use needs only CSV or import_*.

Scope

This binomio provides charts and data access through MCP, powered by openair on R. It does not include interpretation, compliance advice, or health guidance — those belong in your own reporting workflow.

For methodology, see the openair book. Teams that pair generative AI with air-quality data often add a controlled knowledge base for narrative beyond plots; that layer is separate from this chart stack.

Release v0.2.4 — refman-aligned plot legends (pm10, no2, …), openair_plot_title + meta.site, import_adms / import_aurn_csv, enriched network import meta (lat/lon). Pair with client plugin v0.3.4+. Feedback welcome via issues or the landing repo.

Third-party and attribution

This project is not affiliated with openair-project. If you use it — commercial or not — please attribute the parts you rely on.

openair (software)

Charts and statistics are produced by the openair R package (MIT). In papers, reports, or published figures, cite:

Carslaw, D. C. and K. Ropkins (2012). openair — an R package for air quality data analysis. Environmental Modelling & Software, 27–28, 52–61. doi:10.1016/j.envsoft.2011.09.008

BibTeX and updates: openair citation. In R: citation("openair").

Public air-quality data

import_aurn, import_europe, and related tools fetch third-party datasets, not data shipped with this repo. You must follow each provider’s licence when you publish or redistribute results.

Example UK data attribution (OGL):

© Crown copyright Defra via uk-air.defra.gov.uk, licensed under the Open Government Licence.

This MCP wrapper (optional)

openair-3-mcp-server-oss and openair-3-mcp-client-plugin-oss are MIT. You do not need our permission for non-commercial or commercial use. If this MCP binomio was part of your workflow and you publish methods, a brief mention or link to the GitHub repos is appreciated — but the scientific citation above is openair, not this wrapper.

License

MIT — see LICENSE. See Third-party and attribution for openair and data sources.