TeleMcp

Mission control for Kubernetes hosts, exposed to LLM agents through MCP.

TeleMcp deploys a standard observability stack onto a Linux Kubernetes host via Ansible + Helm, then surfaces metrics, logs, and cluster state through a read-only MCP bridge so an LLM agent can bootstrap, monitor, triage, and operate the box.

For project goals, scope, and design principles, see INTENT.md.

Components

Component	Namespace	Role
kube-prometheus-stack	`monitoring`	Prometheus, Alertmanager, Grafana, node-exporter, kube-state-metrics
Loki + Promtail	`logging`	Log aggregation and shipping
OpenTelemetry Collector	`observability`	Optional OTLP fan-out to Prometheus and Loki
mcp-telemetry-bridge	`mcp`	FastAPI service exposing MCP resources, tools, and prompts

Quick Start

0) Prereqs

Ubuntu 24.04 host with k8s (k3s or kubeadm) reachable and kubectl context configured
Ansible 2.15+ on your control machine
Helm 3 on the host (Ansible role installs if missing)

1) Run Ansible

cd ansible
ansible-playbook -i inventories/local.ini playbook.yml

2) Smoke tests

From any machine with a kubectl context:

kubectl get pods -n monitoring
kubectl get pods -n logging
kubectl get pods -n mcp
kubectl port-forward -n mcp svc/mcp-telemetry-bridge 8080:80
curl http://localhost:8080/mcp/schema | jq .
curl http://localhost:8080/healthz

3) Point your LLM agent

Configure your agent's MCP client to the bridge endpoint (ClusterIP, Ingress, or port-forward).

Implemented tools:

Tool	Description
`promql.query`	Run a PromQL expression against Prometheus
`loki.query`	Run a LogQL query against Loki
`k8s.get`	Fetch Kubernetes objects (pods, nodes, deployments, etc.)
`k8s.events`	List cluster or namespace events
`inventory.snapshot`	JSON snapshot of nodes, namespaces, and workloads

Saved resources (via /mcp/resource?uri=...):

res://dashboards/top-pods-by-cpu.promql
res://dashboards/pod-restarts.promql
res://dashboards/warn-events.logql

The bridge currently exposes an HTTP schema approximation (/mcp/schema, /tools/...). Full MCP transport (stdio/SSE) is planned — see INTENT.md.

Repo layout

tele-mcp/
  INTENT.md                 # Project north star — goals, scope, current state
  ansible/                  # Bootstrap playbook and roles
  helm/
    values/                 # Chart values for monitoring, logging, OTel
    mcp-telemetry-bridge/   # Bridge Helm chart
  mcp-telemetry-bridge/       # FastAPI bridge application
  environments/             # Per-environment overrides
  wiki/                     # Extended project and design docs

Documentation

Document	Purpose
INTENT.md	Goals, principles, scope, success criteria
wiki/TeleMcpProject.md	Project overview and audience
wiki/TeleMcpBlueprint.md	Component rationale and bridge design
environments/dev/README.md	Dev environment notes

Security

MCP bridge ServiceAccount is read-only (get / list / watch only)
NetworkPolicy limits bridge egress to Prometheus and Loki
Consider mTLS or OIDC if exposing the bridge outside the cluster

Current limitations

See INTENT.md — Current State for the full list. Notable gaps:

Bridge container image is a placeholder (ghcr.io/example/telemcp-bridge)
No Alertmanager integration in the bridge yet
Host-level signals (systemd, certs, firewall) are deferred to a future DaemonSet sidecar

3.7 KiB Raw Blame History