Coldchain

PyPI version License: MIT

Analyze cold-chain sensor data with AI agents. Connect your temperature/humidity logger to Claude, Cursor, or any MCP client and ask in plain language: "did this shipment breach the cold chain?", "find the anomalies in this log", "split this file into separate journeys."

🔒 Privacy: all analysis runs locally. Your data never leaves your machine. No external APIs, no cloud. Suitable for compliance-sensitive environments.

---

What is this? (start here if you're new to MCP)

MCP (Model Context Protocol) is a standard way to give an AI assistant access to external tools. This project is an MCP server — a small program that runs on your computer and gives an AI agent four specialized tools for analyzing sensor time-series data.

The idea: instead of pasting thousands of temperature readings into a chat and hoping the AI does the math right, the AI calls these tools, which compute the answer deterministically (same input, same result, every time). You ask a question in plain language; the agent runs the right tool and gives you a structured report.

---

Why use it

Language models are unreliable at statistics over large numeric series. They confuse a one-off sensor glitch with a real breach, lose track of timestamps, and produce different answers on re-runs. This server hands the agent deterministic, repeatable tools that get it right every time.

---

Tools

Tool	What it does
summary_stats	Summary statistics: min / max / mean / median / standard deviation, time range and duration.
detect_threshold_breaches	Detects threshold breaches (e.g. 2-8 degrees C) with minimum duration and hysteresis — separates a real breach from a momentary spike.
detect_anomalies	Flags outliers (global z-score, or deviation from a rolling mean).
segment_journey	Splits a continuous log into separate journeys based on time gaps (START/STOP).

---

Key distinction: a breach is not an anomaly

A sensor spiking to 40 degrees C for a single sample is an anomaly (a sensor glitch) — not a breach of the cold chain. A door left open, pushing the temperature to 12 degrees C for 20 minutes, is a breach, even though every individual reading looks plausible. This server distinguishes the two cases — exactly what a compliance audit requires.

---

Installation

The easiest way is with pip:

pip install coldchain-mcp

This installs the server and a command called coldchain-mcp. It's now ready to connect to any MCP client.

Alternative: from source

If you want to modify the server locally:

git clone https://github.com/matuzale/coldchain-mcp
cd coldchain-mcp
pip install -e .

---

Connecting to Claude Desktop

An MCP client (like Claude Desktop) needs to know how to start your server. You tell it through a small configuration file. Open Claude Desktop, go to Settings -> Developer -> Edit Config, and add a cold-chain entry.

If you installed with pip (recommended), the config is short — you just name the command:

{
  "mcpServers": {
    "cold-chain": {
      "command": "coldchain-mcp"
    }
  }
}

This works because pip install created a coldchain-mcp command that already knows where the code lives — so you don't have to point at any file.

If you're running from source instead, point at the script directly:

{
  "mcpServers": {
    "cold-chain": {
      "command": "python",
      "args": ["/full/path/to/coldchain-mcp/server.py"]
    }
  }
}

Windows note: if the short "command": "coldchain-mcp" form doesn't start the server, the install directory may not be on your system PATH. Either add Python's Scripts folder to PATH, or use the full path to coldchain-mcp.exe as the command.

After editing, fully restart Claude Desktop (quit from the system tray, not just the window). The tools appear automatically.

---

Data format

CSV with a header, or JSON. Column names are configurable via the ts_field and value_field parameters, and the parser recognizes common aliases (temp, temperature, time, value).

timestamp,value
2026-07-20T08:00:00,5.1
2026-07-20T08:05:00,4.9

JSON is also accepted:

[
  {"timestamp": "2026-07-20T08:00:00", "value": 5.1},
  {"timestamp": "2026-07-20T08:05:00", "value": 4.9}
]

---

Example (talking to the agent)

"Load sample_data.csv and check whether the shipment breached the 2-8 degrees C range. A breach only counts after 10 minutes."

The agent calls detect_threshold_breaches(min_temp=2, max_temp=8, min_duration_minutes=10) and returns a structured report of any breaches, with start time, end time, duration, and peak value.

---

Roadmap

• PDF report export
• MKT (Mean Kinetic Temperature) — pharmaceutical standard
• Humidity support and temperature/humidity correlation
• Multi-zone detectors for a single shipment

---

License

MIT — see LICENSE. You're free to use, modify, and distribute this, including commercially, as long as the copyright notice is retained.