Skip to content

Prometheus tools#

The Lens MCP Server provides six Prometheus tools for querying metrics, viewing alerts, and inspecting scrape targets on your connected clusters.

Prerequisites#

  • Lens MCP Server enabled and connected to your AI assistant (see Get started with Lens MCP Server)
  • At least one cluster connected via the MCP Server
  • Prometheus running on the target cluster

Note

Prometheus must be running on the target cluster for these tools to work. The tools use the Lens internal proxy to reach the Prometheus API.

prometheus-list-metrics#

List available metric names from Prometheus. Supports filtering and pagination.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query
match string No Series selector to filter metrics (e.g., {job="prometheus"})
limit number No Maximum results to return. Default: 500
offset number No Number of results to skip for pagination. Default: 0

Example prompt: "List all available Prometheus metrics on my production cluster."

Response format:

{
  "metrics": ["container_cpu_usage_seconds_total", "container_memory_working_set_bytes"],
  "total": 1234,
  "offset": 0,
  "limit": 500
}

prometheus-get-metric-metadata#

Get metadata (type, help text, unit) for metrics. Use this to understand what a metric measures before writing queries.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query
metric string No Filter metadata for a specific metric name
limit number No Maximum number of metrics to return metadata for

Example prompt: "What does the container_cpu_usage_seconds_total metric measure?"

Response format:

{
  "container_cpu_usage_seconds_total": [
    {
      "type": "counter",
      "help": "Cumulative cpu time consumed by the container in core-seconds",
      "unit": ""
    }
  ]
}

prometheus-get-alerts#

Get currently firing alerts from Prometheus. Use this for instant cluster health diagnosis without writing PromQL.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query

Example prompt: "Are there any firing alerts on my production cluster?"

Response format:

{
  "alerts": [
    {
      "labels": { "alertname": "HighMemoryUsage", "namespace": "default" },
      "annotations": { "summary": "Memory usage above 90%" },
      "state": "firing",
      "activeAt": "2025-01-15T10:30:00Z",
      "value": "0.92"
    }
  ]
}

prometheus-get-targets#

Get Prometheus scrape targets and their status. Use this to diagnose monitoring coverage and scrape failures.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query
state string No Filter by state: active, dropped, or any (default)
limit number No Maximum targets per state. Default: 50
offset number No Number of targets to skip. Default: 0

Example prompt: "Show me all the Prometheus scrape targets that are down."

Response format:

{
  "activeTargets": [],
  "activeTargetsTotal": 42,
  "droppedTargets": [],
  "droppedTargetsTotal": 3,
  "offset": 0,
  "limit": 50
}

prometheus-get-label-values#

Get all values for a specific Prometheus label. Use this to discover available namespaces, pods, jobs, and other dimensions before writing queries.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query
labelName string Yes The label name (e.g., namespace, pod, job)
match string No Series selector to restrict values (e.g., {job="prometheus"})
limit number No Maximum values to return. Default: 500
offset number No Number of values to skip. Default: 0

Example prompt: "What namespaces are being monitored by Prometheus?"

Response format:

{
  "label": "namespace",
  "values": ["default", "kube-system", "monitoring", "ingress-nginx"],
  "total": 4,
  "offset": 0,
  "limit": 500
}

prometheus-execute-range-query#

Execute a PromQL range query. Returns time-series data over a specified time range.

Parameters:

Parameter Type Required Description
clusterId string Yes The cluster to query
query string Yes The PromQL expression to evaluate
start string Yes Start timestamp (RFC3339 or Unix)
end string Yes End timestamp (RFC3339 or Unix)
step string No Resolution step width (e.g., 15s, 1m). Default: auto

Example prompt: "Show me the CPU usage for the api-server over the last hour, sampled every minute."

Tip

You do not need to write PromQL yourself. Describe what you want in natural language and your AI assistant constructs the query.

Typical workflow#

  1. Check alerts — get an instant overview of cluster health.
  2. List metrics — discover what metrics are available.
  3. Get metadata — understand what a metric measures.
  4. Get label values — discover dimensions (namespaces, pods, jobs).
  5. Execute range queries — analyze trends over time.