Sensormesh MCP Server

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:

{
  "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 }:

{
  "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:

{
  "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+.

npm install -g @jayjex/sensormesh-mcp

Claude Desktop config

Add to claude_desktop_config.json:

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

Cursor config

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

{
  "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, mcp/api.js), set one env var:

{
  "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

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:

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 — the commons itself: device simulator, sample data, dashboard, metered HTTP API.
• jayjex/pdfcheck-mcp — PDF page-tree QA server, same stdio pattern.

MIT license.