# 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`](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](LICENSE). Attribution in [NOTICE](NOTICE).