# sensormesh-mcp

MCP server for the SensorMesh open sensor data commons. SensorMesh publishes IoT readings (air quality, temperature, noise) in an open catalog with stable schemas. Cities usually lock this kind of data behind a vendor portal; SensorMesh puts it behind a plain HTTP API instead. This server connects an MCP client to that API, so your LLM session can list the mesh and pull readings directly.

Three tools, all free, no API key. Every example below is a real response from the live reference instance, captured through the MCP stdio interface.

## Tools

### sensor_list()

Devices, sites, sensor types, row counts, time coverage, and the sha256 of the backing data file. Call this first to see what the mesh holds:

```json
{
  "data_file": "sensormesh-sample.csv",
  "sha256": "022b54f909529cc80faed065f16e70824cb46c4c26e6efc61bfeb1be501a1197",
  "rows": 1296,
  "time_range": [
    "2026-09-08T00:00:00Z",
    "2026-09-08T23:50:00Z"
  ],
  "sensor_types": [
    "air_quality",
    "temperature",
    "noise"
  ],
  "devices": {
    "sm-001": { "site": "metro-core", "sensor_types": ["air_quality"], "readings": 144 },
    "sm-002": { "site": "metro-core", "sensor_types": ["temperature"], "readings": 144 },
    "sm-003": { "site": "metro-core", "sensor_types": ["noise"], "readings": 144 },
    "sm-004": { "site": "riverside-park", "sensor_types": ["air_quality"], "readings": 144 },
    "sm-005": { "site": "riverside-park", "sensor_types": ["temperature"], "readings": 144 },
    "sm-006": { "site": "riverside-park", "sensor_types": ["noise"], "readings": 144 },
    "sm-007": { "site": "north-industrial", "sensor_types": ["air_quality"], "readings": 144 },
    "sm-008": { "site": "north-industrial", "sensor_types": ["temperature"], "readings": 144 },
    "sm-009": { "site": "north-industrial", "sensor_types": ["noise"], "readings": 144 }
  }
}
```

(The API returns the same device map in expanded form; the listing above is the same data, one device per line.)

### sensor_query(filters, limit, format)

A filtered window of readings, up to 10 rows per call. Filter by device, site, sensor type, anomaly flag, or time range. JSON or CSV output. `sensor_query` with `{ "site": "riverside-park", "sensor": "air_quality", "limit": 3 }`:

```json
{
  "sha256": "022b54f909529cc80faed065f16e70824cb46c4c26e6efc61bfeb1be501a1197",
  "total_matched": 144,
  "returned": 3,
  "filters": { "site": "riverside-park", "sensor": "air_quality" },
  "rows": [
    { "timestamp": "2026-09-08T00:00:00Z", "device_id": "sm-004", "site": "riverside-park",
      "sensor_type": "air_quality", "value": 9, "unit": "ug/m3", "anomaly": "" },
    { "timestamp": "2026-09-08T00:10:00Z", "device_id": "sm-004", "site": "riverside-park",
      "sensor_type": "air_quality", "value": 8.3, "unit": "ug/m3", "anomaly": "" },
    { "timestamp": "2026-09-08T00:20:00Z", "device_id": "sm-004", "site": "riverside-park",
      "sensor_type": "air_quality", "value": 7.9, "unit": "ug/m3", "anomaly": "" }
  ]
}
```

`total_matched` tells you how many rows the filter hits; page through them with the paid HTTP endpoint, or regenerate the full dataset yourself — the sha256 pins the exact file the API serves. `format: "csv"` returns the same rows as CSV with the header `timestamp,device_id,site,sensor_type,value,unit,anomaly`.

### sensor_stats(filters)

Per-sensor min/mean/max and anomaly flag counts over the whole mesh, or scoped by any filter. Plain `sensor_stats()` with no arguments:

```json
{
  "scope": {},
  "stats": {
    "air_quality": {
      "readings": 432, "min": 0, "mean": 23.15, "max": 126.7,
      "anomaly_flags": { "spike": 2, "flatline": 1 }
    },
    "temperature": {
      "readings": 432, "min": 13.4, "mean": 21.72, "max": 40.3,
      "anomaly_flags": { "spike": 4, "stuck": 5 }
    },
    "noise": {
      "readings": 432, "min": 34.4, "mean": 57.09, "max": 84.9,
      "anomaly_flags": { "spike": 4, "passby": 20, "stuck": 9 }
    }
  }
}
```

## Install

Node 18+.

```sh
npm install -g @jayjex/sensormesh-mcp
```

### Claude Desktop config

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sensormesh": {
      "command": "npx",
      "args": ["-y", "@jayjex/sensormesh-mcp"]
    }
  }
}
```

### Cursor config

Same shape, in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{
  "mcpServers": {
    "sensormesh": {
      "command": "npx",
      "args": ["-y", "@jayjex/sensormesh-mcp"]
    }
  }
}
```

No configuration needed for the public reference instance. To point at your own SensorMesh API (the server from [sensormesh](https://github.com/jayjex/sensormesh), `mcp/api.js`), set one env var:

```json
{
  "mcpServers": {
    "sensormesh": {
      "command": "npx",
      "args": ["-y", "@jayjex/sensormesh-mcp"],
      "env": { "SENSORMESH_API_URL": "http://localhost:8793" }
    }
  }
}
```

`SENSORMESH_API_URL` is the only env var. If you don't set it, the server talks to the public reference instance.

## Failure behavior

Bad filter values fail closed instead of returning zero rows and leaving you guessing. `sensor_query` with `site: "harbor-front"` (not a real site) returns this error, listing the valid values:

```
MCP error -32602: Invalid enum value. Expected 'metro-core' | 'riverside-park' | 'north-industrial', received 'harbor-front' at site
```

API requests time out after 15 seconds and non-OK API responses surface as errors with the status code. Nothing here returns a silent empty result.

The 10-row cap is the API's free preview window. The same API also exposes `/v1/readings` with full pagination over x402 (USDC on Base, $0.001/call) for HTTP clients — this MCP package stays on the free endpoints, so there are no keys, wallets, or secrets anywhere in it.

## Development

```bash
git clone https://github.com/jayjex/sensormesh-mcp
cd sensormesh-mcp && npm install
node test/fixtures.test.mjs
```

The fixtures test runs offline against real responses captured from a running SensorMesh API: a 9-device inventory and a filtered preview (144 matches, 10-row window). For a full live round trip, run the API from the sensormesh repo, then the smoke test:

```bash
node ../sensormesh/mcp/api.js &
SENSORMESH_API_URL=http://127.0.0.1:8793 node test/smoke.mjs
```

The smoke test initializes the MCP server, calls all three tools (plus the CSV path and a bad-filter case), and asserts the responses.

## Related

- [jayjex/sensormesh](https://github.com/jayjex/sensormesh) — the commons itself: device simulator, sample data, dashboard, metered HTTP API.
- [jayjex/pdfcheck-mcp](https://github.com/jayjex/pdfcheck-mcp) — PDF page-tree QA server, same stdio pattern.

MIT license.