MCP Prometheus

Un serveur MCP ( Model Context Protocol ) complet pour Prometheus, écrit en Go.

Il fournit un accès complet aux métriques, aux requêtes et aux informations système de Prometheus via des interfaces MCP standardisées, permettant aux assistants IA d'exécuter des requêtes PromQL, de découvrir des métriques, d'explorer des étiquettes et d'analyser votre infrastructure de surveillance.

Caractéristiques

exécution de requêtes

• Requêtes instantanées avec horodatage en option et paramètres améliorés
• Requêtes de plage avec limites temporelles, intervalles d'étape et options de performance
• Optimisation des requêtes avec des paramètres de délai, de limite et de statistiques
• Troncature des résultats avec guidage intelligent de l'utilisateur pour les grands ensembles de données

📊 Découverte de métriques

• Liste de toutes les mesures disponibles avec filtrage et sélection temporelle
• Obtenir des métadonnées détaillées pour des mesures spécifiques
• Exploration des métriques avec des options de filtrage améliorées

🏷️ Découverte des étiquettes et des séries

• Liste de tous les noms d'étiquettes avec filtrage et limites
• Obtenir les valeurs des étiquettes pour des étiquettes spécifiques avec un filtrage avancé
• Recherche de séries à l'aide de sélecteurs d'étiquettes avec des limites temporelles
• Recherche avancée d'étiquettes avec des sélecteurs complexes

🎯 Informations sur les cibles et les systèmes

• Récupérer les informations sur la cible et l'état de santé
• Informations sur la construction et les détails de la version
• Informations d'exécution et état du système
• Inspection de la configuration et des drapeaux
• Statistiques TSDB et informations sur la cardinalité

🚨 Alertes et règles

• Surveillance des alertes actives
• Découverte et état d'AlertManager
• Inspection des règles d'enregistrement et d'alerte

🔬 F onctionnalités avancées

• Requêtes exemplaires pour la corrélation des traces
• Exploration des métadonnées de la cible
• Prise en charge de plusieurs locataires avec des identifiants d'organisation dynamiques
• Configuration dynamique du client par requête

🔐 Authentification et transport

• Méthodes d'authentification multiples (Basic, Bearer token)
• En-têtes d'organisation multi-locataires (Cortex, Mimir, Thanos)
• Protocoles de transport multiples (stdio, SSE, HTTP)
• Distribution binaire multiplateforme

Installation

Binaires préconstruits

Téléchargez le dernier binaire pour votre plateforme à partir de la page des versions.

A partir de la source

git clone https://github.com/giantswarm/mcp-prometheus.git cd mcp-prometheus go build -o mcp-prometheus

Configuration du serveur

Configurez le serveur MCP à l'aide de variables d'environnement (toutes optionnelles) :

# Facultatif : Configuration par défaut du serveur Prometheus export PROMETHEUS_URL=http://your-prometheus-server:9090 # Facultatif : Références d'authentification (en choisir une) # Pour l'authentification de base export PROMETHEUS_USERNAME=votre_nom d'utilisateur export PROMETHEUS_PASSWORD=votre_mot_de_passe # Pour l'authentification par jeton porteur export PROMETHEUS_TOKEN=votre_jeton # Facultatif : ID d'organisation par défaut pour les configurations multi-locataires export PROMETHEUS_ORGID=votre_identification_d'organisation

Configuration dynamique: Tous les outils MCP prennent en charge les paramètres prometheus_url et org_id pour la configuration par requête, ce qui vous permet d'interroger plusieurs instances Prometheus et organisations de manière dynamique.

Utilisation

Ligne de commande

Démarrer le serveur avec le transport stdio (par défaut) :

./mcp-prometheus

Démarrer avec le transport HTTP pour les clients basés sur le web :

./mcp-prometheus serve --transport sse --http-addr :8080

Configuration du client MCP

Ajoutez la configuration du serveur à votre client MCP. Par exemple, avec Claude Desktop :

