Grafana

resmi

Grafana örneğinizde panoları arayın, olayları inceleyin ve veri kaynaklarını sorgulayın.

GitHub
3.4k

Grafana MCP ile neler yapabilirsiniz?

  • Panoları arayın ve inceleyin — search_dashboards ve get_dashboard_summary kullanarak panoları bulun ve tam JSON olmadan kompakt özetler alın.
  • Prometheus ve Loki sorgulayın — Veri kaynaklarınızda PromQL ve LogQL sorguları çalıştırın; meta veriler ve histogram yüzdelikleri dahil.
  • Uyarıları yönetin — Uyarı kurallarını listeleyin, oluşturun, güncelleyin ve silin; ayrıca bildirim politikalarını ve iletişim noktalarını görüntüleyin.
  • Derin bağlantılar oluşturun — Gezinme araçlarıyla zaman aralıkları içeren panolara, panellere ve Explore'a doğru URL'ler oluşturun.
  • Panel sorgularını çalıştırın — run_panel_query kullanarak bir pano panelinin sorgusunu özel zaman aralıkları ve değişkenlerle yürütün.

Dokümantasyon

Grafana MCP sunucusu

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Grafana için bir Model Context Protocol (MCP) sunucusu.

Bu, Grafana örneğinize ve çevresindeki ekosisteme erişim sağlar.

Hızlı Başlangıç

uv gerektirir. Aşağıdakini MCP istemci yapılandırmanıza (örn. Claude Desktop, Cursor) ekleyin:

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Grafana Cloud için, GRAFANA_URL değerini örnek URL'nizle değiştirin (örn. https://myinstance.grafana.net). Docker, ikili dosya ve Helm dahil daha fazla kurulum seçeneği için Kullanım bölümüne bakın.

Gereksinimler

  • Tam işlevsellik için Grafana sürüm 9.0 veya üzeri gereklidir. Özellikle veri kaynağıyla ilgili işlemler olmak üzere bazı özellikler, eksik API uç noktaları nedeniyle daha eski sürümlerde düzgün çalışmayabilir.

Özellikler

Aşağıdaki özellikler şu anda MCP sunucusunda mevcuttur. Bu liste yalnızca bilgilendirme amaçlıdır ve bir yol haritası veya gelecekteki özellikler için taahhüt anlamına gelmez.

Panolar

  • Pano arama: Panoları başlığa veya diğer meta verilere göre bulun
  • UID ile pano alma: Benzersiz tanımlayıcısını kullanarak pano ayrıntılarının tamamını alın. Uyarı: Büyük panolar önemli miktarda bağlam penceresi alanı tüketebilir.
  • Pano özeti alma: Tam JSON olmadan başlık, panel sayısı, panel türleri, değişkenler ve meta veriler dahil bir panonun kompakt bir özetini alın; böylece bağlam penceresi kullanımı en aza indirilir
  • Pano özelliği alma: Yalnızca ihtiyaç duyulan verileri almak ve bağlam penceresi tüketimini azaltmak için JSONPath ifadelerini (örn. $.title, $.panels[*].title) kullanarak bir panonun belirli bölümlerini çıkarın
  • Pano güncelleme veya oluşturma: Mevcut panoları değiştirin veya yenilerini oluşturun. Uyarı: Büyük miktarda bağlam penceresi alanı tüketebilen tam pano JSON'u gerektirir.
  • Panoyu yama uygulama: Tam JSON gerektirmeden bir panoda belirli değişiklikler yapın; hedefli değişiklikler için bağlam penceresi kullanımını önemli ölçüde azaltır
  • Panel sorgularını ve veri kaynağı bilgilerini alma: Bir panodaki her panelden başlığı, sorgu dizesini ve veri kaynağı bilgilerini (varsa UID ve tür dahil) alın

Panel Sorgusu Çalıştırma

Not: Panel sorgusu çalıştırma araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için runpanelquery değerini --enabled-tools bayrağınıza ekleyin.

  • Panel sorgusu çalıştırma: Özel zaman aralıkları ve değişken geçersiz kılmalarıyla bir pano panelinin sorgusunu yürütün.

Bağlam Penceresi Yönetimi

