Operational Data

A Model Context Protocol 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. 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):

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

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

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

{ "timestamp": "2026-06-01T06:00:00Z", "asset_id": "LINE-A-FILLER", "count": 4720 }

downtime.json — array of:

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

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

Inspect interactively with the official MCP Inspector:

npm run inspect

To regenerate the bundled sample data:

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 Marcum github.com/Spheresdeep0322

---

License

MIT. See LICENSE.