# poly-observability-mcp

[![OpenSSF Best Practices](https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensourcesecurity)](https://www.bestpractices.dev/en/projects/new?repo_url=https://github.com/hyperpolymath/poly-observability-mcp)
[![RSR Compliant](https://img.shields.io/badge/RSR-compliant-gold)](https://github.com/hyperpolymath/rhodium-standard-repositories)
[![MCP Server](https://img.shields.io/badge/MCP-server-blue)](https://github.com/modelcontextprotocol)
[![License: PMPL-1](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://github.com/hyperpolymath/palimpsest-license)
[![Green Web](https://api.thegreenwebfoundation.org/greencheckimage/github.com)](https://www.thegreenwebfoundation.org/green-web-check/?url=github.com)

Unified MCP server for observability and monitoring. Provides Model Context Protocol tools for querying metrics, logs, and traces through Prometheus, Grafana, Loki, and Jaeger.

## Overview

poly-observability-mcp exposes observability capabilities through the Model Context Protocol (MCP), enabling AI assistants and other MCP clients to query metrics, search logs, analyze traces, and manage dashboards across the observability stack.

## Adapters

### Prometheus (8 tools)
Metrics querying and alerting:

* `prometheus_query` - Execute an instant PromQL query
* `prometheus_query_range` - Execute a range PromQL query
* `prometheus_series` - List time series matching a selector
* `prometheus_labels` - List all label names
* `prometheus_label_values` - List values for a specific label
* `prometheus_targets` - Get current scrape targets and their status
* `prometheus_alerts` - Get current active alerts
* `prometheus_rules` - Get alerting and recording rules

### Grafana (8 tools)
Dashboard and visualization management:

* `grafana_search_dashboards` - Search for dashboards by name or tag
* `grafana_get_dashboard` - Get a dashboard by UID
* `grafana_list_datasources` - List all configured data sources
* `grafana_get_datasource` - Get data source details by name
* `grafana_list_folders` - List all dashboard folders
* `grafana_get_alert_rules` - Get all alert rules
* `grafana_get_annotations` - Get annotations within a time range
* `grafana_get_org` - Get current organization info

### Loki (7 tools)
Log aggregation and querying:

* `loki_query` - Execute an instant LogQL query
* `loki_query_range` - Execute a range LogQL query
* `loki_labels` - List all label names
* `loki_label_values` - List values for a specific label
* `loki_series` - List log streams matching a selector
* `loki_tail` - Get recent logs (snapshot of tail)
* `loki_index_stats` - Get index statistics

### Jaeger (5 tools)
Distributed tracing:

* `jaeger_services` - List all services in Jaeger
* `jaeger_traces` - Get traces for a service
* `jaeger_trace` - Get a specific trace by ID
* `jaeger_operations` - Get operations for a service
* `jaeger_dependencies` - Get service dependency graph

## Requirements

* [Deno](https://deno.land/) runtime
* [Prometheus](https://prometheus.io/) (for metrics tools)
* [Grafana](https://grafana.com/) (for dashboard tools)
* [Loki](https://grafana.com/oss/loki/) (for log tools)
* [Jaeger](https://www.jaegertracing.io/) (for tracing tools)

## Configuration

### Prometheus

```bash
export PROMETHEUS_URL=http://localhost:9090
```

### Grafana

```bash
export GRAFANA_URL=http://localhost:3000
export GRAFANA_API_KEY=your-api-key
```

### Loki

```bash
export LOKI_URL=http://localhost:3100
```

### Jaeger

```bash
export JAEGER_URL=http://localhost:16686
```

## Installation

```bash
git clone https://github.com/hyperpolymath/poly-observability-mcp
cd poly-observability-mcp
deno cache main.js
```

**📌 NOTE**\
This project uses Deno with npm: specifiers. No `npm install` required.

## Usage

Run as MCP server:

```bash
deno run --allow-read --allow-env --allow-net main.js
```

Or use the systemd service:

```bash
systemctl --user enable poly-observability-mcp
systemctl --user start poly-observability-mcp
```

## Use Cases

* Query application metrics and performance data
* Search and analyze logs across services
* Trace requests through distributed systems
* Monitor and manage Grafana dashboards
* Investigate incidents using correlated telemetry

## License

MIT

## OPSM Link

```
OPSM Core
  |
  v
poly-observability-mcp (observability telemetry for OPSM)

```