{ "mcpServers" : { "prometheus" : { "command" : "/path/to/mcp-prometheus", "args" : ["serve"], "env" : { "PROMETHEUS_URL" : "http://your-prometheus-server:9090", "PROMETHEUS_ORGID" : "your-default-org" } } }

Outils disponibles

🔍 Outils d'exécution de requêtes

📊 Outils de découverte de métriques

🏷️ Outils de découverte d'étiquettes et de séries

🎯 Outils d'information sur les cibles et les systèmes

🚨 Outils d'alerte et de règles

🔬 Outils avancés

🔧 Paramètres améliorés

Paramètres de connexion (disponibles sur tous les outils) :

• prometheus_url: URL du serveur Prometheus (par exemple,'http://localhost:9090')
• org_id: ID de l'organisation pour les configurations à plusieurs locataires (par exemple, "tenant-123")

Paramètres d'amélioration de la requête:

• timeout: Délai d'attente de la requête (par exemple, '30s', '1m', '5m')
• limit: Nombre maximum d'entrées retournées
• stats: Inclure les statistiques de la requête ('all')
• lookback_delta: Délai de retour de la requête (par exemple, '5m')
• unlimited: Définir à "true" pour une sortie illimitée (ATTENTION : peut avoir un impact sur les performances)

Paramètres de filtrage temporel:

• start_time, end_time: Horodatage RFC3339 pour le filtrage
• matches: Tableau de correspondance d'étiquettes (par exemple, ['{job="prometheus"}', '{__name__=~"http_.*"}'])

Exemple d'utilisation

Exécution d'une requête de base

{"query" : "up", "prometheus_url" : "http://prometheus:9090", "org_id" : "production" }

Requête améliorée avec options de performance

{ "query" : "rate(http_requests_total[5m])", "prometheus_url" : "http://prometheus:9090", "timeout" : "30s", "limit" : "100", "stats" : "all" }

Requête sur l'étendue avec des limites temporelles

{ "query" : "cpu_usage_percent", "start" : "2025-01-27T00:00:00Z", "end" : "2025-01-27T01:00:00Z", "step" : "1m", "prometheus_url" : "http://prometheus:9090" }

Découverte d'étiquettes avec filtrage

{ "prometheus_url" : "http://prometheus:9090", "matches" : ["up{job=\"kubernetes-nodes"}"], "limit" : "20" }

Découverte de la série

{"matches" : ["{__name__=~\"http_.*\", job=\"api-server\"}"], "prometheus_url" : "http://prometheus:9090", "start_time" : "2025-01-27T00:00:00Z", "limit" : "50" }

Requête multi-locataire

{ "query" : "container_memory_usage_bytes", "prometheus_url" : "http://cortex-gateway:8080/prometheus", "org_id" : "team-platform" }

Optimisation des résultats des requêtes

Le serveur MCP comprend une gestion intelligente des résultats des requêtes :

• Troncature automatique pour les résultats > 50k caractères
• Guide de l'utilisateur pour l'optimisation des requêtes lorsque les résultats sont volumineux
• Conseils sur les performances, y compris les fonctions d'agrégation et de filtrage
• Option de sortie illimitée avec avertissements sur les performances

Exemple de message de troncature :

⚠️ RÉSULTAT TRONQUÉ : La requête a renvoyé un résultat très volumineux (>50k caractères). 💡 Pour optimiser votre requête et obtenir moins de résultats, envisagez : - d'ajouter des filtres d'étiquettes plus spécifiques : {app="specific-app", namespace="specific-ns"} - Utiliser des fonctions d'agrégation : sum(), avg(), count(), etc. - Utiliser topk() ou bottomk() pour obtenir uniquement les N résultats supérieurs/inférieurs 🔧 Pour obtenir le résultat complet non tronqué, ajouter "unlimited" : "true" à vos paramètres de requête

Options de transport

Le serveur prend en charge plusieurs protocoles de transport :

stdio (par défaut)

./mcp-prometheus serve --transport stdio

SSE (événements envoyés par le serveur)

./mcp-prometheus serve --transport sse --http-addr :8080

HTTP en flux continu

./mcp-prometheus serve --transport streamable-http --http-addr :8080

Développement

L'architecture

Le serveur suit une architecture moderne, DRY :

• Enregistrement modulaire des outils avec réutilisation des paramètres
• Création dynamique de clients pour la prise en charge de plusieurs instances
• Gestion centralisée des erreurs et validation des paramètres
• Fonctions d'aide pour réduire la répétition du code de 90 %

Structure du projet

mcp-prometheus/ ├── cmd/ # Commandes CLI et informations de version ├── internal/ │ ├── server/ # Contexte et configuration du serveur │ └── tools/prometheus/ # 18 outils MCP complets ├── main.go # Point d'entrée de l'application ├── go.mod # Dépendances Go └── README.md # Cette documentation

Amélioration de la qualité du code

• 500+ lignes réduites à ~85 lignes dans l'enregistrement principal
• Élimination de plus de 255 lignes redondantes
• Fonctions d'aide aux paramètres pour des définitions de paramètres DRY
• Gestion centralisée des clients avec configuration dynamique
• Traitement cohérent des erreurs dans tous les outils

Construction et test

# Construire le binaire go build -o mcp-prometheus # Exécuter les tests go test ./..

Authentification

Authentification de base

export PROMETHEUS_USERNAME=myuser export PROMETHEUS_PASSWORD=mypassword

Authentification par jeton porteur

export PROMETHEUS_TOKEN=mon-token-porteur

Support multi-locataires

Parfait pour Cortex, Mimir, Thanos et autres configurations multi-locataires :

export PROMETHEUS_ORGID=tenant-123

Gestion des erreurs

Gestion complète des erreurs avec des messages détaillés :

• Conseils deconfiguration manquants
• Détails de l'échec de l'authentification
• Dépannage de laconnectivité réseau
• Assistance en cas de requêtePromQL invalide
• Explications deserreurs de l'API Prometheus
• Gestion des erreurs lors dela création d'un client dynamique

Contribuer

1. Créer un référentiel (Fork)
2. Créer une branche de fonctionnalités(git checkout -b feature/amazing-feature)
3. Livrez vos modifications(git commit -m 'Add some amazing feature')
4. Pousser vers la branche(git push origin feature/amazing-feature)
5. Ouvrir une Pull Request

Licence

Ce projet est sous licence selon les mêmes termes que l'implémentation originale de Python.