Pano araçları artık bağlam penceresi kullanımını etkili bir şekilde yönetmek için çeşitli stratejiler içerir (issue #101):

  • Pano genel bakışı ve değişiklik planlaması için get_dashboard_summary kullanın
  • Yalnızca belirli pano bölümlerine ihtiyacınız olduğunda get_dashboard_property öğesini JSONPath ile kullanın
  • Tam pano JSON'una özel olarak ihtiyaç duymadıkça get_dashboard_by_uid kullanmaktan kaçının

Veri Kaynakları

  • Veri kaynağı bilgilerini listeleme ve alma: Yapılandırılmış tüm veri kaynaklarını görüntüleyin ve her biri hakkında ayrıntılı bilgi alın.
    • Desteklenen veri kaynağı türleri: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Sorgu Örnekleri

Not: Sorgu örnekleri araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için examples değerini --enabled-tools bayrağınıza ekleyin.

  • Sorgu örnekleri alma: Sorgu sözdizimini öğrenmek için farklı veri kaynağı türleri için örnek sorgular alın.

Prometheus Sorgulama

  • Prometheus sorgulama: Prometheus veri kaynaklarına karşı PromQL sorguları yürütün (hem anlık hem de aralık metrik sorgularını destekler).
  • Prometheus meta verilerini sorgulama: Prometheus veri kaynaklarından metrik meta verilerini, metrik adlarını, etiket adlarını ve etiket değerlerini alın.
  • Histogram yüzdeliklerini sorgulama: histogram_quantile kullanarak histogram yüzdelik değerlerini (p50, p90, p95, p99) hesaplayın.

Loki Sorgulama

  • Loki günlüklerini ve metriklerini sorgulama: Loki veri kaynaklarına karşı LogQL kullanarak hem günlük sorgularını hem de metrik sorgularını çalıştırın.
  • Loki meta verilerini sorgulama: Loki veri kaynaklarından etiket adlarını, etiket değerlerini ve akış istatistiklerini alın.
  • Loki desenlerini sorgulama: Yaygın günlük yapılarını ve anormallikleri belirlemek için Loki tarafından algılanan günlük desenlerini alın.

InfluxDB Sorgulama

Not: InfluxDB araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için influxdb değerini --enabled-tools bayrağınıza ekleyin.

  • InfluxDB sorgulama: InfluxDB veri kaynaklarına karşı InfluxQL (v1.x) veya Flux (v2.x) kullanarak sorgular yürütün. Lehçe, veri kaynağı yapılandırmasından çıkarılır veya dialect parametresi aracılığıyla açıkça ayarlanabilir.

ClickHouse Sorgulama

Not: ClickHouse araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için clickhouse değerini --enabled-tools bayrağınıza ekleyin.

  • ClickHouse tablolarını listeleme: Bir ClickHouse veritabanındaki tüm tabloları satır sayıları ve boyutlarıyla birlikte listeleyin.
  • Tablo şemasını tanımlama: Bir ClickHouse tablosu için sütun adlarını, türlerini ve meta verilerini alın.
  • ClickHouse sorgulama: Grafana makro ve değişken ikame desteğiyle SQL sorguları yürütün.

CloudWatch Sorgulama

Not: CloudWatch araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için cloudwatch değerini --enabled-tools bayrağınıza ekleyin.

  • CloudWatch ad alanlarını listeleme: Kullanılabilir AWS CloudWatch ad alanlarını keşfedin.
  • CloudWatch metriklerini listeleme: Belirli bir ad alanında bulunan metrikleri listeleyin.
  • CloudWatch boyutlarını listeleme: Metrik sorgularını filtrelemek için boyutları alın.
  • CloudWatch sorgulama: Zaman aralığı desteğiyle CloudWatch metrik sorguları yürütün.

Graphite Sorgulama

Not: Graphite araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için graphite değerini --enabled-tools bayrağınıza ekleyin.

  • Graphite sorgulama: Bir Graphite veri kaynağına karşı Graphite render API sorguları yürütün.
  • Graphite metriklerini listeleme: Graphite metrik yollarına göz atın ve keşfedin.
  • Graphite etiketlerini listeleme: Kullanılabilir Graphite etiketlerini ve etiket değerlerini listeleyin.
  • Graphite yoğunluğunu sorgulama: Belirli bir desen için Graphite metrik yoğunluğunu sorgulayın.

Athena Sorgulama

Not: Athena araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için athena değerini --enabled-tools bayrağınıza ekleyin.

  • Athena kataloglarını listeleme: Kullanılabilir veri kataloglarını keşfedin (örn. AwsDataCatalog, Iceberg bağlayıcıları).
  • Athena veritabanlarını listeleme: Bir Athena kataloğundaki veritabanlarını listeleyin.
  • Athena tablolarını listeleme: Bir Athena veritabanındaki tabloları listeleyin.
  • Athena tablosunu tanımlama: Bir Athena tablosu için sütun adlarını alın.
  • Athena sorgulama: Makro ikamesi, limit zorlaması ve şablon değişkeni desteğiyle Grafana üzerinden Amazon Athena'ya karşı SQL sorguları yürütün.

Snowflake Sorgulama

Not: Snowflake araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için snowflake değerini --enabled-tools bayrağınıza ekleyin.

Sorgular Grafana'nın Snowflake veri kaynağından (Grafana Enterprise eklentisi grafana-snowflake-datasource) geçer, bu nedenle kimlik doğrulama Grafana'daki veri kaynağı yapılandırması tarafından yönetilir — kimlik bilgileri MCP sunucusu tarafından asla görülmez. Bu, ClickHouse araçları için kullanılan modelle aynıdır.

  • Snowflake tablolarını listeleme: INFORMATION_SCHEMA.TABLES aracılığıyla tabloları (veritabanı, şema, tür, satır sayısı ve boyutla birlikte) keşfedin. İsteğe bağlı veritabanı/şema filtreleri.
  • Tablo şemasını tanımlama: Bir Snowflake tablosu için sütun adlarını, veri türlerini, boş değer kabul edilebilirliğini, varsayılanları ve yorumları alın.
  • Snowflake sorgulama: Makro ve değişken ikame desteğiyle SQL sorguları yürütün. Günlükler ve izlemeler için Snowflake'in olay tablolarını (örn. SNOWFLAKE.TELEMETRY.EVENTS) veya herhangi bir kullanıcı tablosunu sorgulamak için kullanışlıdır.
    • Desteklenen makrolar: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (saniye), $__interval_ms ve şablon değişkeni ikamesi için ${varname}.

Elasticsearch/OpenSearch Sorgulama

Not: Elasticsearch/OpenSearch araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için elasticsearch değerini --enabled-tools bayrağınıza ekleyin.

  • Elasticsearch/OpenSearch sorgulama: Lucene sorgu sözdizimini veya Elasticsearch Query DSL'ini kullanarak Elasticsearch veya OpenSearch veri kaynaklarına karşı arama sorguları yürütün. Zaman aralığına göre filtrelemeyi ve günlükleri, metrikleri veya dizine eklenmiş herhangi bir veriyi almayı destekler. Dizinleri, kimlikleri, kaynak alanları ve isteğe bağlı alaka puanıyla birlikte belgeleri döndürür.

Quickwit Sorgulama

Not: Quickwit araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için quickwit değerini --enabled-tools bayrağınıza ekleyin.

  • Quickwit sorgulama: Lucene sorgu sözdizimini veya kısmi Elasticsearch uyumlu Query DSL'ini kullanarak Quickwit veri kaynaklarına karşı arama sorguları yürütün. Zaman aralığına göre filtrelemeyi ve günlükleri veya diğer dizine eklenmiş belgeleri almayı destekler. Dizinleri, kimlikleri, kaynak alanları ve isteğe bağlı alaka puanıyla birlikte belgeleri döndürür.

Ajan Gözlemlenebilirliği

Not: Ajan Gözlemlenebilirliği araçları varsayılan olarak devre dışıdır ve yalnızca Grafana Cloud'da çalışır. Bunları etkinleştirmek için agento11y değerini --enabled-tools bayrağınıza ekleyin.

  • Konuşmaları listeleme ve arama: Son LLM konuşmalarını listeleyin veya bir zaman aralığı boyunca bir filtre ifadesiyle (model, sağlayıcı, ajan, durum, hata türü, değerlendirme sonuçları ve daha fazlası) arayın. Arama sonuçları hata sayılarını, derecelendirme özetlerini, değerlendirme özetlerini ve izleme kimliklerini içerir.
  • Konuşma ayrıntısı alma: Tek bir konuşmayı, istemler ve çıktılar dahil tüm üretimleriyle birlikte getirin.
  • Üretim ayrıntısı ve puanları alma: Kimliğe göre tek bir üretimi ve değerlendirme puanlarını (değerlendirici, puan anahtarı, değer, geçti, açıklama) getirin.
  • Ajan kataloğunu okuma: Telemetri gönderen ajanları listeleyin, bir ajan sürümünü tam olarak getirin (tam sistem istemi, JSON şemasıyla birlikte her araç ve üzerinde çalıştığı modeller), bir ajanın sürüm geçmişinde ilerleyin ve sürüm başına değerlendirme puanı toplamlarını karşılaştırın. Etkili sürümler, bir araç değişikliğinin asla etkilemediği sha256: karmalarıdır; kendi sürümünü bildirmeyen bir ajan için sistem istemini karmalarlar, bu nedenle bir istem düzenlemesi yeni bir sürüm oluşturur. Katalog ve sürüm satırları, tam bir istem getirmeden önce kontrol etmeye değer bir token_estimate taşır.
  • Değerlendiricileri ve şablonları inceleme: Bir puanın geldiği değerlendiricileri, bunların türetildiği şablonları ve LLM yargıcı değerlendiricileri için kullanılabilir yargıç sağlayıcılarını ve modellerini okuyun. Yazma araçları etkinken ayrıca değerlendiriciler oluşturun, çatallayın, test edin ve silin.
  • Değerlendirme kurallarını ve korumaları inceleme: Değerlendiricileri üretim trafiğine bağlayan eşzamansız değerlendirme kurallarını ve satır içi çalışan ve uyarabilen veya reddedebilen korumaları (kanca kuralları) okuyun. Yazma araçları etkinken ayrıca bunları oluşturun, güncelleyin, önizleyin ve silin. Yazma işlemleri ve kalıcı olmayan preview_rule ve test_evaluator işlemleri, Agento11y Yönetici rolü tarafından verilen grafana-agento11y-app.eval:write iznini gerektirir.
  • Kaydedilmiş konuşmaları ve koleksiyonları düzenleme: Kaydedilmiş konuşmaları (bir konuşmaya sabit bir kimlik, ad ve etiket veren yer imleri) ve bunları gruplayan koleksiyonları, her koleksiyonun üye sayısı ve her kaydedilmiş konuşma satırına gömülü koleksiyonlar dahil okuyun. Yazma araçları etkinken ayrıca bir konuşmayı yer imlerine ekleyin, koleksiyonlar oluşturun ve düzenleyin ve üye ekleyin veya kaldırın. Bu yazma işlemleri aynı grafana-agento11y-app.eval:write iznini gerektirir.
  • Test paketlerini okuma ve düzenleme: Çevrimdışı deneylerin karşı çalıştığı sürümlenmiş test paketlerini listeleyin, birini tam sürüm geçmişiyle okuyun ve bir sürümün test durumlarında sayfalama yapın. Yazma araçları etkinken ayrıca bir paket oluşturun, yeniden adlandırın veya yeniden etiketleyin, bir taslak sürüm açın, yayınlayın ve test durumlarını yazın veya silin. Yayınlanmış bir sürüm dondurulmuştur, bu nedenle bir düzenleme yeni bir taslak açmak anlamına gelir. Bu yazma işlemleri grafana-agento11y-app.eval:write gerektirir.
  • Çevrimdışı deneyleri okuma: Bir test paketi üzerindeki değerlendirme çalıştırmalarını listeleyin ve birini başlık geçme oranı, maliyet ve belirteç toplamlarıyla okuyun. Test durumu başına bir rapordan denemelere, her yargıcın açıklamasıyla birlikte puanlarına ve yapıt meta verilerine inin. Yazma araçları etkinken ayrıca bir deneyi yeniden adlandırın veya yeniden etiketleyin ve çalışan bir deneyi iptal edin; bunlar grafana-agento11y-app.eval:write gerektirir. Deneyler SDK çalıştırıcıları tarafından oluşturulur, bu araç tarafından değil.

Grafana Assistant

Not: Asistan araçları varsayılan olarak devre dışıdır ve hedef Grafana örneğine Grafana Assistant eklentisinin (grafana-assistant-app) kurulmasını gerektirir. Ayrıca yazma araçlarıdır (asistan yığın durumunu değiştirebilir), bu nedenle --disable-write ayarlandığında atlanırlar. Bunları etkinleştirmek için assistant değerini --enabled-tools bayrağınıza ekleyin.

  • Asistana sorun: Grafana Assistant'a doğal dilde bir istem gönderin ve tam metin yanıtını bekleyin. Asistan, tek bir izole veri kaynağı sorgusu çalıştırmaktan daha geniş olan araçları, metrikleri, günlükleri ve diğer yığın bağlamını kullanabilir. Aynı konuşmayı sürdürmek için döndürülen contextId değerini takip eden bir çağrıda geri iletin. Karmaşık görevler birkaç dakika sürebilir; çağrı, yanıt tamamlanana veya istek zaman aşımına uğrayana (5 dakika) kadar bloke olur.

Incident'ler

  • Incident'leri arayın, oluşturun ve güncelleyin: Grafana Incident'te olayları yönetin; arama, oluşturma ve olaylara aktivite ekleme dahil.

Sift Araştırmaları

  • Sift araştırmalarını listeleyin: Bir limit parametresi desteğiyle Sift araştırmalarının listesini alın.
  • Sift araştırması alın: UUID'sine göre belirli bir Sift araştırmasının ayrıntılarını alın.
  • Sift analizlerini alın: Bir Sift araştırmasından belirli bir analizi alın.
  • Günlüklerde hata desenlerini bulun: Sift kullanarak Loki günlüklerinde yüksek hata desenlerini tespit edin.
  • Yavaş istekleri bulun: Sift (Tempo) kullanarak yavaş istekleri tespit edin.

Alerting

  • Uyarı kuralı bilgilerini listeleyin ve getirin: Grafana'da uyarı kurallarını ve durumlarını (tetikleniyor/normal/hata/vb.) görüntüleyin. Hem Grafana tarafından yönetilen kuralları hem de Prometheus veya Loki veri kaynaklarından veri kaynağı tarafından yönetilen kuralları destekler.
  • Uyarı kuralları oluşturun ve güncelleyin: Yeni uyarı kuralları oluşturun veya mevcut olanları değiştirin.
  • Uyarı kurallarını silin: UID ile uyarı kurallarını kaldırın.
  • Uyarı yönlendirmesini yönetin: Bildirim politikalarını, iletişim noktalarını ve zaman aralıklarını görüntüleyin. Hem Grafana tarafından yönetilen iletişim noktalarını hem de harici Alertmanager veri kaynaklarından (Prometheus Alertmanager, Mimir, Cortex) alıcıları destekler.

Grafana OnCall

  • Programları listeleyin ve yönetin: Grafana OnCall'da nöbet programlarını görüntüleyin ve yönetin.
  • Vardiya ayrıntılarını alın: Belirli nöbet vardiyaları hakkında ayrıntılı bilgi alın.
  • Güncel nöbetçi kullanıcıları alın: Bir program için şu anda nöbette olan kullanıcıları görün.
  • Ekipleri ve kullanıcıları listeleyin: Tüm OnCall ekiplerini ve kullanıcılarını görüntüleyin.
  • Uyarı gruplarını listeleyin: Grafana OnCall'dan uyarı gruplarını durum, entegrasyon, etiketler ve zaman aralığı dahil çeşitli ölçütlere göre görüntüleyin ve filtreleyin.
  • Uyarı grubu ayrıntılarını alın: Kimliğine göre belirli bir uyarı grubu hakkında ayrıntılı bilgi alın.

Admin

Not: Admin araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için admin değerini --enabled-tools bayrağınıza ekleyin.

  • Ekipleri listeleyin: Grafana'da yapılandırılmış tüm ekipleri görüntüleyin.
  • Kullanıcıları listeleyin: Grafana'da bir kuruluştaki tüm kullanıcıları görüntüleyin.
  • Tüm rolleri listeleyin: Tüm Grafana rollerini listeleyin; devredilebilir roller için isteğe bağlı bir filtre ile.
  • Rol ayrıntılarını alın: UID ile belirli bir Grafana rolünün ayrıntılarını alın.
  • Bir rol için atamaları listeleyin: Bir role atanmış tüm kullanıcıları, ekipleri ve hizmet hesaplarını listeleyin.
  • Kullanıcılar için rolleri listeleyin: Bir veya daha fazla kullanıcıya atanmış tüm rolleri listeleyin.
  • Ekipler için rolleri listeleyin: Bir veya daha fazla ekibe atanmış tüm rolleri listeleyin.
  • Bir kaynak için izinleri listeleyin: Belirli bir kaynak (dashboard, veri kaynağı, klasör vb.) için tanımlanmış tüm izinleri listeleyin.
  • Bir Grafana kaynağını tanımlayın: Bir kaynak türü için kullanılabilir izinleri ve atama yeteneklerini listeleyin.

Navigasyon

  • Derin bağlantılar oluşturun: LLM URL tahminine güvenmek yerine Grafana kaynakları için doğru derin bağlantı URL'leri oluşturun.
    • Dashboard bağlantıları: UID'lerini kullanarak dashboard'lara doğrudan bağlantılar oluşturun (örn. http://localhost:3000/d/dashboard-uid)
    • Panel bağlantıları: viewPanel parametresiyle dashboard'lar içindeki belirli panellere bağlantılar oluşturun (örn. http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Explore bağlantıları: Önceden yapılandırılmış veri kaynaklarıyla Grafana Explore'a bağlantılar oluşturun (örn. http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • Zaman aralığı desteği: Bağlantılara zaman aralığı parametreleri ekleyin (from=now-1h&to=now)
    • Özel parametreler: Dashboard değişkenleri veya yenileme aralıkları gibi ek sorgu parametreleri ekleyin

Açıklamalar (Annotations)

  • Açıklamaları alın: Filtrelerle açıklamaları sorgulayın. Zaman aralığını, dashboard UID'sini, etiketleri ve eşleştirme modunu destekler.
  • Açıklama oluşturun: Bir dashboard veya panel üzerinde yeni bir açıklama oluşturun.
  • Graphite açıklaması oluşturun: Graphite formatını kullanarak açıklamalar oluşturun (what, when, tags, data).
  • Açıklamayı güncelleyin: Mevcut bir açıklamanın tüm alanlarını değiştirin (tam güncelleme).
  • Açıklamayı yama yapın: Bir açıklamanın yalnızca belirli alanlarını güncelleyin (kısmi güncelleme).
  • Açıklama etiketlerini alın: İsteğe bağlı filtrelemeyle kullanılabilir açıklama etiketlerini listeleyin.

Anlık Görüntüler (Snapshots)

  • Anlık görüntüleri listeleyin: İsteğe bağlı sorgu ve limit filtreleriyle dashboard anlık görüntülerini listeleyin.
  • Anlık görüntü alın: Anlık görüntü anahtarıyla anlık görüntü meta verilerini ve dashboard yükünü alın.
  • Anlık görüntü oluşturun: İsteğe bağlı süre sonu ve harici anlık görüntü seçenekleriyle tam bir dashboard yükünden bir dashboard anlık görüntüsü oluşturun.
  • Anlık görüntüyü silin: Anlık görüntü anahtarıyla bir anlık görüntüyü silin.

İşleme (Rendering)

  • Panel veya dashboard görüntüsü alın: Bir Grafana dashboard panelini veya tam dashboard'ı PNG görüntüsü olarak işleyin. Görüntüyü raporlarda, uyarılarda veya sunumlarda kullanılmak üzere base64 kodlu veri olarak döndürür. Boyutları, zaman aralığını, temayı, ölçeği ve dashboard değişkenlerini özelleştirmeyi destekler. Ayrıca isteğe bağlı provisioningPreview parametresi aracılığıyla bir sağlama deposu dalından (örn. bir git-sync PR önizlemesi) henüz uygulanmamış dashboard'ları işlemeyi destekler.

Provisioning

  • Provisioning depolarını listeleyin: Bu Grafana örneği için yapılandırılmış provisioning depolarını (örn. git-sync kaynakları) listeleyin; her deponun slug'ını kaynak URL'si, dalı, yolu, senkronizasyon durumu ve sağlığıyla birlikte döndürür.
  • Provisioning dosyasını doğrulayın: Belirli bir dal veya commit'teki bir provisioning deposundan bir dosyayı kuru çalıştırma (dry-run) olarak uygulayın. Kabul edilip edilmeyeceğini, kaynak eylemini (oluştur/güncelle), hedef kaynak türünü ve yapılandırılmış doğrulama hatalarını döndürür — Grafana'nın PR yorumlayıcısının kullandığı kabul yüzeyinin aynısı.

Araç listesi yapılandırılabilir, böylece MCP istemcisine hangi araçları sunmak istediğinizi seçebilirsiniz. Bu, belirli işlevleri kullanmıyorsanız veya bağlam penceresinin çok fazlasını kaplamak istemiyorsanız kullanışlıdır. Bir araç kategorisini devre dışı bırakmak için sunucuyu başlatırken --disable-<category> bayrağını kullanın. Örneğin, OnCall araçlarını devre dışı bırakmak için --disable-oncall kullanın veya navigasyon derin bağlantı oluşturmayı devre dışı bırakmak için --disable-navigation kullanın.

RBAC İzinleri

Her araç düzgün çalışmak için belirli RBAC izinleri gerektirir. MCP sunucusu için bir hizmet hesabı oluştururken, hangi araçları kullanmayı planladığınıza bağlı olarak gerekli izinlere sahip olduğundan emin olun. Listelenen izinler gereken minimum eylemlerdir - kullanım durumunuza bağlı olarak uygun kapsamlara da ihtiyacınız olabilir (örn. datasources:*, dashboards:*, folders:*).

İpucu: Grafana RBAC'ye aşina değilseniz veya birçok ayrıntılı kapsam yapılandırmak yerine daha hızlı ve daha basit bir kurulum istiyorsanız, hizmet hesabına Editor gibi yerleşik bir rol atayabilirsiniz. Editor rolü, çoğu MCP sunucu işlemine izin verecek geniş okuma/yazma erişimi sağlar; manuel olarak uygulanan kapsamlardan daha az ayrıntılıdır (ve dolayısıyla daha az kısıtlayıcıdır), bu nedenle yalnızca kolaylık, sıkı en az ayrıcalık erişiminden daha önemli olduğunda kullanın.

Not: Grafana Incident ve Sift araçları, ince taneli RBAC izinleri yerine temel Grafana rollerini kullanır:

  • Görüntüleyici rolü: Salt okunur işlemler için gereklidir (olayları listeleme, araştırmaları alma)
  • Düzenleyici rolü: Yazma işlemleri için gereklidir (olay oluşturma, araştırmaları değiştirme)

Grafana RBAC hakkında daha fazla bilgi için resmi belgelere bakın.

RBAC Kapsamları

Kapsamlar, izinlerin uygulandığı belirli kaynakları tanımlar. Her eylem, hem uygun izin hem de kapsam kombinasyonunu gerektirir.

Yaygın Kapsam Desenleri:

  • Geniş erişim: Kuruluş genelinde erişim için * joker karakterlerini kullanın

    • datasources:* - Tüm veri kaynaklarına erişim
    • dashboards:* - Tüm dashboard'lara erişim
    • folders:* - Tüm klasörlere erişim
    • teams:* - Tüm ekiplere erişim

  • Sınırlı erişim: Bireysel kaynakları kısıtlamak için belirli UID'ler veya kimlikler kullanın

    • datasources:uid:prometheus-uid - Yalnızca belirli bir Prometheus veri kaynağına erişim
    • dashboards:uid:abc123 - Yalnızca UID'si abc123 olan dashboard'a erişim
    • folders:uid:xyz789 - Yalnızca UID'si xyz789 olan klasöre erişim
    • teams:id:5 - Yalnızca kimliği 5 olan ekibe erişim
    • global.users:id:123 - Yalnızca kimliği 123 olan kullanıcıya erişim

Örnekler:

  • Tam MCP sunucu erişimi: Tüm araçlar için geniş izinler verin

    datasources:* (datasources:read, datasources:query)
dashboards:* (dashboards:read, dashboards:create, dashboards:write)
folders:* (for dashboard creation and alert rules)
teams:* (teams:read)
global.users:* (users:read)

  • Sınırlı veri kaynağı erişimi: Yalnızca belirli Prometheus ve Loki örneklerini sorgulayın

    datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

  • Dashboard'a özel erişim: Yalnızca belirli dashboard'ları okuyun

    dashboards:uid:monitoring-dashboard (dashboards:read)
dashboards:uid:alerts-dashboard (dashboards:read)

Araçlar

AraçKategoriAçıklamaGerekli RBAC İzinleriGerekli Kapsamlar
list_teamsYöneticiTüm ekipleri listeleteams:readteams:* veya teams:id:1
list_users_by_orgYöneticiBir organizasyondaki tüm kullanıcıları listeleusers:readglobal.users:* veya global.users:id:123
list_all_rolesYöneticiTüm Grafana rollerini listeleroles:readroles:*
get_role_detailsYöneticiBir Grafana rolünün ayrıntılarını alroles:readroles:uid:editor
get_role_assignmentsYöneticiBir rol için atamaları listeleroles:readroles:uid:editor
list_user_rolesYöneticiKullanıcılar için rolleri listeleroles:readglobal.users:id:123
list_team_rolesYöneticiEkipler için rolleri listeleroles:readteams:id:7
get_resource_permissionsYöneticiBir kaynak için izinleri listelepermissions:readdashboards:uid:abcd1234
get_resource_descriptionYöneticiBir Grafana kaynak türünü açıklapermissions:readdashboards:*
search_dashboardsAramaPanolar için arama yapdashboards:readdashboards:* veya dashboards:uid:abc123
get_dashboard_by_uidPanoUID ile bir pano aldashboards:readdashboards:uid:abc123
update_dashboardPanoYeni bir pano güncelle veya oluşturdashboards:create, dashboards:writedashboards:*, folders:* veya folders:uid:xyz789
get_dashboard_panel_queriesPanoBir panodan panel başlığını, sorguları, veri kaynağı UID'sini ve türünü aldashboards:readdashboards:uid:abc123
run_panel_queryPanelSorgusuÇalıştır*Bir veya daha fazla pano panel sorgusu çalıştırdashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyPanoJSONPath ifadelerini kullanarak bir panonun belirli bölümlerini çıkardashboards:readdashboards:uid:abc123
get_dashboard_summaryPanoTam JSON olmadan bir panonun kompakt özetini aldashboards:readdashboards:uid:abc123
list_datasourcesVeri KaynaklarıVeri kaynaklarını listeledatasources:readdatasources:*
get_datasourceVeri KaynaklarıUID veya ada göre bir veri kaynağı aldatasources:readdatasources:uid:prometheus-uid
get_query_examplesÖrnekler*Bir veri kaynağı türü için örnek sorgular aldatasources:readdatasources:*
query_prometheusPrometheusBir Prometheus veri kaynağına karşı sorgu çalıştırdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusMetrik meta verilerini listeledatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusKullanılabilir metrik adlarını listeledatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusBir seçiciyle eşleşen etiket adlarını listeledatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusBelirli bir etiket için değerleri listeledatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusHistogram yüzdelik değerlerini hesapladatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentGrafana Incident'daki olayları listeleGörüntüleyici rolüN/A
create_incidentIncidentGrafana Incident'da bir olay oluşturEditör rolüN/A
add_activity_to_incidentIncidentGrafana Incident'da bir olaya etkinlik öğesi ekleEditör rolüN/A
get_incidentIncidentKimliğe göre tek bir olay alGörüntüleyici rolüN/A
query_loki_logsLokiLogQL kullanarak günlükleri sorgula ve al (günlük veya metrik sorguları)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiGünlüklerdeki tüm kullanılabilir etiket adlarını listeledatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiBelirli bir günlük etiketi için değerleri listeledatasources:querydatasources:uid:loki-uid
query_loki_statsLokiGünlük akışları hakkında istatistik aldatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiOrtak yapıları tanımlamak için algılanan günlük desenlerini sorguladatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiBir Loki etiket stratejisini denetle (canlı veya statik) ve isteğe bağlı olarak sorgu performansını teşhis etdatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configYapılandırmaOnaylanan etiketleri zorunlu kılan bir Alloy loki.process snippet'i oluşturN/AN/A
query_influxdbInfluxDBInfluxQL (v1) veya Flux (v2) kullanarak InfluxDB'yi sorguladatasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Bir ClickHouse veritabanındaki tabloları listeledatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Sütun türleriyle tablo şemasını aldatasources:querydatasources:uid:*
query_clickhouseClickHouse*Makro değiştirmeyle SQL sorguları çalıştırdatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Kullanılabilir AWS CloudWatch ad alanlarını listeledatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*Bir ad alanındaki metrikleri listeledatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Bir metrik için boyutları listeledatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*CloudWatch metrik sorgularını çalıştırdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Kullanılabilir Athena veri kataloglarını listeledatasources:querydatasources:uid:*
list_athena_databasesAthena*Bir Athena kataloğundaki veritabanlarını listeledatasources:querydatasources:uid:*
list_athena_tablesAthena*Bir Athena veritabanındaki tabloları listeledatasources:querydatasources:uid:*
describe_athena_tableAthena*Bir Athena tablosu için sütun adlarını aldatasources:querydatasources:uid:*
query_athenaAthena*Makro değişimi ile SQL sorgularını çalıştırdatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Lucene sözdizimi veya Query DSL kullanarak Elasticsearch veya OpenSearch sorguladatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Lucene sözdizimi veya Query DSL kullanarak Quickwit sorguladatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*INFORMATION_SCHEMA aracılığıyla bir Snowflake veritabanı/şemasındaki tabloları listeledatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Tablo şemasını al (sütun türleri, nullability, varsayılanlar, yorumlar)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Makro/değişken değişimi ile SQL sorgularını çalıştırdatasources:querydatasources:uid:*
alerting_manage_rulesAlertingUyarı kurallarını yönet (listele, al, sürümler, oluştur, güncelle, sil)alert.rules:read + alert.rules:write değişiklikler içinfolders:* veya folders:uid:alerts-folder
alerting_manage_routingAlertingBildirim politikalarını, iletişim noktalarını ve zaman aralıklarını yönetalert.notifications:readGlobal kapsam
list_oncall_schedulesOnCallGrafana OnCall'dan zaman çizelgelerini listelegrafana-oncall-app.schedules:readEklentiye özel kapsamlar
get_oncall_shiftOnCallBelirli bir OnCall vardiyası için ayrıntıları algrafana-oncall-app.schedules:readEklentiye özel kapsamlar
get_current_oncall_usersOnCallBelirli bir zaman çizelgesi için şu anda nöbette olan kullanıcıları algrafana-oncall-app.schedules:readEklentiye özel kapsamlar
list_oncall_teamsOnCallGrafana OnCall'dan ekipleri listelegrafana-oncall-app.user-settings:readEklentiye özel kapsamlar
list_oncall_usersOnCallGrafana OnCall'dan kullanıcıları listelegrafana-oncall-app.user-settings:readEklentiye özel kapsamlar
list_alert_groupsOnCallFiltreleme seçenekleriyle Grafana OnCall'dan uyarı gruplarını listelegrafana-oncall-app.alert-groups:readEklentiye özel kapsamlar
get_alert_groupOnCallKimliğine göre Grafana OnCall'dan belirli bir uyarı grubunu algrafana-oncall-app.alert-groups:readEklentiye özel kapsamlar
get_sift_investigationSiftUUID'sine göre mevcut bir Sift incelemesini alViewer rolüN/A
get_sift_analysisSiftBir Sift incelemesinden belirli bir analizi alViewer rolüN/A
list_sift_investigationsSiftİsteğe bağlı bir sınırla Sift incelemeleri listesini alViewer rolüN/A
find_error_pattern_logsSiftLoki günlüklerinde yüksek hata desenlerini bulur.Editor rolüN/A
find_slow_requestsSiftİlgili tempo veri kaynaklarından yavaş istekleri bulur.Editor rolüN/A
list_pyroscope_label_namesPyroscopeBir seçiciyle eşleşen etiket adlarını listeledatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeBir etiket adı için bir seçiciyle eşleşen etiket değerlerini listeledatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeKullanılabilir profil türlerini listeledatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopePyroscope'tan profilleri, metrikleri veya her ikisini sorguladatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsBelirli bir varlık için assertion özetini alEklentiye özel izinlerEklentiye özel kapsamlar
agento11y_manage_conversationsAgent Observability*Grafana Agent Observability'dan LLM konuşmalarını listele, ara ve getirgrafana-agento11y-app.conversations:readN/A
agento11y_manage_generationsAgent Observability*Grafana Agent Observability'dan LLM üretim ayrıntılarını ve değerlendirme puanlarını getirgrafana-agento11y-app.data:readN/A
agento11y_manage_agentsAgent Observability*Ajan kataloğunu oku: ajanları listele, bir ajan sürümünü tam olarak al, sürüm geçmişini listele ve sürüm başına puan özetlerini algrafana-agento11y-app.data:readN/A
agento11y_manage_evaluatorsAgent Observability*Değerlendiricileri, değerlendirici şablonlarını ve jüri kataloğunu yönet (listele, al, upsert, fork, test et, sil)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write değişiklikler ve testler içinN/A
agento11y_manage_eval_rulesAgent Observability*Değerlendirme kurallarını ve korumaları yönet (listele, al, oluştur, güncelle, önizle, sil)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write değişiklikler ve önizlemeler içinN/A
agento11y_manage_eval_collectionsAgent Observability*Kaydedilmiş konuşmaları ve bunları gruplayan koleksiyonları yönet (listele, al, kaydet, oluştur, güncelle, sil, üye ekle ve kaldır)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write değişiklikler içinN/A
agento11y_manage_experimentsAgent Observability*Çevrimdışı deneyleri, bunların denemelerini, puanlarını, yapıt meta verilerini ve filtre yönlerini oku; bir deneyi güncelle ve iptal etgrafana-agento11y-app.data:read + grafana-agento11y-app.eval:write değişiklikler içinN/A
agento11y_manage_test_suitesAgent Observability*Çevrimdışı deneylerin çalıştığı test paketlerini, sürümlerini ve test durumlarını yönet (listele, al, oluştur, güncelle, taslak, yayınla, upsert, sil)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write değişiklikler içinN/A
ask_assistantAssistant*Grafana Assistant'a bir istem gönder ve tam metin yanıtını döndür (contextId ile çok turlu)Eklentiye özel izinlerEklentiye özel kapsamlar
generate_deeplinkNavigationGrafana kaynakları için doğru derin bağlantı URL'leri oluşturYok (salt okunur URL oluşturma)N/A
get_annotationsAnnotationsFiltrelerle açıklamaları getirannotations:readannotations:* veya annotations:id:123
create_annotationAnotasyonlarYeni bir anotasyon oluştur (standart veya Graphite formatı)annotations:writeannotations:*
update_annotationAnotasyonlarBir anotasyonun belirli alanlarını güncelle (kısmi güncelleme)annotations:writeannotations:*
get_annotation_tagsAnotasyonlarİsteğe bağlı filtreleme ile anotasyon etiketlerini listeleannotations:readannotations:*
list_snapshotsAnlık Görüntüİsteğe bağlı sorgu ve limit filtreleriyle dashboard anlık görüntülerini listeledashboards:readdashboards:* veya dashboards:uid:abc123
get_snapshotAnlık GörüntüAnlık görüntü anahtarına göre anlık görüntü meta verilerini ve dashboard veri yükünü aldashboards:readdashboards:* veya dashboards:uid:abc123
create_snapshotAnlık GörüntüTam bir dashboard veri yükünden dashboard anlık görüntüsü oluşturdashboards:writedashboards:* veya dashboards:uid:abc123
delete_snapshotAnlık GörüntüAnlık görüntü anahtarına göre bir dashboard anlık görüntüsünü sildashboards:writedashboards:* veya dashboards:uid:abc123
get_panel_imageİşlemeDepolanmış bir dashboard veya paneli — ya da bir depo dalından sağlama önizlemesini — PNG görüntüsü olarak işledashboards:readdashboards:uid:abc123
list_provisioning_repositoriesSağlamaKaynak URL'si, dal, senkronizasyon durumu ve sağlık bilgileriyle sağlama depolarını listele (örn. git-sync kaynakları)provisioning.repositories:readN/A
validate_provisioning_fileSağlamaSağlama deposundan bir dosyayı kuru çalıştırma ile uygula ve kabul doğrulama hatalarını raporlaprovisioning.repositories:readN/A
* Varsayılan olarak devre dışı. Etkinleştirmek için --enabled-tools kategorisine ekleyin.

CLI Bayrak Referansı

mcp-grafana ikili dosyası, yapılandırma için çeşitli komut satırı bayraklarını destekler:

Taşıma (Transport) Seçenekleri:

  • -t, --transport: Taşıma türü (stdio, sse veya streamable-http) - varsayılan: stdio
  • --address: SSE/streamable-http sunucusu için ana bilgisayar ve bağlantı noktası - varsayılan: localhost:8000
  • --base-path: SSE/streamable-http sunucusu için temel yol
  • --endpoint-path: streamable-http sunucusu için uç nokta yolu - varsayılan: /mcp
  • --server-name: MCP el sıkışmasında ve OTel service.name içinde kullanılan sunucu adı - varsayılan: mcp-grafana. GRAFANA_MCP_SERVER_NAME ortam değişkenini geçersiz kılar

HTTP Taşıma Güvenliği (yalnızca SSE / streamable-http):

Host/Origin doğrulaması, dinleyicideki her rotada zorunlu tutulur — /sse, /mcp, /healthz ve /metrics — böylece DNS-rebinding yapan bir tarayıcı bunların hiçbirine ulaşamaz. Stdio taşıması etkilenmez.

  • --allowed-hosts: Host başlık değerlerinin virgülle ayrılmış beyaz listesi. Varsayılan olarak --address değerinin loopback varyantlarıdır (örn. localhost:8000,127.0.0.1:8000,[::1]:8000). Boş olarak ayrıştırılan bir değer (ayarlanmamış, ,, , vb.) de varsayılanlara geri döner; böylece bir yazım hatası kontrolü sessizce devre dışı bırakamaz. Beyaz listenin dışında bir Host başlığı taşıyan istekler 403 ile reddedilir. Kontrolü devre dışı bırakmak için * değerini geçirin — bu yalnızca Host değerini yeniden yazan güvenilir bir ters proxy arkasında veya izole bir ağda çalışırken güvenlidir. K8s httpGet probları ve harici /metrics scrape işlemleri bu listede açık bir ana bilgisayar adına, * değerine veya bir tcpSocket probuna / ayrı bir metrik bağlantı noktasına (--metrics-address) ihtiyaç duyacaktır.
  • --allowed-origins: Origin başlık değerlerinin virgülle ayrılmış beyaz listesi. Varsayılan olarak boştur — Origin başlığı taşıyan herhangi bir istek reddedilir (tarayıcılar çapraz kaynaklı istekler için her zaman bir tane gönderir ve hiçbir tarayıcı bu sunucuyu doğrudan çağırmamalıdır). Tarayıcı tabanlı istemcilere izin vermek için açık bir listeye ayarlayın veya kontrolü devre dışı bırakmak için * değerini kullanın.

Çağıran Kimlik Doğrulaması (yalnızca SSE / streamable-http):

İsteğe bağlı olarak MCP istemcilerinin sunucuya kimlik doğrulaması yapmasını gerektirir. Bu, sunucunun Grafana'ya ulaşmak için kullandığı kimlik bilgilerinden ayrıdır. Stdio etkilenmez.

  • --server-auth-token: Çağıranların Authorization: Bearer <token> olarak göndermesi gereken Bearer belirteci. MCP_GRAFANA_SERVER_TOKEN ortam değişkenine geri döner. Ayarlanmışsa, geçerli bir belirteç olmayan istekler herhangi bir araç çalışmadan önce 401 ile reddedilir. Sırrın işlem argümanlarında görünmemesi için ortam değişkenini tercih edin.

Çağıran kimlik doğrulaması yalnızca --server-auth-token ayarlandığında zorunlu tutulur. Ayarlandığında ve sunucu loopback olmayan bir adrese bağlandığında, sunucu başlar ancak bir güvenlik hatası günlüğe kaydeder — bu hata, --log-level tarafından gizlenmemesi için error günlük düzeyinde yayınlanır (loopback ve stdio etkilenmez); gelecekteki bir ana sürüm bunu bir başlangıç hatası haline getirecektir. Çağıran kimlik doğrulaması loopback olmayan bir adreste etkinleştirildiğinde TLS (veya TLS sonlandırma) kullanın. Çağıran kimlik doğrulaması etkinleştirildiğinde, doğrulanmış Authorization başlığı istekler Grafana'ya ulaşmadan önce kaldırılır; --server-auth-token ile GRAFANA_FORWARD_HEADERS=Authorization birleştirmek başlangıçta reddedilir.

Hata Ayıklama ve Günlükleme:

  • --debug: Ayrıntılı HTTP istek/yanıt günlüklemesi için hata ayıklama modunu etkinleştir
  • --log-level: Günlük düzeyi (debug, info, warn, error) - varsayılan: info

Grafana İstemci Seçenekleri:

  • --grafana-timeout: Grafana istemcisi tarafından yapılan istekler için zaman sınırı. Go süre dizelerini kabul eder (örn. 10s, 500ms) - varsayılan: 10s
  • --include-args-in-spans: OpenTelemetry span'lerine araç çağrısı argümanlarını dahil et. Yalnızca üretim dışı ortamlarda veya argümanların PII içermediği bilindiğinde etkinleştirin - varsayılan: false

Gözlemlenebilirlik:

  • --metrics: Prometheus metrik uç noktasını /metrics adresinde etkinleştir
  • --metrics-address: Metrik sunucusu için ayrı adres (örn. :9090). Boşsa, metrikler ana sunucuda sunulur
  • --slow-request-threshold: Herhangi bir MCP isteği (araç çağrısı, listeleme, kaynak okuma vb.) bu süreden uzun sürerse bir olay günlüğe kaydet. Go süre dizelerini kabul eder (örn. 500ms, 5s). Varsayılan 0 yavaş istek günlüğünü devre dışı bırakır. Yavaş istek günlüğü bölümüne bakın.
  • --slow-request-log-level: Yavaş istek olayları için günlük düzeyi (info veya warn) - varsayılan: warn.

Oturum Yönetimi:

  • --session-idle-timeout-minutes: Oturum boşta kalma zaman aşımı (dakika cinsinden). Bu süre boyunca etkinlik olmayan oturumlar otomatik olarak temizlenir - varsayılan: 30. Oturum temizlemeyi devre dışı bırakmak için 0 olarak ayarlayın. Yalnızca SSE ve streamable-http taşımaları için geçerlidir.

Araç Yapılandırması:

  • --enabled-tools: Virgülle ayrılmış etkin kategori listesi - varsayılan: admin, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery ve snowflake dışındaki tüm kategoriler. Devre dışı kategorileri etkinleştirmek için bunları listeye ekleyin (örn. "search,datasource,...,snowflake")
  • --max-loki-log-limit: query_loki_logs çağrısı başına döndürülen maksimum günlük satırı sayısı - varsayılan: 100. Not: Bunu, kesilme algılamasına izin vermek için Loki'nin sunucu tarafı max_entries_limit_per_query değerinin en az 1 altına ayarlayın (araç, daha fazla veri olup olmadığını algılamak için dahili olarak limit+1 ister).
  • --disable-search: Arama araçlarını devre dışı bırak
  • --disable-datasource: Veri kaynağı araçlarını devre dışı bırak
  • --disable-incident: Incident araçlarını devre dışı bırak
  • --disable-prometheus: Prometheus araçlarını devre dışı bırak
  • --disable-write: Yazma araçlarını devre dışı bırak (oluşturma/güncelleme işlemleri)
  • --disable-loki: Loki araçlarını devre dışı bırak
  • --disable-elasticsearch: Elasticsearch ve OpenSearch araçlarını devre dışı bırak
  • --disable-quickwit: Quickwit araçlarını devre dışı bırak
  • --disable-influxdb: InfluxDB araçlarını devre dışı bırak
  • --disable-alerting: Alerting araçlarını devre dışı bırak
  • --disable-dashboard: Dashboard araçlarını devre dışı bırak
  • --disable-oncall: OnCall araçlarını devre dışı bırak
  • --disable-asserts: Asserts araçlarını devre dışı bırak
  • --disable-sift: Sift araçlarını devre dışı bırak
  • --disable-admin: Yönetim araçlarını devre dışı bırak
  • --disable-pyroscope: Pyroscope araçlarını devre dışı bırak
  • --disable-navigation: Gezinme araçlarını devre dışı bırak
  • --disable-rendering: İşleme araçlarını devre dışı bırak (panel/dashboard görüntü dışa aktarma)
  • --disable-snapshot: Snapshot araçlarını devre dışı bırak
  • --disable-cloudwatch: CloudWatch araçlarını devre dışı bırak
  • --disable-examples: Sorgu örnekleri araçlarını devre dışı bırak
  • --disable-clickhouse: ClickHouse araçlarını devre dışı bırak
  • --disable-snowflake: Snowflake araçlarını devre dışı bırak
  • --disable-runpanelquery: Panel sorgusu çalıştırma araçlarını devre dışı bırak
  • --disable-graphite: Graphite araçlarını devre dışı bırak
  • --disable-athena: Athena araçlarını devre dışı bırak
  • --disable-provisioning: Provisioning araçlarını devre dışı bırak
  • --disable-agento11y: Agent Observability araçlarını devre dışı bırak
  • --disable-assistant: Grafana Assistant araçlarını devre dışı bırak

Salt Okunur Mod

--disable-write bayrağı, MCP sunucusunu salt okunur modda çalıştırmanın bir yolunu sağlar ve Grafana örneğinize yapılan tüm yazma işlemlerini önler. Bu, aşağıdaki gibi güvenli, salt okunur erişim sağlamak istediğiniz senaryolar için kullanışlıdır:

  • Sınırlı salt okunur izinlere sahip hizmet hesapları kullanma
  • Yapay zeka asistanlarına değişiklik yapma yeteneği olmadan gözlemlenebilirlik verileri sağlama
  • Yazma erişiminin kısıtlanması gereken üretim ortamlarında çalıştırma
  • Yanlışlıkla değişiklikleri önlemek istediğiniz test ve geliştirme senaryoları

--disable-write etkinleştirildiğinde, aşağıdaki yazma işlemleri devre dışı bırakılır:

Dashboard Araçları:

  • update_dashboard

Klasör Araçları:

  • create_folder

Incident Araçları:

  • create_incident
  • add_activity_to_incident

Alerting Araçları:

  • alerting_manage_rules (oluşturma, güncelleme, silme işlemleri)

Not (Annotation) Araçları:

  • create_annotation
  • update_annotation

Sift Araçları:

  • find_error_pattern_logs (araştırma oluşturur)
  • find_slow_requests (araştırma oluşturur)

Snapshot Araçları:

  • create_snapshot
  • delete_snapshot

Agent Observability Araçları:

  • agento11y_manage_evaluators (upsert, delete, fork, test değerlendirici işlemleri)
  • agento11y_manage_eval_rules (kural ve guard oluşturma, güncelleme, silme, önizleme işlemleri)
  • agento11y_manage_eval_collections (kayıtlı konuşmaları kaydetme ve silme; koleksiyon oluşturma, güncelleme, silme; koleksiyon üyesi ekleme ve kaldırma)
  • agento11y_manage_experiments (deney güncelleme ve iptal işlemleri)
  • agento11y_manage_test_suites (test paketleri oluşturma ve güncelleme; sürüm oluşturma ve yayımlama; test senaryoları upsert ve silme)

Tüm okuma işlemleri kullanılabilir durumda kalır; böylece panoları sorgulayabilir, PromQL/LogQL sorguları çalıştırabilir, kaynakları listeleyebilir ve veri alabilirsiniz.

İstemci TLS Yapılandırması (Grafana bağlantıları için):

  • --tls-cert-file: İstemci kimlik doğrulaması için TLS sertifika dosyasının yolu
  • --tls-key-file: İstemci kimlik doğrulaması için TLS özel anahtar dosyasının yolu
  • --tls-ca-file: Sunucu doğrulaması için TLS CA sertifika dosyasının yolu
  • --tls-skip-verify: TLS sertifika doğrulamasını atla (güvenli değil)

Sunucu TLS Yapılandırması (yalnızca streamable-http taşıması):

  • --server.tls-cert-file: Sunucu HTTPS için TLS sertifika dosyasının yolu
  • --server.tls-key-file: Sunucu HTTPS için TLS özel anahtar dosyasının yolu

Kullanım

Bu MCP sunucusu hem yerel Grafana örnekleriyle hem de Grafana Cloud ile çalışır. Grafana Cloud için, aşağıdaki yapılandırma örneklerinde http://localhost:3000 yerine örnek URL'nizi (örn. https://myinstance.grafana.net) kullanın.

  1. Hizmet hesabı belirteci kimlik doğrulaması kullanıyorsanız, Grafana'da kullanmak istediğiniz araçları kullanmak için yeterli izinlere sahip bir hizmet hesabı oluşturun, bir hizmet hesabı belirteci oluşturun ve yapılandırma dosyasında kullanmak üzere panoya kopyalayın. Hizmet hesabı belirteçleri oluşturma hakkında ayrıntılı bilgi için Grafana hizmet hesabı belgelerine bakın. İpucu: İnce taneli RBAC kapsamları yapılandırma konusunda rahat değilseniz, daha basit (ancak daha az kısıtlayıcı) bir seçenek, hizmet hesabına yerleşik Editor rolünü atamaktır. Bu, çoğu MCP sunucusu işlemini kapsayan geniş okuma/yazma erişimi sağlar — kolaylık, kesin en az ayrıcalık gereksinimlerinden daha ağır bastığında kullanın.

    Not: GRAFANA_API_KEY ortam değişkeni kullanımdan kaldırılmıştır ve gelecekteki bir sürümde kaldırılacaktır. Lütfen bunun yerine GRAFANA_SERVICE_ACCOUNT_TOKEN kullanmaya geçiş yapın. Eski değişken adı geriye dönük uyumluluk için çalışmaya devam edecek ancak kullanımdan kaldırma uyarıları gösterecektir.

Hizmet hesabı belirtecini bir dosyadan okuma

Belirteci GRAFANA_SERVICE_ACCOUNT_TOKEN ile satır içi olarak iletmek yerine, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE değerini belirteci içeren bir dosya yoluna yönlendirebilirsiniz. Dosya her istekte yeniden okunur; böylece döndürülen belirteçler, sunucuyu yeniden başlatmadan otomatik olarak alınır.

Bu özellikle Kubernetes'te kullanışlıdır; burada bir Secret birime bağlanmışsa, temel Secret değiştiğinde yerinde güncellenir (genellikle ~1 dakika içinde). Belirteç değerine göre anahtarlanan istek başına istemci önbelleğiyle birleştirildiğinde, döndürülen bir belirteç, pod yeniden başlatması ve kesinti olmadan şeffaf bir şekilde yeni bir istemci üretir:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

Dosya içeriğinden çevreleyen boşluk (sondaki yeni satır dahil) kırpılır. Hem GRAFANA_SERVICE_ACCOUNT_TOKEN hem de GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ayarlanmışsa, satır içi belirteç önceliklidir.

Çoklu Organizasyon Desteği

Aşağıdakilerden birini kullanarak hangi organizasyonla etkileşim kuracağınızı belirtebilirsiniz:

  • Ortam değişkeni: Sayısal organizasyon kimliği için GRAFANA_ORG_ID değerini ayarlayın
  • HTTP başlığı: SSE veya streamable HTTP taşımaları kullanırken X-Grafana-Org-Id değerini ayarlayın (başlık, ortam değişkenine göre önceliklidir - yani bir varsayılan organizasyon da ayarlayabilirsiniz).

Bir organizasyon kimliği sağlandığında, MCP sunucusu Grafana'ya yapılan tüm isteklerde X-Grafana-Org-Id başlığını ayarlar ve işlemlerin belirtilen organizasyon bağlamında gerçekleştirilmesini sağlar.

Organizasyon kimliği ile örnek:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Özel HTTP Başlıkları

Tüm Grafana API isteklerine GRAFANA_EXTRA_HEADERS ortam değişkenini kullanarak isteğe bağlı HTTP başlıkları ekleyebilirsiniz. Değer, başlık adlarını değerlere eşleyen bir JSON nesnesi olmalıdır.

Özel başlıklarla örnek:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

İstemciden Başlık İletme (Yalnızca SSE/Streamable-HTTP)

MCP sunucusu SSO'yu yöneten bir ağ geçidi veya ters proxy arkasında çalıştığında (ör. OIDC ile bir AWS ALB), her kullanıcının oturum çerezinin Grafana'ya ulaşması gerekir, böylece isteği kimliği doğrulanmış kullanıcıyla ilişkilendirebilir. GRAFANA_FORWARD_HEADERS ortam değişkeni, gelen HTTP isteğinden her giden Grafana API isteğine kopyalanacak başlık adlarının virgülle ayrılmış bir beyaz listesini belirterek bunu sağlar.

Bu yalnızca SSE (-t sse) veya streamable-http (-t streamable-http) taşımaları kullanılırken geçerlidir. stdio modunda hiçbir etkisi yoktur.

Örnek: oturum çerezi iletme

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

Birden fazla başlığı virgülle ayırarak iletebilirsiniz:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

İletilen başlıklar, GRAFANA_EXTRA_HEADERS içinde tanımlanan başlıklarla birleştirilir. Bir başlık adı her ikisinde de görünürse, o istek için gelen istekteki değer önceliklidir.

  1. mcp-grafana kurmak için birkaç seçeneğiniz vardır:

    • uvx (önerilen): uv kuruluysa, ek kurulum gerekmez — uvx sunucuyu otomatik olarak indirip çalıştırır:

      uvx mcp-grafana

    • Docker imajı: Docker Hub'dan önceden oluşturulmuş Docker imajını kullanın.

      Önemli: Docker imajının giriş noktası, MCP sunucusunu varsayılan olarak SSE modunda çalıştıracak şekilde yapılandırılmıştır, ancak çoğu kullanıcı Claude Desktop gibi AI asistanlarıyla doğrudan entegrasyon için STDIO modunu kullanmak isteyecektir:

      1. STDIO Modu: stdio modu için varsayılanı -t stdio ile açıkça geçersiz kılmalı ve stdin'i açık tutmak için -i bayrağını eklemelisiniz:
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio

      Not — ağ modlarını güvenli hale getirin: SSE ve streamable-http modlarında kapsayıcı, döngü dışı bir adrese (0.0.0.0:8000) bağlanır. Arayan belirteci olmadan sunucu başlar ancak bir güvenlik hatası günlüğe kaydeder (error günlük düzeyinde, bu nedenle --log-level tarafından gizlenmez; ve gelecekteki bir ana sürümde başlamayı reddedecektir). İstemcilerden bir Authorization: Bearer <token> gerektirmek için MCP_GRAFANA_SERVER_TOKEN ayarlayın (önerilir). STDIO modu etkilenmez. Bkz. Arayan Kimlik Doğrulaması.

      1. SSE Modu: Bu modda sunucu, istemcilerin bağlandığı bir HTTP sunucusu olarak çalışır. -p bayrağını kullanarak 8000 numaralı bağlantı noktasını açmalısınız:
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. Streamable HTTP Modu: Bu modda sunucu, birden çok istemci bağlantısını işleyebilen bağımsız bir süreç olarak çalışır. -p bayrağını kullanarak 8000 numaralı bağlantı noktasını açmalısınız: Bu mod için varsayılanı -t streamable-http ile açıkça geçersiz kılmalısınız
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http

      Sunucu TLS sertifikalarıyla HTTPS streamable HTTP modu için:

      docker pull grafana/mcp-grafana
docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • İkili dosyayı indirin: mcp-grafana sürümünün en son sürümünü sürümler sayfasından indirin ve $PATH içine yerleştirin.

    • Kaynaktan derleyin: Go araç zinciri kuruluysa, ikili dosyanın kurulacağı dizini belirtmek için GOBIN ortam değişkenini kullanarak kaynaktan da derleyip kurabilirsiniz. Bu da $PATH içinde olmalıdır.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

    • Helm kullanarak Kubernetes'e dağıtın: Grafana helm-charts deposundaki Helm grafiğini kullanın

      helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

  2. Sunucu yapılandırmasını istemci yapılandırma dosyanıza ekleyin. Örneğin, Claude Desktop için:

    uvx kullanılıyorsa:

    {
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

    İkili dosya kullanılıyorsa:

    {
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Not: Claude Desktop'ta Error: spawn mcp-grafana ENOENT görürseniz, mcp-grafana tam yolunu belirtmeniz gerekir.

Docker kullanılıyorsa:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Not: -t stdio bağımsız değişkeni burada önemlidir çünkü Docker imajındaki varsayılan SSE modunu geçersiz kılar.

Uzak MCP sunucusuyla VSCode kullanma

VSCode kullanıyorsanız ve MCP sunucusunu SSE modunda çalıştırıyorsanız (taşımayı geçersiz kılmadan Docker imajını kullanırken varsayılan budur), .vscode/settings.json aşağıdakileri içerdiğinden emin olun:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Sunucu TLS sertifikalarıyla HTTPS streamable HTTP modu için:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

Hata Ayıklama Modu

Komuta -debug bayrağını ekleyerek Grafana taşıması için hata ayıklama modunu etkinleştirebilirsiniz. Bu, MCP sunucusu ile Grafana API arasındaki HTTP isteklerinin ve yanıtlarının ayrıntılı günlüğünü sağlar ve sorun gidermede yardımcı olabilir.

Claude Desktop yapılandırmasıyla hata ayıklama modunu kullanmak için yapılandırmanızı şu şekilde güncelleyin:

İkili dosya kullanılıyorsa:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Docker kullanılıyorsa:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Not: Standart yapılandırmada olduğu gibi, Docker imajındaki varsayılan SSE modunu geçersiz kılmak için -t stdio bağımsız değişkeni gereklidir.

TLS Yapılandırması

Grafana örneğiniz mTLS arkasındaysa veya özel TLS sertifikaları gerektiriyorsa, MCP sunucusunu özel sertifikalar kullanacak şekilde yapılandırabilirsiniz. Sunucu aşağıdaki TLS yapılandırma seçeneklerini destekler:

  • --tls-cert-file: İstemci kimlik doğrulaması için TLS sertifika dosyasının yolu
  • --tls-key-file: İstemci kimlik doğrulaması için TLS özel anahtar dosyasının yolu
  • --tls-ca-file: Sunucu doğrulaması için TLS CA sertifika dosyasının yolu
  • --tls-skip-verify: TLS sertifika doğrulamasını atla (güvenli değil, yalnızca test için kullanın)

İstemci sertifikası kimlik doğrulamasıyla örnek:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Docker ile örnek:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

TLS yapılandırması, MCP sunucusu tarafından kullanılan tüm HTTP istemcilerine uygulanır, bunlar şunları içerir:

  • Ana Grafana OpenAPI istemcisi
  • Prometheus veri kaynağı istemcileri
  • Loki veri kaynağı istemcileri
  • Olay yönetimi istemcileri
  • Sift araştırma istemcileri
  • Uyarı istemcileri
  • Asserts istemcileri

Doğrudan CLI Kullanım Örnekleri:

Kendinden imzalı sertifikalarla test etmek için:

./mcp-grafana --tls-skip-verify -debug

İstemci sertifikası kimlik doğrulamasıyla:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

Yalnızca özel CA sertifikasıyla:

./mcp-grafana --tls-ca-file /path/to/ca.crt

Programatik Kullanım:

Bu kitaplığı programatik olarak kullanıyorsanız, TLS etkin bağlam işlevleri de oluşturabilirsiniz:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

URL doğrulama:

NewGrafanaClient doğrudan çağrılırken (stdio veya programatik yapılandırma), ulaşılabilir bir panikten kaçınmak için URL'leri önceden doğrulayın:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Sunucu TLS Yapılandırması (Yalnızca Streamable HTTP Taşıması)

Streamable HTTP taşımasını (-t streamable-http) kullanırken, MCP sunucusunu HTTP yerine HTTPS sunacak şekilde yapılandırabilirsiniz. Bu, MCP istemciniz ile sunucunun kendisi arasındaki bağlantıyı güvence altına almanız gerektiğinde kullanışlıdır.

Sunucu, streamable HTTP taşıması için aşağıdaki TLS yapılandırma seçeneklerini destekler:

  • --server.tls-cert-file: Sunucu HTTPS için TLS sertifika dosyasının yolu (TLS için gereklidir)
  • --server.tls-key-file: Sunucu HTTPS için TLS özel anahtar dosyasının yolu (TLS için gereklidir)

Not: Bu bayraklar, yukarıda belgelenen istemci TLS bayraklarından tamamen ayrıdır. İstemci TLS bayrakları, MCP sunucusunun Grafana'ya nasıl bağlandığını yapılandırırken, bu sunucu TLS bayrakları, streamable HTTP taşıması kullanılırken istemcilerin MCP sunucusuna nasıl bağlandığını yapılandırır.

HTTPS streamable HTTP sunucusuyla örnek:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

Bu, MCP sunucusunu HTTPS 8443 bağlantı noktasında başlatır. İstemciler daha sonra http://localhost:8000/ yerine https://localhost:8443/ bağlanır.

Sunucu TLS ile Docker örneği:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Sağlık Kontrolü Uç Noktası

SSE (-t sse) veya streamable HTTP (-t streamable-http) taşımalarını kullanırken, MCP sunucusu /healthz adresinde bir sağlık kontrolü uç noktası sunar. Bu uç nokta, yük dengeleyiciler, izleme sistemleri veya orkestrasyon platformları tarafından sunucunun çalıştığını ve bağlantıları kabul ettiğini doğrulamak için kullanılabilir.

Uç Nokta: GET /healthz

Yanıt:

  • Durum Kodu: 200 OK
  • Gövde: ok

Örnek kullanım:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# With custom address
curl http://localhost:9090/healthz

Not: Sağlık kontrolü uç noktası yalnızca SSE veya streamable HTTP taşımaları kullanılırken kullanılabilir. stdio taşıması (-t stdio) kullanılırken kullanılamaz, çünkü stdio bir HTTP sunucusu açığa çıkarmaz.

Gözlemlenebilirlik

MCP sunucusu, OTel MCP anlamsal kurallarını izleyerek Prometheus metriklerini, OpenTelemetry dağıtılmış izlemeyi ve OpenTelemetry günlük dışa aktarımını destekler. İzleme ve günlük dışa aktarımı, standart OTEL_* ortam değişkenleri aracılığıyla yapılandırılır ve herhangi bir taşımayla çalışır.

Not: mcp-grafana şu anda hem izlemeler hem de günlükler için yalnızca OTLP/gRPC taşımasını destekler. OTEL_EXPORTER_OTLP_PROTOCOL (ve _TRACES_PROTOCOL / _LOGS_PROTOCOL varyantları) dikkate alınmaz — gRPC her durumda kullanılır.

Metrikler

SSE veya streamable HTTP taşımalarını kullanırken, --metrics bayrağıyla Prometheus metriklerini etkinleştirin:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Kullanılabilir Metrikler:

MetrikTürAçıklama
mcp_server_operation_duration_secondsHistogramMCP işlemlerinin süresi (etiketler: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramMCP istemci oturumlarının süresi (etiketler: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramHTTP sunucu isteklerinin süresi (otelhttp'tan)

Not: Metrikler yalnızca SSE veya streamable HTTP taşımaları kullanılırken kullanılabilir. stdio taşımasıyla kullanılamazlar.

Yavaş istek günlüğü

--slow-request-threshold bayrağı, bir MCP isteği (araç çağrısı, liste, kaynak okuma vb.) belirtilen süreyi aştığında yapılandırılmış bir günlük olayı yayar. Tam hata ayıklama günlüğünde boğulmadan yavaş sorguları ve araç çağrılarını teşhis etmek için kullanışlıdır.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

Günlük olayı şu yapılandırılmış öznitelikleri taşır:

ÖznitelikAçıklama
mcp.methodMCP yöntemi (ör. tools/call, tools/list, resources/read)
durationGözlemlenen istek süresi
thresholdYapılandırılmış eşik
toolAraç adı (yalnızca tools/call yöntemleri için mevcuttur)
errorİstek başarısız olduğunda hata değeri (en iyi çaba bağlamı; içerik üst akış hata sarmalayıcı tarafından kontrol edilir)
error.typeSınırlı kardinalite hata sınıflandırması (türsüz hatalar için _OTHER)

Yavaş istek günlüğü tüm taşımalarda (stdio dahil) çalışır ve --metrics gerektirmez. 0 varsayılan eşiği onu tamamen devre dışı bırakır. Proxy'li araçlar tools/call üzerinden akar ve otomatik olarak kapsanır.

İzleme

Dağıtılmış izleme, standart OTEL_* ortam değişkenleri aracılığıyla yapılandırılır ve --metrics bayrağından bağımsız çalışır. OTEL_EXPORTER_OTLP_ENDPOINT (veya sinyale özgü OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) ayarlandığında, sunucu izlemeleri OTLP/gRPC üzerinden dışa aktarır:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Araç çağrısı yayılmaları semconv adlandırmasını (tools/call <tool_name>) izler ve gen_ai.tool.name, mcp.method.name ve mcp.session.id gibi öznitelikler içerir. Sunucu ayrıca araç çağrısı isteklerinin _meta alanından W3C izleme bağlamı yayılımını destekler.

Günlükler

OTEL_EXPORTER_OTLP_ENDPOINT (veya sinyale özgü OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) ayarlandığında, sunucu mevcut düz metin stderr çıktısına ek olarak yapılandırılmış günlükleri de OTLP/gRPC üzerinden dışa aktarır. otelslog köprüsü, etkin yayılımdan trace_id ve span_id otomatik olarak ekler, böylece günlük kayıtları sunucunun zaten yaydığı izlemelerle ilişkilendirilir.

İzlemeler ve günlükler uç noktalarını bağımsız olarak çözer, böylece iki sinyal ayrı ayrı etkinleştirilebilir: yalnızca OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ayarlamak günlük dışa aktarımı olmadan izlemeyi etkinleştirir, yalnızca OTEL_EXPORTER_OTLP_LOGS_ENDPOINT ayarlamak izleme olmadan günlük dışa aktarımını etkinleştirir ve genel OTEL_EXPORTER_OTLP_ENDPOINT her ikisini de etkinleştirir.

Genel OTEL_EXPORTER_OTLP_ENDPOINT kullanıyorsanız ancak günlük dışa aktarımını devre dışı bırakmak istiyorsanız (ör. arka uç LogsService desteklemiyorsa), şunu ayarlayın:

OTEL_LOGS_EXPORTER=none

Bu, sunucunun uç nokta yapılandırmasından bağımsız olarak bir OTLP günlük dışa aktarıcısı oluşturmasını engeller ve unknown service opentelemetry.proto.collector.logs.v1.LogsService gibi hataların önüne geçer.

OTLP günlüğü etkinleştirildiğinde stderr günlüğü değişmez; isterseniz konteyner günlüklerine güvenmeye devam edebilir veya stderr'i /dev/null'e yönlendirebilirsiniz.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

Taşıma protokolü OTLP/gRPC'dir (varsayılan port 4317). Günlükler, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (veya genel OTEL_EXPORTER_OTLP_ENDPOINT) uzak gRPC uç noktasına yönlendirilerek ve OTEL_EXPORTER_OTLP_LOGS_HEADERS (veya OTEL_EXPORTER_OTLP_HEADERS) aracılığıyla kimlik doğrulaması sağlanarak, OTLP/gRPC kabul eden herhangi bir yönetilen arka uca — örneğin Grafana Cloud — doğrudan gönderilebilir; bu, yukarıdaki izleme örneğini yansıtır. Yerel bir OTel toplayıcı isteğe bağlıdır — fan-out, toplu işleme veya çoklu arka uç yönlendirme için yararlıdır, ancak zorunlu değildir.

Sinyale özgü varyantlar OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT ve OTEL_EXPORTER_OTLP_LOGS_COMPRESSION dikkate alınır ve genel OTEL_EXPORTER_OTLP_* karşılıklarını geçersiz kılar — tam liste ve öncelik kuralları için OTel dışa aktarıcı spesifikasyonuna bakın.

Yapılandırılan toplayıcıya ulaşılamazsa, günlük kayıtları bellekte arabelleğe alınır (varsayılan kuyruk: 2048) ve kuyruk dolduğunda en eski kayıtlar atılır. Süreç, hizmeti engellemeden devam eder. Kesintiler sırasında kayıpsız arabelleğe alma gerekiyorsa yerel bir OTel toplayıcı yapılandırın.

Günlükler ayrıca stdio taşıma protokolü altında dışa aktarılır; bu, IDE istemcileri tarafından çağrılan yerel mcp-grafana örneklerinden günlükleri merkezileştirmeyi kolaylaştırır.

Metrikler, izleme ve günlükler içeren Docker örneği:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Sorun Giderme

Grafana Sürüm Uyumluluğu

Veri kaynağıyla ilgili araçları kullanırken aşağıdaki hatayla karşılaşırsanız:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

Bu genellikle Grafana'nın 9.0'dan önceki bir sürümünü kullandığınızı gösterir. /datasources/uid/{uid} API uç noktası Grafana 9.0'da tanıtılmıştır ve veri kaynağı işlemleri daha eski sürümlerde başarısız olur.

Çözüm: Bu sorunu çözmek için Grafana örneğinizi 9.0 veya sonraki bir sürüme yükseltin.

Geliştirme

Katkılar memnuniyetle karşılanır! Önerileriniz veya iyileştirmeleriniz varsa lütfen bir sorun (issue) açın veya bir çekme isteği (pull request) gönderin.

Bu proje Go dilinde yazılmıştır. Platformunuz için talimatları izleyerek Go'yu kurun.

Sunucuyu yerel olarak STDIO modunda (yerel geliştirme için varsayılan) çalıştırmak için şunu kullanın:

make run

Sunucuyu yerel olarak SSE modunda çalıştırmak için şunu kullanın:

go run ./cmd/mcp-grafana --transport sse

Sunucuyu özel olarak oluşturulmuş bir Docker imajı içinde SSE taşıma protokolünü kullanarak da çalıştırabilirsiniz. Yayınlanan Docker imajı gibi, bu özel imajın giriş noktası da varsayılan olarak SSE modundadır. İmajı oluşturmak için şunu kullanın:

make build-image

Ve imajı SSE modunda (varsayılan) çalıştırmak için şunu kullanın:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Bunun yerine STDIO modunda çalıştırmanız gerekiyorsa, taşıma protokolü ayarını geçersiz kılın:

docker run -it --rm mcp-grafana:latest -t stdio

Test Etme

Üç tür test mevcuttur:

  1. Birim Testleri (harici bağımlılık gerektirmez):
make test-unit

Birim testlerini şununla da çalıştırabilirsiniz:

make test
  1. Entegrasyon Testleri (docker konteynerlerinin çalışır durumda olmasını gerektirir):
make test-integration
  1. Bulut Testleri (bulut Grafana örneği ve kimlik bilgileri gerektirir):
make test-cloud

Not: Bulut testleri CI'da otomatik olarak yapılandırılır. Yerel geliştirme için kendi Grafana Cloud örneğinizi ve kimlik bilgilerinizi ayarlamanız gerekir.

Daha kapsamlı entegrasyon testleri, Grafana örneğinin yerel olarak 3000 portunda çalışmasını gerektirir; Docker Compose ile bir tane başlatabilirsiniz:

docker-compose up -d

Entegrasyon testleri şununla çalıştırılabilir:

make test-all

Daha fazla araç ekliyorsanız, lütfen onlar için entegrasyon testleri ekleyin. Mevcut testler iyi bir başlangıç noktası olmalıdır.

Lint (Kod Denetimi)

Kodu lint etmek için şunu çalıştırın:

make lint

Bu, jsonschema yapı etiketlerinde kaçış karakteri olmayan virgülleri kontrol eden özel bir linter içerir. description alanlarındaki virgüller, sessiz kesilmeyi önlemek için \\, ile kaçış karakteriyle yazılmalıdır. Yalnızca bu linter'i şununla çalıştırabilirsiniz:

make lint-jsonschema

Daha fazla ayrıntı için JSONSchema Linter belgelerine bakın.

Lisans

Bu proje Apache Lisansı, Sürüm 2.0 altında lisanslanmıştır.