# operational-data-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes operational and industrial telemetry to Claude and other MCP clients.

It ships with a sample ice cream packaging plant dataset (three machines, three days of hourly production, scheduled downtime events, and a couple of injected anomalies) so it works out of the box. Point it at your own JSON data via an environment variable to use it on real workloads.

```
npx operational-data-mcp
```

That's a working MCP server on stdio, no install step. Run on its own it sits
silent waiting for a client, which is correct behavior for stdio transport.

To see what it actually does without wiring up a client first:

```
git clone https://github.com/leemarcum/operational-data-mcp
cd operational-data-mcp && npm install && npm run demo
```

`npm run demo` starts the server, calls every tool over stdio, and prints exactly
what an MCP client receives — throughput attainment per machine, statistical
outliers in the hourly counts, and the downtime events behind them.

The rest of this README explains why it exists, how to wire it into Claude Desktop, what each tool does, and how to extend it for your own plant or operational system.

---

## Why this exists

Most "AI agent for operations" demos either skip the data-integration problem entirely or hand-wave it with a generic SQL connector. The hard part of doing this work for real is somewhere else: operational systems were built before MCP existed, the data is fragmented across vendors and protocols, and the security boundaries are there for good reasons.

I built this because I wanted a clean reference implementation of the pattern I keep using on real plants — a single MCP server that normalizes operational data into a few well-shaped tools an LLM can reason about. List your assets. Query production. Roll up throughput against target. Find the hours that look wrong. Same five questions on every plant floor, regardless of vendor.

The dataset is small on purpose. Replace it with yours and the same questions still apply.

---

## What you get

Five tools, three resources, one bundled dataset:

| Tool | What it does |
|---|---|
| `list_assets` | Returns every machine in the dataset with metadata (line, vendor, controller, target throughput). |
| `query_production` | Filters hourly production counts by asset id and time window. |
| `query_downtime` | Filters downtime events by asset, cause code, or time window. |
| `summarize_throughput` | Rolls up attainment percentage and downtime minutes per asset over a window. |
| `find_anomalies` | Runs a simple z-score anomaly detector over hourly production counts. |

Three resources (raw JSON, addressable by URI):

- `opdata://datasets/assets`
- `opdata://datasets/production`
- `opdata://datasets/downtime`

---

## Install and wire into Claude Desktop

Add this block to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "operational-data": {
      "command": "npx",
      "args": ["-y", "operational-data-mcp"]
    }
  }
}
```

Restart Claude Desktop. The five tools above will appear in the tool drawer. Ask Claude things like:

> Roll up Line A's attainment for June 2 and tell me what drove the gap from target.

> Are there any hours on the Line B cartoner that look like anomalies? What was happening around them?

> What's the most common downtime cause across all three assets?

---

## Use your own data

The server reads three JSON files from a directory. Set `OPDATA_DATA_DIR` to point at yours:

```json
{
  "mcpServers": {
    "operational-data": {
      "command": "npx",
      "args": ["-y", "operational-data-mcp"],
      "env": {
        "OPDATA_DATA_DIR": "/absolute/path/to/your/data"
      }
    }
  }
}
```

The directory must contain `assets.json`, `production.json`, and `downtime.json`. Schemas (intentionally minimal):

**`assets.json`** — array of:
```json
{
  "id": "LINE-A-FILLER",
  "name": "Line A Pint Filler",
  "line": "A",
  "type": "filler",
  "target_per_hour": 4800,
  "vendor": "Tetra Pak",
  "controller": "Allen-Bradley CompactLogix"
}
```

**`production.json`** — array of:
```json
{ "timestamp": "2026-06-01T06:00:00Z", "asset_id": "LINE-A-FILLER", "count": 4720 }
```

**`downtime.json`** — array of:
```json
{
  "asset_id": "LINE-A-FILLER",
  "start": "2026-06-02T02:00:00Z",
  "minutes": 90,
  "cause_code": "CIP_WASHDOWN",
  "note": "Scheduled clean-in-place"
}
```

Anything extra in those objects is preserved and returned to the client. That's intentional — keeps the schema honest while letting you carry your own metadata through.

---

## Run from source

```bash
git clone https://github.com/leemarcum/operational-data-mcp
cd operational-data-mcp
npm install
npm start
```

Inspect interactively with the official MCP Inspector:

```bash
npm run inspect
```

To regenerate the bundled sample data:

```bash
node scripts/generate-fixtures.js
```

---

## Where this goes next

Honest list of what I'd add when a real use case shows up:

- **Streaming sources** — swap the file-backed store for a Kafka/MQTT subscriber so production data flows in live. The tool surface stays the same; only the store layer changes.
- **More analyzers** — OEE rollups, shift comparisons, changeover-time tracking. All composable on top of the same primitives.
- **Auth and RBAC** — once an MCP server starts touching real operational data, you need ABAC at the tool level. The MCP protocol supports this; this reference doesn't implement it yet.
- **Bridging legacy controllers** — most plants I've worked in have at least one machine speaking Modbus or OPC UA. A thin adapter that polls those and writes into this server's format gets you most of the way.

If you're using this for something real and want one of those, open an issue.

---

## Why I built it

I spent fifteen years working in industrial automation — robotics, controls, plant networking — while writing production software in parallel. The pattern this server demonstrates is the one I keep using on real plants: take fragmented operational data that nobody can easily query, put it behind a small set of well-shaped tools, and let an LLM (or anyone else) answer the same five questions about it that an experienced operator would ask.

The cleanest production version of that pattern was at an ice cream plant where I networked previously-isolated lines together for real-time downtime and throughput visibility. The bundled dataset is a sanitized echo of what that data looked like.

— Lee Hunter Marcum
[github.com/leemarcum](https://github.com/leemarcum)

---

## License

MIT. See [LICENSE](./LICENSE).