influx-timeseries-mcp

A selective, aggregation-first Model Context Protocol (MCP) server for InfluxDB v2 (Flux), built for LLM use where flooding the context window with raw time-series points is the failure mode to avoid.

Status: in development. Design spec: docs/superpowers/specs/2026-06-12-influx-timeseries-mcp-design.md

Why

Generic InfluxDB MCP servers expose "run arbitrary Flux → return all rows." For time-series and event data that dumps tens of thousands of points into the model on a single query. This server inverts that: every path pushes reduction to InfluxDB and bounds its output, so the database returns kilobytes and the model stays focused.

Design

• Aggregation-first. All windowing, grouping, percentiles, and limits are expressed in the Flux sent to InfluxDB — the server never pulls raw series into memory to reduce them.

• Hybrid tool surface. Cheap discovery tools (measurements, tags, fields) + curated selective queries (aggregate, top_n, count_events, latest) + a guarded raw-Flux escape hatch (mandatory range, auto-injected limit, byte-capped response).

• Bounded by construction. Range is mandatory; results are double-capped (max rows AND max bytes); truncation is explicit, never a silent partial dump.

• Read-only. No write/admin tools; runs with a read-only InfluxDB token.

Runtime

Python + the MCP SDK (FastMCP), run as a stdio server. Packaged as a container for the homelab MCP gateway.

License

MIT — see LICENSE. Attribution in NOTICE.