openair-3-mcp-client-plugin-oss

imageLicense: MIT

The client plugin — install this in Claude, Cursor, Codex, or VS Code. It connects your IDE to openair-3-mcp-server-oss, which you run locally (same machine as R) or on another host.

Openair plots and public network import from chat — alongside your usual R workflow. R runs wherever you host the MCP server (typically on your own machine for local setup, or on a remote host if you prefer).

Not affiliated with openair-project maintainers.

• Manual skills — ingest, prepare/plot, multi-MCP bridge (skills/)
• Workflow skills — pattern recipes (regional Excel, public network, remote upload)
• openair-agent — agents/openair-agent.md guardrails + analyst contract (client orchestrator)
• Examples — copy-paste chat workflows for AURN and CSV
• MCP wiring — .mcp.json.example with placeholders only (never commit tokens)

Architecture

flowchart LR
  subgraph localSetup ["Local (stdio) — IDE and R on the same machine"]
    IDE_L["IDE + client-plugin"]
    S_L["server-oss + R"]
    IDE_L -- ".mcp.json (stdio)" --> S_L
  end

  subgraph remoteSetup ["Remote (HTTP) — server on another host"]
    IDE_R["IDE + client-plugin"]
    Proxy["mcp-remote"]
    S_R["server-oss + R"]
    IDE_R -- ".mcp.json" --> Proxy -- "HTTPS + token" --> S_R
  end

Local stdio: IDE spawns the Python server directly — no Node, no HTTP port. Remote HTTP: IDE uses mcp-remote to reach a server elsewhere.

Choose your setup

VS Code: use the same JSON under .vscode/mcp.json with a top-level "servers" key instead of "mcpServers" (same command / args per server).

Binomio

Hermes Agent (Anne web)

Portable Agent Plugins v1 package: root plugin.json + skills/ + mcp.json.

hermes plugins install miguel-escribano/openair-3-mcp-client-plugin-oss --enable
# or: bash deploy/install-hermes-plugin.sh

Hosted Anne enables openair-client via profile plugins.enabled (see inbiot-anne-hermes/RUNTIME.md). Loopback MCP is in profile mcp_servers (:3007/mcp); remote laptops use mcp.remote.example.json. Do not adopt openair-agent.md as persona on the hosted profile — Anne interprets plots under her guardrails.

Quick start

1. Run the server where R lives — server README (local or remote).
2. Wire MCP — copy .mcp.json.example → .mcp.json (gitignored). Pick path A, B, or C. See CONNECTORS.md.
3. Install the plugin
   • Claude Code: claude plugin install /path/to/openair-3-mcp-client-plugin-oss
   • Cursor / Codex / VS Code: open this folder or add to your plugin path; skills live under skills/
4. Restart the IDE session after MCP config changes.

Using skills

Two ways to activate the harness:

1. Natural language (default) — describe your data modality and goal. Include what you know: path, datetime column, pollutant, timezone, site code, dates.
2. Direct invoke — @ingest-local-export, @ingest-local, @prepare-plot, @regional-excel, etc. when routing fails (Cursor / VS Code / Codex).

You are the analyst: supply column names, timezone, and paths when you know them. The agent should ask, not guess. For openair methodology see the official book.

Getting your data in

Merge multiple MCP servers in .mcp.json — see CONNECTORS.md. Upstream exports must be structured JSON (SeriesV1 schema); never hand-build arrays in chat.

Remote MCP: do not assume example server paths (data/felisa.xlsx) exist. Guardrail O6 in openair-agent.md.

What you can ask

Examples

Reproductions

Runnable scripts (no chat model needed) that reproduce a real, published openair analysis through this kit's MCP pipeline — proof you can run yourself, not a cherry-picked screenshot. Starts with the openair book's own Marylebone Road NOx polar plot example. See reproductions/.

Testing (acceptance gate)

This repo owns the golden-path harness — the authoritative check that deployed MCP produces correct plots.

$env:OPENAIR_MCP_TOKEN = "…"
python tests/run_series_exercises.py
python tests/run_wind_exercises.py

Server repo pytest + fixtures/ cover ingest/prepare units only — run both tiers before a release.

VS Code Copilot: examples/vscode-chat-felisa.md — same data as the harness, no Excel file hunt.

Do I need Python?

• Python runs the MCP server alongside R — infrastructure on the host you choose, not your analysis language.
• You do not write Python or R for Excel/CSV when using Disk (load_series_from_*) or Upload (load_series_from_upload).
• Recommended: local stdio for regional Excel exports; ingest-local-export (export script) for remote MCP with local files. Upload (load_series_from_upload) is the last resort for small files — default 1 MB, configurable on the server via OPENAIR_INGEST_MAX_BYTES.

All date parsing, dedupe, and alignment happen on the server (guardrails O1–O6 in agents/openair-agent.md).

Installation detail

Method 1: HTTP + mcp-remote

Use for local HTTP (127.0.0.1) or a remote server. Start the server over HTTP first (server README → Running the server), then point the plugin at its URL:

{
  "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: http://127.0.0.1:8001/sse — drop --header … if you have no token auth.
• Remote: your server URL instead of localhost; add the token header when your proxy requires it.

Requires Node.js 18+ on the IDE machine.

Method 2: Local stdio

IDE and R on the same machine — no HTTP server, 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. The command/cwd above point at a server checkout — set the server up first (clone, Python deps, R packages): server README → Quick start.

Plugin layout

skills/openair/            # Router — auto-routes to specialist skills
skills/ingest-local/       # Manual — CSV/Excel on server disk
skills/ingest-local-export/ # Manual — agent-run export script (local file + remote MCP)
skills/ingest-network/     # Manual — import_aurn, import_europe, …
skills/prepare-plot/       # Manual — prepare → one plot
skills/multi-mcp/          # Manual — json_exports bridge
skills/workflows/          # Pattern recipes (regional Excel, network, upload)
agents/openair-agent.md          # Guardrails O1–O6, analyst contract, routing
examples/                  # Copy-paste walkthroughs (start with vscode-chat-felisa.md for remote MCP)
reproductions/             # Runnable scripts reproducing published openair analyses via MCP
tests/                     # Acceptance harness + felisa_munarriz.json
.mcp.json.example          # Client config template (safe to commit)
CONNECTORS.md              # Server + optional MCP pairing

Optional pairing (multi-MCP)

Install openair-3-mcp alongside any MCP that returns time-series JSON:

Chain: upstream tool → prepare_series_for_openair(json_exports=[…]) → plot tool on openair MCP.

Requirements: deterministic JSON from the upstream tool (SeriesV1 or compatible export). Standalone CSV / import_* users do not need a second MCP.

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.1.0 — initial public release: openair-agent persona (agents/openair-agent.md), ingest/prepare/plot skills, workflow recipes, multi-MCP bridge, Felisa WindSeriesV1 fixture + 15-tool acceptance harness (tests/). Pair with the server at the same release. Issues and feedback welcome.

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.