Grafana

resmi

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

GitHub

3.5k

Bu MCP'yi deneyinSponsorlu

Grafana MCP ile neler yapabilirsiniz?

Panoları arayın ve inceleyin — Panoları başlık, klasör, etiket veya yıldızlı duruma göre isteyin, ardından search_dashboards, get_dashboard_summary veya get_dashboard_property ile özetleri, sürümleri veya $.title gibi belirli JSONPath özelliklerini çekin.
Prometheus ve Loki sorgulayın — PromQL veya LogQL sorguları çalıştırın, metrik/etiket meta verilerini alın ve histogram yüzdeliklerini (p50–p99) doğrudan veri kaynaklarınızdan hesaplayın.
Uyarıları ve olayları yönetin — Uyarı kurallarını listeleyin veya oluşturun, tetiklenme durumlarını kontrol edin ve özel alanlarla Grafana Incident kayıtlarını arayın veya güncelleyin.
SQL ve CloudWatch verilerini keşfedin — ClickHouse, Snowflake, Athena, MySQL, PostgreSQL veya MSSQL üzerinde tabloları listeleyin, şemaları tanımlayın ve makrolarla SQL çalıştırın; ayrıca CloudWatch metriklerini ad alanı ve boyuta göre sorgulayın.
Panoları işleyin ve bağlantılar oluşturun — Bir paneli veya panoyu PNG görüntüsü olarak alın veya zaman aralıkları ve değişkenlerle panolara, panellere ve Explore'a doğru derin bağlantılar oluşturun.

Dokümantasyon

Grafana MCP sunucusu

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. MCP istemci yapılandırmanıza (örn. Claude Desktop, Cursor) aşağıdakini 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, klasör UID'sine, etikete veya yıldızlı duruma göre bulun
UID ile pano alma: Benzersiz tanımlayıcısını kullanarak pano ayrıntılarının tamamını alın. Geçerli pano yerine kayıtlı bir anlık görüntü yüklemek için isteğe bağlı version değerini iletin. Uyarı: Büyük panolar önemli miktarda bağlam penceresi alanı tüketebilir.
Pano sürümlerini listele: Bir panonun kayıtlı sürümlerini kompakt meta veriler olarak listeleyin (sürüm numarası, yazar, zaman damgası, kaydetme mesajı)
Pano özeti al: Bağlam penceresi kullanımını en aza indirmek için tam JSON olmadan başlık, panel sayısı, panel türleri, değişkenler ve meta veriler dahil bir panonun kompakt özetini alın
Pano özelliği al: Yalnızca gerekli verileri getirmek 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üncelle veya oluştur: Mevcut panoları değiştirin veya yenilerini oluşturun. Uyarı: Büyük miktarda bağlam penceresi alanı tüketebilecek tam pano JSON'u gerektirir.
Panoyu yama: Tam JSON gerektirmeden bir panoya belirli değişiklikler uygulayı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 al: Bir panodaki her panelden başlığı, sorgu dizesini ve veri kaynağı bilgilerini (varsa UID ve tür dahil) alın

Panel Sorgusu Çalıştır

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

Panel sorgusu çalıştır: Ö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çeriyor (sorun #101):

Pano özeti ve değişiklik planlaması için get_dashboard_summary kullanın
Yalnızca belirli pano bölümlerine ihtiyacınız olduğunda JSONPath ile get_dashboard_property kullanın
Tam pano JSON'una özellikle ihtiyacınız olmadıkça get_dashboard_by_uid kullanmaktan kaçının

Veri Kaynakları

Veri kaynağı bilgilerini listele ve getir: 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 örneği araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için --enabled-tools bayrağınıza examples ekleyin.

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

Prometheus Sorgulama

Prometheus sorgula: 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 sorgula: Prometheus veri kaynaklarından metrik meta verilerini, metrik adlarını, etiket adlarını ve etiket değerlerini alın.
Histogram yüzdeliklerini sorgula: histogram_quantile kullanarak histogram yüzdelik değerlerini (p50, p90, p95, p99) hesaplayın.

Loki Sorgulama

Loki günlüklerini ve metriklerini sorgula: 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 sorgula: Loki veri kaynaklarından etiket adlarını, etiket değerlerini ve akış istatistiklerini alın.
Loki desenlerini sorgula: 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 --enabled-tools bayrağınıza influxdb ekleyin.

InfluxDB sorgula: 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.

SQL Veri Kaynağı Sorgulama

Not: SQL araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için --enabled-tools bayrağınıza sql ekleyin. Geriye dönük uyumlu takma adlar clickhouse, snowflake ve athena de çalışır.

Birleşik SQL araçları, tek bir araç seti aracılığıyla ClickHouse, Snowflake, Athena, MySQL, PostgreSQL ve MSSQL destekler. Sorgular Grafana'nın veri kaynağı eklentilerinden geçer, bu nedenle kimlik doğrulama veri kaynağı yapılandırması tarafından yönetilir — kimlik bilgileri MCP sunucusu tarafından asla görülmez.

Veritabanlarını/şemaları/katalogları listele: Bir SQL veri kaynağı için organizasyonel birimleri keşfedin. Athena için, katalogları listelemek üzere kataloğu atlayın veya veritabanlarını listelemek için bir katalog iletin.
Tabloları listele: Bir veritabanındaki veya şemadaki tabloları meta verilerle (satır sayıları, varsa boyutlar) listeleyin.
Tablo şemasını tanımla: Sütun adlarını, türlerini, boş değer kabul edilebilirliğini, varsayılanları ve yorumları alın.
SQL sorgula: Veri kaynağına özel makro ikamesi ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), otomatik limit uygulaması ve şablon değişkeni 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 --enabled-tools bayrağınıza cloudwatch ekleyin.

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

Google Cloud Logging Sorgulama

Not: Google Cloud Logging araçları varsayılan olarak devre dışıdır. Bunları etkinleştirmek için --enabled-tools bayrağınıza cloudlogging ekleyin. Grafana 11.2+ gerektiren Google Cloud Logging veri kaynağı eklentisini (googlecloud-logging-datasource) sürüm 1.8.0 veya üzerini gerektirir. Daha eski eklenti sürümleri farklı bir yanıt düzeni döndürür ve query_cloud_logging yükseltme isteyen bir hata bildirir.

Cloud Logging projelerini listele: Veri kaynağının günlükleri okuyabileceği GCP proje kimliklerini keşfedin.
Cloud Logging paketlerini ve görünümlerini listele: Bir sorguyu kapsamlamak için günlük paketlerini ve günlük görünümlerini keşfedin.
Cloud Logging sorgula: Zaman aralığı ve limit ile Cloud Logging sorgu dili filtrelerini (örn. resource.type="k8s_container" AND severity>=ERROR) çalıştırın; girişleri önem düzeyi, gövde, etiketler ve izleme kimliğiyle en yeniden en eskiye döndürür. GCP kimlik doğrulaması veri kaynağı yapılandırması tarafından yönetilir.

Graphite Sorgulama

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

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

Elasticsearch/OpenSearch Sorgulama

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

Elasticsearch/OpenSearch sorgula: 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. Belgeleri dizin, kimlik, kaynak alanları ve isteğe bağlı alaka puanıyla döndürür.

Quickwit Sorgulama

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

Quickwit sorgula: 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. Belgeleri dizin, kimlik, kaynak alanları ve isteğe bağlı alaka puanıyla 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 --enabled-tools bayrağınıza agento11y ekleyin.

Sohbetleri listele ve ara: Son LLM sohbetlerini listeleyin veya bir zaman aralığında filtre ifadesiyle (model, sağlayıcı, aracı, durum, hata türü, değerlendirme sonuçları ve daha fazlası) arayın. Arama sonuçları hata sayıları, puan özetleri, değerlendirme özetleri ve izleme kimliklerini içerir.
Sohbet ayrıntısını al: Tüm üretimleri (istemler ve çıktılar dahil) içeren tek bir sohbeti getirin.
Üretim ayrıntısını ve puanlarını al: Kimliğe göre tek bir üretimi ve değerlendirme puanlarını (değerlendirici, puan anahtarı, değer, geçti, açıklama) getirin.
Aracı kataloğunu oku: Telemetri gönderen aracıları listeleyin, bir aracı sürümünü tam olarak getirin (tam sistem istemi, JSON şemasıyla birlikte her araç ve üzerinde çalıştığı modeller), bir aracının sürüm geçmişini inceleyin ve sürüm başına değerlendirme puanı ortalamalarını karşılaştırın. Etkin sürümler, bir araç değişikliğinin asla etkilemediği sha256: karmalarıdır; kendi sürümünü bildirmeyen bir aracı 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ı incele: Bir puanın geldiği değerlendiricileri, bunların türetildiği şablonları ve LLM yargıcı değerlendiricileri için kullanılabilen yargıç sağlayıcılarını ve modellerini okuyun. Yazma araçları etkinleştirilmişse, değerlendiricileri de oluşturun, çatallayın, test edin ve silin.
Değerlendirme kurallarını ve korumalarını incele: Değerlendiricileri üretim trafiğine bağlayan zaman uyumsuz değerlendirme kurallarını ve satır içi çalışan ve uyarabilen veya reddedebilen korumaları (kanca kuralları) okuyun. Yazma araçları etkinleştirilmişse, bunları da oluşturun, güncelleyin, önizleyin ve silin. Yazmalar 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.
Kayıtlı sohbetleri ve koleksiyonları düzenle: Kayıtlı sohbetleri (bir sohbete sabit bir kimlik, ad ve etiket veren yer imleri) ve bunları gruplayan koleksiyonları, her koleksiyonun üye sayısı ve her kayıtlı sohbet satırına gömülü koleksiyonlar dahil olmak üzere okuyun. Yazma araçları etkinleştirilmişse, bir sohbeti yer imlerine ekleyin, koleksiyonlar oluşturun ve düzenleyin ve üye ekleyin veya kaldırın. Bu yazmalar aynı grafana-agento11y-app.eval:write iznini gerektirir.
Test paketlerini oku ve düzenle: Çevrimdışı deneylerin üzerinde çalıştığı sürümlü test paketlerini listeleyin, tam sürüm geçmişiyle birini okuyun ve bir sürümün test senaryolarında sayfalayın. Yazma araçları etkinleştirilmişse, bir paket oluşturun, yeniden adlandırın veya yeniden etiketleyin, bir taslak sürüm açın, yayınlayın ve test senaryolarını yazın veya silin. Yayınlanmış bir sürüm dondurulur, bu nedenle bir düzenleme yeni bir taslak açmak anlamına gelir. Bu yazmalar grafana-agento11y-app.eval:write gerektirir.
Çevrimdışı deneyleri oku: 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 senaryosu başına rapordan denemelere, her yargıcın açıklamasıyla puanlarına ve yapıt meta verilerine inin. Yazma araçları etkinleştirilmişse, bir deneyi yeniden adlandırın veya yeniden etiketleyin ve çalışan birini 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 Asistanı

Not: Asistan araçları varsayılan olarak devre dışıdır ve hedef Grafana örneğine Grafana Asistanı eklentisinin (grafana-assistant-app) yüklenmesini 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 --enabled-tools bayrağınıza assistant ekleyin.

Asistana sor: Grafana Asistanı'na doğal dilde bir istem gönderin ve tam metin yanıtını bekleyin. Asistan, izole bir 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ı sohbete devam etmek için döndürülen contextId değerini bir takip çağrısında 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 engellenir.

Olaylar

Olayları ara, oluştur ve güncelle: Grafana Incident'te olayları arama, oluşturma, etkinlik ekleme ve özel alanları okuma veya ayarlama dahil olmak üzere yönetin.

Sift Araştırmaları

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

Uyarı

Uyarı kuralı bilgilerini listele ve getir: Grafana'da uyarı kurallarını ve durumlarını (tetikleniyor/normal/hata vb.) görüntüleyin. Hem Grafana yönetimli kuralları hem de Prometheus veya Loki veri kaynaklarından veri kaynağı yönetimli kuralları destekler.
Uyarı kuralları oluştur ve güncelle: Yeni uyarı kuralları oluşturun veya mevcut olanları değiştirin.
Uyarı kurallarını sil: Uyarı kurallarını UID'ye göre kaldırın.
Uyarı yönlendirmeyi yönet: Bildirim politikalarını, iletişim noktalarını ve zaman aralıklarını görüntüleyin. Hem Grafana yönetimli iletişim noktalarını hem de harici Alertmanager veri kaynaklarından (Prometheus Alertmanager, Mimir, Cortex) alıcıları destekler.

Grafana OnCall

Programları listele ve yönet: Grafana OnCall'da nöbet programlarını görüntüleyin ve yönetin.
Vardiya ayrıntılarını al: Belirli nöbet vardiyaları hakkında ayrıntılı bilgi alın.
Geçerli nöbetçi kullanıcıları al: Bir program için şu anda nöbette olan kullanıcıları görün.
Ekipleri ve kullanıcıları listele: Tüm OnCall ekiplerini ve kullanıcılarını görüntüleyin.
Uyarı gruplarını listele: 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: Kimliğine göre belirli bir uyarı grubu hakkında ayrıntılı bilgi alın.

Yönetim

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

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

Kullanıcı

Kullanıcı bilgileri: Geçerli Grafana kimliğini alın — oturum açma, e-posta, ad, Grafana (sunucu) yöneticisi olup olmadığı, geçerli kuruluş ve kimlik bilgisinin erişebildiği kuruluşlar (rollerle birlikte). çok kuruluşlu istekleri için geçerli orgId değerlerini keşfetmek için kullanın.

Gezinme

Derin bağlantılar oluştur: LLM URL tahminine güvenmek yerine Grafana kaynakları için doğru derin bağlantı URL'leri oluşturun.
- Pano bağlantıları: UID'lerini kullanarak panolara doğrudan bağlantılar oluşturun (örn. http://localhost:3000/d/dashboard-uid)
- Panel bağlantıları: viewPanel parametresiyle panolardaki belirli panellere bağlantılar oluşturun (örn. http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Keşfet bağlantıları: Önceden yapılandırılmış veri kaynaklarıyla Grafana Explore'a bağlantılar oluşturun (örn. http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana 10.2'nin altı panes anlamaz, bu nedenle bu sürümler için eski ?left={...} biçimi yayınlanır.
- Zaman aralığı desteği: Bağlantılara zaman aralığı parametreleri ekleyin (from=now-1h&to=now)
- Özel parametreler: Pano değişkenleri veya yenileme aralıkları gibi ek sorgu parametreleri ekleyin

Ek Açıklamalar

Ek Açıklamaları Al: Filtrelerle ek açıklamaları sorgulayın. Zaman aralığını, pano UID'sini, etiketleri ve eşleştirme modunu destekler.
Ek Açıklama Oluştur: Bir panoda veya panelde yeni bir ek açıklama oluşturun.
Graphite Ek Açıklaması Oluştur: Graphite biçimini kullanarak ek açıklamalar oluşturun (what, when, tags, data).
Ek Açıklamayı Güncelle: Mevcut bir ek açıklamanın tüm alanlarını değiştirin (tam güncelleme).
Ek Açıklamayı Yama: Bir ek açıklamanın yalnızca belirli alanlarını güncelleyin (kısmi güncelleme).
Ek Açıklamayı Sil: Bir ek açıklamayı kimliğine göre kalıcı olarak silin.
Ek Açıklama Etiketlerini Al: İsteğe bağlı filtrelemeyle kullanılabilir ek açıklama etiketlerini listeleyin.

Anlık Görüntüler

Anlık görüntüleri listele: İsteğe bağlı sorgu ve limit filtreleriyle pano anlık görüntülerini listeleyin.
Anlık görüntüyü al: Anlık görüntü anahtarına göre anlık görüntü meta verilerini ve pano yükünü alın.
Anlık görüntü oluştur: İsteğe bağlı sona erme ve harici anlık görüntü seçenekleriyle tam bir pano yükünden bir pano anlık görüntüsü oluşturun.
Anlık görüntüyü sil: Anlık görüntü anahtarına göre bir anlık görüntüyü silin.

İşleme

Panel veya pano görüntüsünü al: Bir Grafana pano panelini veya tam panoyu 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 pano 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ış panoları işlemeyi destekler.
- Not: Grafana Image Renderer hizmetinin kurulu ve yapılandırılmış olmasını gerektirir.

Sağlama

Sağlama depolarını listele: Bu Grafana örneği için yapılandırılmış sağlama depolarını (örn. git-sync kaynakları) listeleyin ve her deponun kısa adını kaynak URL'si, dalı, yolu, eşitleme durumu ve sağlığıyla birlikte döndürün.
Sağlama dosyasını doğrula: Belirli bir dalda veya taahhütte bir sağlama deposundan bir dosyayı kuru çalıştırma 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ı kullanılabilir hale getirmek istediğinizi seçebilirsiniz. Bu, belirli işlevleri kullanmıyorsanız veya bağlam penceresinin çok fazlasını kaplamak istemiyorsanız yararlı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 gezinme 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ı, 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 bu nedenle daha az kısıtlayıcıdır), bu nedenle yalnızca kolaylık katı 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ı listele, araştırmaları al)
Düzenleyici rolü: Yazma işlemleri için gereklidir (olaylar oluştur, araştırmaları değiştir)

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 panolara erişim
- folders:* - Tüm klasörlere erişim
- teams:* - Tüm ekiplere erişim
Sınırlı erişim: Tekil kaynaklara erişimi 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 panoya 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)

Panoya özel erişim: Yalnızca belirli panoları okuyun

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

Araçlar

Araç	Kategori	Açıklama	Gerekli RBAC İzinleri	Gerekli Kapsamlar
`list_teams`	Yönetici	Tüm ekipleri listele	`teams:read`	`teams:*` veya `teams:id:1`
`list_users_by_org`	Yönetici	Bir organizasyondaki tüm kullanıcıları listele	`users:read`	`global.users:*` veya `global.users:id:123`
`list_all_roles`	Yönetici	Tüm Grafana rollerini listele	`roles:read`	`roles:*`
`get_role_details`	Yönetici	Bir Grafana rolünün ayrıntılarını al	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Yönetici	Bir rol için atamaları listele	`roles:read`	`roles:uid:editor`
`list_user_roles`	Yönetici	Kullanıcılar için rolleri listele	`roles:read`	`global.users:id:123`
`list_team_roles`	Yönetici	Ekipler için rolleri listele	`roles:read`	`teams:id:7`
`get_resource_permissions`	Yönetici	Bir kaynak için izinleri listele	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Yönetici	Bir Grafana kaynak türünü tanımla	`permissions:read`	`dashboards:*`
`user_info`	Kullanıcı	Geçerli kimlik, yetenekler ve erişilebilir organizasyonlar	Yok (oturum açmış kullanıcı)	—
`search_dashboards`	Arama	Sorgu, klasör UID, etiket veya yıldızlıya göre panoları ara	`dashboards:read`	`dashboards:*` veya `dashboards:uid:abc123`
`get_dashboard_by_uid`	Pano	Bir panoyu uid ile, isteğe bağlı olarak kaydedilmiş bir sürümle al	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Pano	Bir panonun kaydedilmiş sürümlerini listele (sürüm, yazar, zaman, mesaj)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Pano	Yeni bir pano güncelle veya oluştur	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` veya `folders:uid:xyz789`
`get_dashboard_panel_queries`	Pano	Bir panodan panel başlığı, sorgular, veri kaynağı UID ve türünü al	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	PanelSorgusuÇalıştır*	Bir veya daha fazla pano panel sorgusunu yürüt	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Pano	JSONPath ifadeleri kullanarak bir panonun belirli bölümlerini çıkar	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Pano	Tam JSON olmadan bir panonun kompakt bir özetini al	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Veri Kaynakları	Veri kaynaklarını listele	`datasources:read`	`datasources:*`
`get_datasource`	Veri Kaynakları	UID veya ada göre bir veri kaynağı al	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Örnekler*	Bir veri kaynağı türü için örnek sorgular al	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Bir Prometheus veri kaynağına karşı bir sorgu yürüt	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Metrik meta verilerini listele	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Kullanılabilir metrik adlarını listele	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Bir seçiciyle eşleşen etiket adlarını listele	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Belirli bir etiket için değerleri listele	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Histogram yüzdelik değerlerini hesapla	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Olay	Grafana Incident'te olayları, isteğe bağlı olarak özel alan değerleriyle listele	Görüntüleyici rolü	N/A
`create_incident`	Olay	Grafana Incident'te bir olay oluştur, isteğe bağlı olarak özel alanları ayarla	Düzenleyici rolü	N/A
`add_activity_to_incident`	Olay	Grafana Incident'te bir olaya bir etkinlik öğesi ekle	Düzenleyici rolü	N/A
`update_incident`	Olay	Grafana Incident'te bir olayı güncelle (durum, önem, başlık veya özel alanlar)	Düzenleyici rolü	N/A
`get_incident`	Olay	Kimliğe göre tek bir olayı, özel alanları dahil al	Görüntüleyici rolü	N/A
`list_incident_custom_fields`	Olay	Olaylar için yapılandırılmış özel alanları, türleri ve seçenek seçenekleriyle listele	Görüntüleyici rolü	N/A
`query_loki_logs`	Loki	LogQL kullanarak günlükleri sorgula ve al (günlük veya metrik sorguları)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Günlüklerdeki tüm kullanılabilir etiket adlarını listele	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Belirli bir günlük etiketi için değerleri listele	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Günlük akışları hakkında istatistikler al	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Ortak yapıları tanımlamak için algılanan günlük desenlerini sorgula	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Bir Loki etiket stratejisini denetle (canlı veya statik) ve isteğe bağlı olarak sorgu performansını teşhis et	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Yapılandırma	Onaylanan etiketleri zorunlu kılan bir Alloy `loki.process` snippet'i oluştur	N/A	N/A
`query_influxdb`	InfluxDB	InfluxDB'yi InfluxQL (v1) veya Flux (v2) kullanarak sorgula	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Bir SQL veri kaynağından veritabanlarını, şemaları veya katalogları listele	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Bir SQL veri kaynağındaki tabloları listele	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Bir tablo için sütun şemasını al	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Makro değişimi ile SQL sorguları çalıştır	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Kullanılabilir AWS CloudWatch ad alanlarını listele	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Bir ad alanındaki metrikleri listele	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Bir metrik için boyutları listele	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Bir boyut anahtarı için değerleri listele	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	CloudWatch metrik sorgularını çalıştır	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Bir Google Cloud Logging veri kaynağı tarafından okunabilen GCP projelerini listele	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Bir GCP projesindeki günlük paketlerini listele	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Bir günlük paketindeki günlük görünümlerini listele	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Cloud Logging sorgu dili ile günlükleri sorgula	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Lucene sözdizimi veya Query DSL kullanarak Elasticsearch veya OpenSearch sorgula	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Lucene sözdizimi veya Query DSL kullanarak Quickwit sorgula	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Uyarı kurallarını yönet (listele, al, sürümler, oluştur, güncelle, sil)	`alert.rules:read` + `alert.rules:write` değişiklikler için	`folders:*` veya `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Bildirim politikalarını, iletişim noktalarını ve zaman aralıklarını yönet	`alert.notifications:read`	Global kapsam
`alerting_manage_silences`	Alerting	Uyarı susturmalarını yönet (listele, al, oluştur, güncelle, süresi doldur)	`alert.instances:read` + `alert.instances:write` değişiklikler için	Global kapsam
`list_oncall_schedules`	OnCall	Grafana OnCall'dan programları listele	`grafana-oncall-app.schedules:read`	Eklentiye özel kapsamlar
`get_oncall_shift`	OnCall	Belirli bir OnCall vardiyası için ayrıntıları al	`grafana-oncall-app.schedules:read`	Eklentiye özel kapsamlar
`get_current_oncall_users`	OnCall	Belirli bir program için şu anda nöbette olan kullanıcıları al	`grafana-oncall-app.schedules:read`	Eklentiye özel kapsamlar
`list_oncall_teams`	OnCall	Grafana OnCall'dan ekipleri listele	`grafana-oncall-app.user-settings:read`	Eklentiye özel kapsamlar
`list_oncall_users`	OnCall	Grafana OnCall'dan kullanıcıları listele	`grafana-oncall-app.user-settings:read`	Eklentiye özel kapsamlar
`list_alert_groups`	OnCall	Filtreleme seçenekleriyle Grafana OnCall'dan uyarı gruplarını listele	`grafana-oncall-app.alert-groups:read`	Eklentiye özel kapsamlar
`get_alert_group`	OnCall	Kimliğine göre Grafana OnCall'dan belirli bir uyarı grubunu al	`grafana-oncall-app.alert-groups:read`	Eklentiye özel kapsamlar
`update_alert_group`	OnCall	Bir uyarı grubunu onayla, onayı kaldır, çöz veya çözümü kaldır	`grafana-oncall-app.alert-groups:write` (ve `:read`)	Eklentiye özel kapsamlar
`get_sift_investigation`	Sift	UUID'sine göre mevcut bir Sift incelemesini al	Görüntüleyici rolü	N/A
`get_sift_analysis`	Sift	Bir Sift incelemesinden belirli bir analizi al	Görüntüleyici rolü	N/A
`list_sift_investigations`	Sift	İsteğe bağlı bir sınırla Sift incelemelerinin listesini al	Görüntüleyici rolü	N/A
`find_error_pattern_logs`	Sift	Loki günlüklerinde yükseltilmiş hata desenlerini bulur.	Editör rolü	N/A
`find_slow_requests`	Sift	İlgili tempo veri kaynaklarından yavaş istekleri bulur.	Editör rolü	N/A
`list_pyroscope_label_names`	Pyroscope	Bir seçiciyle eşleşen etiket adlarını listele	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Bir etiket adı için bir seçiciyle eşleşen etiket değerlerini listele	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Kullanılabilir profil türlerini listele	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Pyroscope'tan profilleri, metrikleri veya her ikisini sorgula	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Belirli bir varlık için özet doğrulama al	Eklentiye özel izinler	Eklentiye özel kapsamlar
`agento11y_manage_conversations`	Agent Observability*	Grafana Agent Observability'dan LLM konuşmalarını listele, ara ve getir	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Grafana Agent Observability'dan LLM üretim ayrıntılarını ve değerlendirme puanlarını getir	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Ajan kataloğunu oku: ajanları listele, bir ajan sürümünü tam olarak al, sürüm geçmişini ve sürüm başına puan toplamlarını listele	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Değerlendiricileri, değerlendirici şablonlarını ve jüri kataloğunu yönet (listele, al, ekle/güncelle, çatalla, test et, sil)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` değişiklikler ve testler için	N/A
`agento11y_manage_eval_rules`	Agent 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çin	N/A
`agento11y_manage_eval_collections`	Agent 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çin	N/A
`agento11y_manage_experiments`	Ajan Gözlemlenebilirliği*	Çevrimdışı deneyleri, denemelerini, puanlarını, yapıt meta verilerini ve filtre yönlerini okuyun; bir deneyi güncelleyin ve iptal edin	Mutasyonlar için `grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write`	N/A
`agento11y_manage_test_suites`	Ajan Gözlemlenebilirliği*	Çevrimdışı deneylerin çalıştığı test paketlerini, sürümlerini ve test durumlarını yönetin (listele, al, oluştur, güncelle, taslak, yayınla, upsert, sil)	Mutasyonlar için `grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write`	N/A
`ask_assistant`	Asistan*	Grafana Asistanı'na bir istem gönderin ve tam metin yanıtını döndürün (`contextId` ile çok turlu)	Eklentiye özel izinler	Eklentiye özel kapsamlar
`generate_deeplink`	Gezinme	Grafana kaynakları için doğru derin bağlantı URL'leri oluşturun	Yok (salt okunur URL oluşturma)	N/A
`get_annotations`	Ek Açıklamalar	Filtrelerle ek açıklamaları getirin	`annotations:read`	`annotations:*` veya `annotations:id:123`
`create_annotation`	Ek Açıklamalar	Yeni bir ek açıklama oluşturun (standart veya Graphite biçimi)	`annotations:write`	`annotations:*`
`update_annotation`	Ek Açıklamalar	Bir ek açıklamanın belirli alanlarını güncelleyin (kısmi güncelleme)	`annotations:write`	`annotations:*`
`delete_annotation`	Ek Açıklamalar	Bir ek açıklamayı kimliğine göre silin	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Ek Açıklamalar	İsteğe bağlı filtrelemeyle ek açıklama etiketlerini listeleyin	`annotations:read`	`annotations:*`
`list_snapshots`	Anlık Görüntü	İsteğe bağlı sorgu ve sınır filtreleriyle pano anlık görüntülerini listeleyin	`dashboards:read`	`dashboards:*` veya `dashboards:uid:abc123`
`get_snapshot`	Anlık Görüntü	Anlık görüntü anahtarına göre anlık görüntü meta verilerini ve pano yükünü alın	`dashboards:read`	`dashboards:*` veya `dashboards:uid:abc123`
`create_snapshot`	Anlık Görüntü	Tam bir pano yükünden bir pano anlık görüntüsü oluşturun	`dashboards:write`	`dashboards:*` veya `dashboards:uid:abc123`
`delete_snapshot`	Anlık Görüntü	Anlık görüntü anahtarına göre bir pano anlık görüntüsünü silin	`dashboards:write`	`dashboards:*` veya `dashboards:uid:abc123`
`get_panel_image`	İşleme	Saklanan bir panoyu veya paneli — veya bir depo dalından sağlama önizlemesini — PNG görüntüsü olarak işleyin	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Sağlama	Sağlama depolarını (ör. git-sync kaynakları) kaynak URL'si, dal, eşitleme durumu ve sağlık durumuyla listeleyin	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Sağlama	Bir sağlama deposundan bir dosyayı kuru çalıştırma uygulayın ve kabul doğrulama hatalarını bildirin	`provisioning.repositories:read`	N/A
`search_docs`	Belgeler	Grafana belgelerini arayın veya ürün gruplarını listeleyin (ürünleri listelemek için sorguyu atlayın)	Yok (genel grafana.com/docs)	N/A
`get_doc`	Belgeler	Bir belge sayfasını getirin; başlıklar için outline_only veya sınırlı alma için section ayarlayın	Yok (genel grafana.com/docs)	N/A
* Varsayılan olarak devre dışıdır. Etkinleştirmek için `--enabled-tools` kategorisine ekleyin.

CLI Bayrakları Referansı

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

Taşıma 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. /healthz ve /metrics her zaman sunucu kökünde sunulur, bu önek altında değil — bunlar yalnızca iç uç noktalardır ve bunları uygulama önekinden ayrı tutmak, API'yi ters proxy üzerinden açığa çıkarmayı kolaylaştırır
--endpoint-path: streamable-http sunucusu için uç nokta yolu, --base-path değerine eklenir - 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
--instructions-append: Başlatma sırasında MCP istemcilerine döndürülen sunucu talimatlarına eklenen metin, böylece bağlanan her aracı bunu görür

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

Host/Origin doğrulaması, MCP dinleyicisindeki her rotada zorunludur — /sse, /mcp ve /healthz / /metrics aynı dinleyiciyi paylaştığında — bu nedenle DNS-rebinding tarayıcısı bunların hiçbirine ulaşamaz. Stdio taşıması etkilenmez. --healthz-address ve --metrics-address sarmalanmayan ayrı bir dinleyici başlatır.

--allowed-hosts: Host başlık değerlerinin virgülle ayrılmış beyaz listesi. Varsayılan olarak --address döngüsel varyantlarına (ör. localhost:8000,127.0.0.1:8000,[::1]:8000) ayarlanır. Boş olarak ayrıştırılan bir değer (ayarlanmamış, ,, , vb.) da 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. * değerini geçirerek Host doğrulamasını devre dışı bırakın — yalnızca güvenilir bir ters proxy Host doğruladığında güvenlidir. K8s httpGet probları ve harici /metrics taramaları, bu listede açık bir ana bilgisayar adına, * değerine, bir tcpSocket probuna veya ayrı bir bağlantı noktasına (--healthz-address / --metrics-address) ihtiyaç duyar.
--allowed-origins: Origin başlık değerlerinin virgülle ayrılmış beyaz listesi. Varsayılan olarak boş — Origin başlığı taşıyan herhangi bir istek reddedilir (tarayıcılar çapraz kaynak istekleri 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 liste ayarlayın veya kontrolü devre dışı bırakmak için * değerini kullanın.
--allow-grafana-url-override: X-Grafana-URL seçimini etkinleştirin. GRAFANA_ALLOW_URL_OVERRIDE değerine geri döner; varsayılan olarak devre dışıdır. Beyaz liste olmadan, çağıranlar sunucunun erişebildiği herhangi bir HTTP(S) URL'sini seçebilir.
--allowed-grafana-urls: URL geçersiz kılmaları için isteğe bağlı virgülle ayrılmış tam Grafana temel URL beyaz listesi. GRAFANA_ALLOWED_URLS değerine geri döner. --allow-grafana-url-override gerektirir; açık bir boş bayrak, devralınan bir listeyi devre dışı bırakır.

Ç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 taşıyıcı belirteci. MCP_GRAFANA_SERVER_TOKEN ortam değişkenine geri döner. Ayarlanırsa, geçerli bir belirteç olmayan istekler herhangi bir araç çalışmadan önce 401 ile reddedilir. Sırrın işlem bağımsız değişkenlerinde görünmemesi için ortam değişkenini tercih edin.

Çağıran kimlik doğrulaması yalnızca --server-auth-token ayarlandığında zorunludur. Ayarlanmadığında ve sunucu döngüsel olmayan bir adrese bağlandığında, sunucu başlar ancak bir güvenlik hatası günlüğe kaydeder — error günlük düzeyinde yayınlanır, böylece --log-level tarafından gizlenmez (döngüsel ve stdio etkilenmez); gelecekteki bir ana sürüm bunu bir başlangıç hatası yapacaktır. Çağıran kimlik doğrulaması döngüsel 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 kombinasyonu başlangıçta reddedilir.

Grafana URL Geçersiz Kılmaları (yalnızca SSE / streamable-http):

[!UYARI] URL geçersiz kılmaları, MCP çağıranlarının giden HTTP(S) hedeflerini seçmesine izin verir. Beyaz liste URL'leri sınırlar ancak çağıranların kimliğini doğrulamaz veya belirteçleri hedeflere bağlamaz.

Her hedefi yetkilendiren, istemci tarafından sağlanan URL ve belirteç başlıklarını değiştiren ve eşleşen belirteci sağlayan kimlik doğrulayan bir proxy arkasında dağıtın. Sunucunun giden ağ erişimini onaylanmış hedeflerle sınırlayın.

Beyaz liste olmadan, sahte bir istek belirteci, iç ve meta veri hizmetleri dahil olmak üzere erişilebilir herhangi bir HTTP(S) hizmetine istek gönderilmesine neden olabilir.

Büyük bir filo için seçimi etkinleştirmek üzere GRAFANA_ALLOW_URL_OVERRIDE=true (veya --allow-grafana-url-override) ayarlayın. Hedefleri kısıtlamak için ayrıca GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (veya --allowed-grafana-urls) ayarlayın.

Bir hedef seçen her MCP isteğinde şu başlıkları gönderin:

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

--server-auth-token yapılandırılmışsa, ayrıca Authorization: Bearer <MCP caller token> gönderin. Bu, MCP sunucusuna kimlik doğrulaması yapar ve seçilen Grafana örneği için olan X-Grafana-Service-Account-Token değerinden ayrıdır. Proxy'niz her örnek için farklı bir Grafana belirteci gönderebilir; sunucu yapılandırılmış bir belirteci asla aralarında paylaşmaz. Kullanımdan kaldırılmış X-Grafana-API-Key başlığı da çalışır. İstek Grafana belirteci olmayan bir URL başlığı reddedilir. Belirteç taşıdıkları için gelen istekler için TLS kullanın.

Beyaz liste, şema, bağlantı noktası ve yolu içeren tam temel URL'leri eşleştirir; joker karakterler desteklenmez. Grafana kimlik doğrulaması bir SSRF savunması değildir.

Seçilen bir URL için sunucu GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, ortam temel kimlik doğrulaması, GRAFANA_EXTRA_HEADERS veya istemci sertifikalarını kullanmaz. --tls-skip-verify ayarlanmış olsa bile TLS doğrulaması etkin kalır; yapılandırılmış bir CA dosyası yine de geçerlidir. Bu istekten açıkça iletilen başlıklar yine de geçerlidir. Seçilen temel URL dışındaki yönlendirmeler ve diğer Grafana API istekleri engellenir. X-Grafana-URL olmayan istekler olağan GRAFANA_URL ve ortam kimlik bilgisi davranışını korur. Bu seçenek yalnızca SSE ve streamable HTTP için geçerlidir. SSE için, her mesaj POST'una her iki seçim başlığını da ekleyin; ilk SSE GET'indeki başlıklar araç çağrılarına taşınmaz.

Hata Ayıklama ve Günlüğe Kaydetme:

--debug: Ayrıntılı HTTP istek/yanıt günlüğü için hata ayıklama modunu etkinleştirin
--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 (ör. 10s, 500ms) - varsayılan: 10s
--include-args-in-spans: OpenTelemetry yayılmalarına araç çağrısı bağımsız değişkenlerini dahil edin. Yalnızca üretim dışı ortamlarda veya bağımsız değişkenlerin PII içermediği bilindiğinde etkinleştirin - varsayılan: false

Gözlemlenebilirlik:

--metrics: /metrics adresinde Prometheus metrikleri uç noktasını etkinleştirin
--metrics-address: Metrik sunucusu için ayrı adres (ör. :9090). Boşsa, metrikler ana sunucuda sunulur
--healthz-address: /healthz için ayrı adres (ör. :8080). Boşsa, /healthz ana sunucuda sunulur. İki adres eşleştiğinde --metrics-address ile bir dinleyiciyi paylaşır. Yan dinleyiciler Host/Origin doğrulamasını atlar.
--slow-request-threshold: Herhangi bir MCP isteği (araç çağrısı, liste, kaynak okuma vb.) bu süreden uzun sürdüğünde bir olay günlüğe kaydedin. Go süre dizelerini kabul eder (ör. 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.

Anonim Kullanım İstatistikleri:

--usage-stats: Anonim kullanım istatistikleri raporlaması: enabled, disabled veya log (gönderilecek raporu stderr'e yazdırır ve hiçbir şey göndermez). GRAFANA_USAGE_STATS ortam değişkenini geçersiz kılar, bu da DO_NOT_TRACK değerini geçersiz kılar; tanınmayan herhangi bir değer raporlamayı devre dışı bırakır. Anonim kullanım istatistikleri bölümüne bakın.

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: Etkin kategorilerin virgülle ayrılmış listesi - varsayılan: admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery ve snowflake dışındaki tüm kategoriler. Devre dışı kategorileri etkinleştirmek için bunları listeye ekleyin (ör. "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: Kesilme algılamasına izin vermek için bunu Loki'nin sunucu tarafındaki max_entries_limit_per_query değerinin en az 1 altında ayarlayın (araç, daha fazla veri olup olmadığını algılamak için dahili olarak limit+1 ister).
--loki-guardrail-mode: query_loki_logs için Loki sorgu maliyet koruması - varsayılan: off. Loki, satır filtresi olmayan günlük sorgularında max_query_bytes_read uygulamaz; bu nedenle geniş bir aralıkta geniş bir seçici terabaytları tarayabilir; koruma, seçici bir akış seçici gerektirir, etkin zaman aralığını sınırlar ([30d] gibi aralık vektör süreleri dahil) ve sorguyu çalıştırmadan önce Loki'nin dizin/istatistik bayt tahminini önceden kontrol eder. shadow, engellenecek sorguları günlüğe kaydeder ancak çalıştırılmasına izin verir (yine de dizin/istatistik gidiş-dönüşünü öder); enforce, LLM'nin uygulayabileceği yeniden yazma yönergeleriyle bunları reddeder. VictoriaLogs'ta koruma yalnızca seçici biçimli ({...}) sorgulara uygulanır — hiçbir seçici ayrıştırılmadığında (normal parantezsiz LogsQL biçimi), sorgu tamamen geçer ve bayt bütçesi kontrolü asla uygulanmaz (ucuz dizin tahmini yoktur). Ortam değişkeni yedeği: GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes: Tek bir query_loki_logs çağrısının tarayabileceği maksimum bayt sayısı, Loki'nin dizin/istatistik API'si aracılığıyla tahmin edilir - varsayılan: 107374182400 (100 GiB). 0, bayt bütçesi kontrolünü devre dışı bırakır. Ortam değişkeni yedeği: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Tek bir query_loki_logs çağrısı için maksimum etkin zaman aralığı, aralık vektör süreleri dahil - varsayılan: 24h. Go süre dizelerini kabul eder. 0, aralık kontrolünü devre dışı bırakır. Ortam değişkeni yedeği: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: Hangi günlük akışlarının okunabileceğini kısıtlamak için her yerel-Loki sorgusuna VE ile eklenen LogQL etiket eşleştiricileri (ör. environment=~"prod|staging"). --disable-api gerektirir. Loki sorgu zorunluluğuna bakın.
--loki-label-enumeration-fallback: Negatif zorunlu eşleştiriciler etiket numaralandırma araçlarını kapsamlandıramadığında ne yapılacağı: reject (varsayılan) veya unfiltered. Loki sorgu zorunluluğuna bakın.
--disable-search: Arama araçlarını devre dışı bırak
--disable-datasource: Veri kaynağı araçlarını devre dışı bırak
--disable-incident: Olay 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-query: Sorgu araçlarını devre dışı bırak (bir veri kaynağına karşı sorgu yürüten araçlar); meta veri ve keşif araçları kullanılabilir kalır
--enable-query: Ham-SQL sorgu araçlarını (query_sql, query_influxdb) --disable-write altında bile kayıtlı tut. --enable-write-tools=query_sql,query_influxdb ile eşdeğerdir; bu yaygın durum için bir kısayol olarak tutulur.
--enable-write-tools: --disable-write altında bile kayıtlı tutulacak bireysel araç adlarının virgülle ayrılmış listesi; yazma davranışı bağımsız olarak geri alınabilecek kadar kapsamlı olan araçlar için (ör. find_error_pattern_logs,find_slow_requests). Tüm kategorisi devre dışı bırakılmış bir araç üzerinde etkisi yoktur, ör. --disable-sift aracılığıyla.
--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: Uyarı araçlarını devre dışı bırak
--disable-dashboard: Pano 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/pano görüntü dışa aktarma)
--disable-snapshot: Anlık görüntü araçlarını devre dışı bırak
--disable-cloudwatch: CloudWatch araçlarını devre dışı bırak
--disable-cloudlogging: Google Cloud Logging araçlarını devre dışı bırak
--disable-examples: Sorgu örneği araçlarını devre dışı bırak
--disable-sql: SQL veri kaynağı araçlarını devre dışı bırak (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). --disable-clickhouse, --disable-snowflake, --disable-athena takma adları da çalışır.
--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-provisioning: Sağlama araçlarını devre dışı bırak
--disable-agento11y: Aracı Gözlemlenebilirliği araçlarını devre dışı bırak
--disable-assistant: Grafana Asistanı araçlarını devre dışı bırak
--disable-docs: Dokümantasyon 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 yönelik tüm yazma işlemlerini engeller. 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
AI asistanlarına değişiklik yetenekleri 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:

Pano Araçları:

update_dashboard

Klasör Araçları:

create_folder

Olay Araçları:

create_incident
add_activity_to_incident
update_incident

Uyarı Araçları:

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

OnCall Araçları:

update_alert_group

Açıklama Araçları:

create_annotation
update_annotation
delete_annotation

Sift Araçları:

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

Bunlar yalnızca Sift API aracılığıyla geçici Sift araştırma kayıtları oluşturur — asla bir Grafana panosuna, uyarısına veya veri kaynağına dokunmazlar. Bunlar olmadan, list_sift_investigations/get_sift_investigation/get_sift_analysis listelenecek veya alınacak hiçbir şeye sahip olmaz. Bunları --disable-write altında kayıtlı tutmak için --enable-write-tools=find_error_pattern_logs,find_slow_requests değerini iletin.

Anlık Görüntü Araçları:

create_snapshot
delete_snapshot

Ham-SQL Sorgu Araçları:

Bunlar, incelemeden kendilerine verilen herhangi bir sorguyu yürütür; bu nedenle veri kaynağı kimlik bilgileri izin verdiğinde yazabilirler — query_sql bir DROP TABLE çalıştırır, query_influxdb bir DELETE çalıştırır. Salt okunur mod bu nedenle bunları kaldırır. Veri kaynağı kimlik bilgilerinin salt okunur olduğu bilindiğinde bunları tutmak için --enable-query değerini iletin.

query_sql
query_influxdb

Aracı Gözlemlenebilirliği Araçları:

agento11y_manage_evaluators (upsert, silme, çatallama, test değerlendirici işlemleri)
agento11y_manage_eval_rules (oluşturma, güncelleme, silme, önizleme kuralı ve koruma işlemleri)
agento11y_manage_eval_collections (kayıtlı konuşmaları kaydetme ve silme; koleksiyonları oluşturma, güncelleme, silme; koleksiyon üyeleri ekleme ve kaldırma)
agento11y_manage_experiments (deney işlemlerini güncelleme ve iptal etme)
agento11y_manage_test_suites (test paketleri oluşturma ve güncelleme; sürümler oluşturma ve yayınlama; test durumlarını upsert ve silme)

Tüm okuma işlemleri kullanılabilir kalır; panoları sorgulamanıza, PromQL/LogQL sorguları çalıştırmanıza, kaynakları listelemenize ve veri almanıza olanak tanır. Yazma ifade edemeyen sorgu dilleri — PromQL, LogQL, TraceQL, Elasticsearch DSL, Graphite, CloudWatch — sorgu araçlarını salt okunur modda tutar; yalnızca yukarıda listelenen ham-SQL araçları kaldırılır.

Sorgusuz Mod

--disable-query bayrağı, bir veri kaynağına karşı sorgu yürüten her aracı kaldırırken meta veri ve keşif araçlarını yerinde bırakır. Bu, asistanın potansiyel olarak pahalı veya veri açığa çıkaran sorgular çalıştırmadan neyin var olduğunu keşfedebilmesini istediğinizde kullanışlıdır — örneğin hizmet hesabının datasources:read ancak datasources:query olmadığı durumlarda.

Üç sorgu ayarının en güçlüsüdür ve --enable-query üzerinde kazanır:

Bayraklar	Güvenli sorgu araçları (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Ham-SQL sorgu araçları (`query_sql`, `query_influxdb`)
(yok)	kayıtlı	kayıtlı
`--disable-write`	kayıtlı	kayıtlı değil
`--disable-write --enable-query`	kayıtlı	kayıtlı
`--disable-query`	kayıtlı değil	kayıtlı değil
`--disable-query --enable-query`	kayıtlı değil	kayıtlı değil

--disable-query etkinleştirildiğinde, aşağıdaki araçlar kayıtlı değildir:

Prometheus Araçları:

query_prometheus
query_prometheus_histogram

Loki Araçları:

query_loki_logs
query_loki_patterns

query_loki_stats ve analyze_loki_labels kayıtlı kalır: her ikisi de veri kaynağına bir seçici gönderir, ancak dizini okur ve günlük içeriği yerine akış, öbek ve bayt sayılarını döndürür.

Elasticsearch/OpenSearch ve Quickwit Araçları:

query_elasticsearch
query_quickwit

InfluxDB Araçları (ayrıca --disable-write tarafından kaldırılır, yukarıya bakın):

query_influxdb

SQL Veri Kaynağı Araçları (ayrıca --disable-write tarafından kaldırılır, yukarıya bakın):

query_sql

Graphite Araçları:

query_graphite
query_graphite_density

CloudWatch Araçları:

query_cloudwatch

Google Cloud Logging Araçları:

query_cloud_logging

Pyroscope Araçları:

query_pyroscope

Panel Sorgusu Çalıştırma Araçları:

run_panel_query

elasticsearch, quickwit, influxdb ve runpanelquery kategorileri başka hiçbir şey içermez; bu nedenle sorgular devre dışı bırakıldığında hiçbir araç kaydetmezler. Diğer her kategorideki kardeş araçlar — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects vb. — kullanılabilir kalır.

--disable-query'nin sorgu araçlarını ve grafana_api_request POST-to-/api/ds/query yolunu kapattığını, ancak bir veri kaynağına giden her rotayı denetlemediğini unutmayın. Salt okunur modda, grafana_api_request, /api/ds/query'e yalnızca sorgu araçları etkinleştirildiğinde POST'a izin verir (ham-SQL araçlarıyla aynı kapı — --enable-query geçersiz kılmadıkça --disable-write tarafından engellenir). Bir paneli sunucu tarafında işleyen get_panel_image etkilenmez.

İ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 (ör. https://myinstance.grafana.net) kullanın.

Hizmet hesabı belirteci kimlik doğrulaması kullanıyorsanız, kullanmak istediğiniz araçları kullanmak için yeterli izinlere sahip Grafana'da 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ılar için Grafana hizmet hesabı belgelerine bakın. İpucu: İnce taneli RBAC kapsamlarını 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, katı 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çin. 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.

Servis hesabı token'ını bir dosyadan okuma

Token'ı GRAFANA_SERVICE_ACCOUNT_TOKEN ile satır içi olarak iletmek yerine, token'ı içeren bir dosya yolunu GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ile işaret edebilirsiniz. Dosya her istekte yeniden okunur, böylece döndürülen token'lar sunucuyu yeniden başlatmadan otomatik olarak alınır.

Bu, özellikle Kubernetes'te kullanışlıdır; burada bir Secret birime bağlandığında, temel Secret değiştiğinde yerinde güncellenir (genellikle ~1 dakika içinde). İstek başına istemci önbelleğiyle (token değerine göre anahtarlanan) birleştirildiğinde, döndürülen bir token, pod yeniden başlatma veya 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

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

Çoklu Organizasyon Desteği

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

Ortam değişkeni: Sayısal organizasyon kimliği için GRAFANA_ORG_ID değerini ayarlayın
HTTP başlığı: SSE veya akışkan HTTP taşımalarını kullanırken X-Grafana-Org-Id değerini ayarlayın (başlık, ortam değişkenine göre önceliklidir - yani bir varsayılan org 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.

Dinamik (çağrı başına) organizasyon seçimi

Yukarıdaki seçenekler organizasyonu tüm bağlantı için sabitler. Tek bir bağlantının araç çağrısı başına farklı organizasyonları hedeflemesine izin vermek için sunucuyu --dynamic-multi-org bayrağıyla başlatın. Bu varsayılan olarak kapalıdır.

Etkinleştirildiğinde, her araç, o çağrı için bağlantının organizasyonunu geçersiz kılan isteğe bağlı bir orgId bağımsız değişkenini kabul eder (hem X-Grafana-Org-Id başlığını hem de uygulama platformu API'leri için çözümlenen Kubernetes ad alanını yönlendirir). Proxy'li veri kaynağı araçları ayrıca kimlik bilgisinin erişebildiği her organizasyonda keşfedilir. orgId değerini atlayan çağrılar, bağlantının varsayılan organizasyonunu kullanır.

Bu yalnızca birden fazla organizasyona ait kimlik bilgileri için çalışır (ör. bir kullanıcı veya bir adına kimlik); bir servis hesabı token'ı tek organizasyonuna bağlı kalır. Hangi orgId değerlerinin geçerli olduğunu keşfetmek için user_info aracını kullanın.

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ı

GRAFANA_EXTRA_HEADERS ortam değişkenini kullanarak tüm Grafana API isteklerine 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\"}"
      }
    }
  }
}

SOCKS5 Proxy

Bu sunucunun Grafana'ya yaptığı tüm istekleri GRAFANA_SOCKS5_PROXY ortam değişkenini kullanarak bir SOCKS5 proxy üzerinden yönlendirebilirsiniz. Proxy, bu sunucunun Grafana trafiğiyle sınırlıdır: genel HTTP_PROXY/HTTPS_PROXY değişkenlerini değiştirmez ve ayarlandığında yalnızca Grafana taşımaları için proxy seçimini geçersiz kılar; diğer MCP sunucularını veya kabuk oturumunuzu etkilemez. Ayarlanmadığında davranış değişmez.

URL, socks5:// veya socks5h:// şemasını kullanmalıdır (Go bunları aynı şekilde ele alır: ana bilgisayar adı çözümlemesi proxy'ye devredilir) ve kimlik bilgileri içerebilir, ör. socks5://user:pass@127.0.0.1:1080.

Örnek:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Geçersiz bir proxy URL'si başlangıç hatasıdır ve çalışma zamanında proxy'li bir bağlantı kurulamazsa sunucu, Grafana trafiğini sessizce doğrudan göndermek yerine kapalı kalır.

İstemciden Başlıkları İletme (Yalnızca SSE/Akışkan-HTTP)

MCP sunucusu SSO'yu işleyen bir ağ geçidi veya ters proxy'nin arkasında çalıştığında (ör. OIDC ile bir AWS ALB), her kullanıcının oturum çerezi Grafana'ya ulaşmalıdır, 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 etkinleştirir.

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

Örnek: oturum çerezini 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, gelen istekten gelen değer o istek için önceliklidir.

İzleme bağlamı başlıkları (traceparent, tracestate, baggage) istisnadır: sunucu izleme bağlamını kendisi yayar, bu nedenle iletilen bir değer enjekte ettiği değeri asla geçersiz kılmaz. gözlemlenebilirlik bölümüne bakın.

mcp-grafana kurmak için birkaç seçeneğiniz var:
- uvx (önerilir): uv kuruluysa, ek kurulum gerekmez — uvx sunucuyu otomatik olarak indirip çalıştırır:
```
uvx mcp-grafana
```
- Docker görüntüsü: Docker Hub'dan önceden oluşturulmuş Docker görüntüsünü kullanın.
  
  Önemli: Docker görüntüsü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üvenceye alın: SSE ve akışkan-http modlarında kapsayıcı, döngü dışı bir adres bağlar (0.0.0.0:8000). Arayan token'ı 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 değerini ayarlayın (önerilir). STDIO modu etkilenmez. Arayan Kimlik Doğrulaması bölümüne bakın.
  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çığa çıkarmalı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. Akışkan HTTP Modu: Bu modda sunucu, birden fazla istemci bağlantısını işleyebilen bağımsız bir işlem olarak çalışır. -p bayrağını kullanarak 8000 numaralı bağlantı noktasını açığa çıkarmalı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 akışkan 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: sürümler sayfasından mcp-grafana son sürümünü indirin ve $PATH dizinine yerleştirin.
- Kaynaktan derleyin: Bir 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
```

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 görüntüsündeki varsayılan SSE modunu geçersiz kılar.

VSCode'u uzak MCP sunucusuyla kullanma

VSCode kullanıyorsanız ve MCP sunucusunu SSE modunda çalıştırıyorsanız (taşımayı geçersiz kılmadan Docker görüntüsünü kullanırken varsayılan olan), .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 akışkan 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 görüntüsündeki 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 dahil:

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:

Kendi imzalı sertifikalarla test 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 özellikli 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 Akışkan HTTP Taşıması)

Akışkan 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üvenceye almanız gerektiğinde kullanışlıdır.

Sunucu, akışkan 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ı, akışkan HTTP taşımasını kullanırken istemcilerin MCP sunucusuna nasıl bağlandığını yapılandırır.

HTTPS akışkan 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/ adresine 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 akışkan 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

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

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

Anonim Kullanım İstatistikleri

Sunucu, kendisi hakkında Grafana Labs'a anonim kullanım istatistikleri bildirebilir: hangi araçların çağrıldığı, bu çağrıların kaçının başarısız olduğu ve sunucunun nasıl yapılandırıldığı. Bir rapor, bir sunucu sürecini kapsar — bir kullanıcıyı veya bir konuşmayı değil — ve her 4 saatte bir ve kapanışta bir kez gönderilir. Bu sürümde raporlama varsayılan olarak devre dışıdır — alıcı uç nokta henüz canlı değil — ve sonraki bir sürüm, aynı devre dışı bırakma seçeneğiyle varsayılanı etkin olarak değiştirecektir.

Araç argümanları, kaynak adları, sorgular, günlük satırları, hata mesajları ve kimlik bilgileri asla gönderilmez. Bayraklar yalnızca adlarıyla kaydedilir, asla değerleriyle kaydedilmez ve Grafana örneği yalnızca cloud veya self_hosted olarak tanımlanır — asla URL, ana bilgisayar adı, yığın takma adı veya kuruluş ile değil. Hiçbir şey kullanıcı başına, oturum başına veya istemci başına değildir: kabloda oturum tanımlayıcısı yoktur ve bir araç çağrısını belirli bir istemciye atfetmenin bir yolu yoktur.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 ayrıca, araçlar arası DO_NOT_TRACK kuralını izleyerek raporlamayı devre dışı bırakır. Yalnızca 1'in bir etkisi vardır, yalnızca devre dışı bırakabilir ve hem --usage-stats hem de GRAFANA_USAGE_STATS onu geçersiz kılar; bu nedenle onu genel olarak ayarlayan bir ana bilgisayar, bir sunucuyu yine de raporlamaya geri alabilir.

GRAFANA_USAGE_STATS_ENDPOINT hedefi değiştirir. Bu bir devre dışı bırakma değildir.

Tam alan listesi, asla gönderilmeyenler, verilerin nasıl okunacağı ve sınırlamaları için bkz. Anonim kullanım istatistikleri.

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şkenleriyle yapılandırılır ve her aktarım türüyle çalışır.

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

Metrikler

SSE veya akışkan HTTP aktarımları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:

Metrik	Tür	Açıklama
`mcp_server_operation_duration_seconds`	Histogram	MCP işlemlerinin süresi (etiketler: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histogram	MCP istemci oturumlarının süresi (etiketler: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histogram	HTTP sunucu isteklerinin süresi (otelhttp'tan)

Not: Metrikler yalnızca SSE veya akışkan HTTP aktarımları kullanılırken kullanılabilir. stdio aktarımıyla kullanılamazlar.

Loki maliyet koruması (--loki-guardrail-mode) etkinleştirildiğinde, dört sayaç daha kararlarını kaydeder:

Metrik	Tür	Açıklama
`mcp_loki_guardrail_admitted_total`	Sayaç	Etkinleştirilen her denetimden geçen sorgular (etiketler: `backend`)
`mcp_loki_guardrail_would_block_total`	Sayaç	`shadow` modunda bir denetimde başarısız olan ve yine de çalışan sorgular (etiketler: `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Sayaç	`enforce` modunda reddedilen sorgular (etiketler: `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Sayaç	Korumasının değerlendiremediği ve kabul ettiği sorgular (etiketler: `backend`, `cause`)

reason şunlardan biridir: selector, range, bytes; cause şunlardan biridir: unparseable, estimate_failed; backend şunlardan biridir: loki, victorialogs, unknown. Birden çok denetimi tetikleyen bir sorgu bir kez sayılır ve ilk çalışan denetimle etiketlenir (selector, ardından range, ardından bytes), böylece dört sayaç korumalı popülasyonu böler. Bir shadow → enforce dağıtımı sırasında bunların nasıl okunacağı için Gözlemlenebilirlik bölümüne bakın.

Kütüphane gömmecileri GrafanaConfig.MeterProvider'ü ayarlamalıdır (GrafanaConfig.Logger'in metrik karşılığı): koruma, bir araç işleyicisinin içinde çalışır, bu nedenle yapıcı seçeneği yoktur ve noop genel MeterProvider kuran bir süreç, aksi takdirde her kaydı düşürür.

Yavaş istek günlüğü

--slow-request-threshold bayrağı, bir MCP isteği (araç çağrısı, listeleme, kaynak okuma vb.) verilen 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:

Öznitelik	Açıklama
`mcp.method`	MCP yöntemi (örn., `tools/call`, `tools/list`, `resources/read`)
`duration`	Gözlemlenen istek süresi
`threshold`	Yapılandırılmış eşik
`tool`	Araç 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 düzey hata sarmalama tarafından kontrol edilir)
`error.type`	Sınırlı kardinaliteli hata sınıflandırması (türsüz hatalar için `_OTHER`)

Yavaş istek günlüğü tüm aktarımlarda (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şkenleriyle 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 öznitelikleri 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'i 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; bu nedenle 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 (örn. arka uç LogsService'i desteklemiyorsa), şunu ayarlayın:

OTEL_LOGS_EXPORTER=none

Bu, uç nokta yapılandırmasından bağımsız olarak sunucunun 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ı önler.

OTLP günlüğü etkinleştirildiğinde stderr günlüğü değişmez; kapsayıcı günlüklerine güvenmeye devam edebilir veya isterseniz stderr'i /dev/null'ye 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

Aktarım OTLP/gRPC'dir (varsayılan bağlantı noktası 4317). Günlükler, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT'ü (veya genel OTEL_EXPORTER_OTLP_ENDPOINT) uzak gRPC uç noktasına yönlendirerek ve OTEL_EXPORTER_OTLP_LOGS_HEADERS (veya OTEL_EXPORTER_OTLP_HEADERS) aracılığıyla kimlik doğrulaması sağlayarak, 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 kullanışlıdır, ancak gerekli 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ı belirtimine bakın.

Yapılandırılan toplayıcıya ulaşılamıyorsa, 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 aktarımı altında da 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

Loki sorgu zorunluluğu

--loki-enforced-matchers, bir operatörün sunucunun okuyabileceği Loki günlük akışlarını kısıtlamasını sağlar; sunucunun yayınladığı her yerel-Loki sorgusuna sabit bir LogQL etiket eşleştirici kümesini AND'leyerek. Bu, bir veri kaynağı açığa çıkarılmaması gereken akışlar içerdiğinde (örn. hassas bilgiler taşıyabilecek günlükler) ancak Grafana veya Loki katmanında erişimi kısıtlayamadığınızda kullanışlıdır (OSS'de veri kaynağı başına veya kullanıcı başına etiket erişim kontrolü yoktur).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Nasıl çalışır:

Eşleştiriciler başlangıçta bir kez ayrıştırılır (geçersiz girdi sunucuyu durdurur) ve her sorgudaki her akış seçiciye eklenir. Loki, bir seçici içindeki eşleştiricileri AND'lediğinden, bir kullanıcı sorgusu sonuçları yalnızca zorunlu sınırlar içinde daraltabilir — asla genişletemez. Politikayla çelişen bir kullanıcı seçici (örn. bir hariç tutma altında {namespace="vault"} istemek) yalnızca hiçbir şey döndürmez.
query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names ve list_loki_label_values'yi kapsar.
Kapalı başarısız olur: ayrıştırılamayan herhangi bir sorgu, filtrelenmemiş gönderilmek yerine reddedilir.
VictoriaLogs veri kaynakları, güvenli bir şekilde yeniden yazılamayan LogsQL kullanır; bu nedenle zorunluluk etkinken tamamen reddedilirler.
Yalnızca negatif eşleştiriciler, etiket numaralandırma uç noktalarını kapsayamaz (Loki, pozitif eşleştiricisi olmayan bağımsız bir seçiciyi reddeder). Bu uç durumu --loki-label-enumeration-fallback ile kontrol edin (varsayılan olarak reject veya etiket meta verilerinin kapsam dışı numaralandırmasına izin vermek için unfiltered — günlük satırları asla açığa çıkarılmaz). Pozitif/izin listesi eşleştiricileri etkilenmez.

[!ÖNEMLİ] Zorunluluk yalnızca Loki sorgu araçlarına uygulanır. Diğer araçlar, zorunlu arka uca asla dokunmayan yollardan Loki günlük verilerine ulaşabilir; bu nedenle kısıtlamanın gerçekten geçerli olması için bunları da devre dışı bırakmalısınız:

--disable-api — grafana_api_request, Loki veri kaynağı proxy'sini doğrudan sorgulayabilir (tam baypas).

--disable-rendering — get_panel_image, Loki panellerini sunucu tarafında işleyerek kısıtlanmamış günlük satırları içeren görüntüler üretir.

--disable-sift — Sift araştırmaları, Loki günlüklerini tüm akışlarda sunucu tarafında analiz eder.

--disable-assistant — ask_assistant, tüm akışlarda Loki'yi sunucu tarafında okuyan Grafana Assistant'a devreder. Yalnızca yazma araçları etkinken kaydedilir; bu nedenle --disable-write onu da kapatır.

Sunucu, başlangıçta hâlâ etkin olan bu araçların her birini adlandıran bir uyarı günlüğe kaydeder. run_panel_query güvenlidir (zorunlu sorgu yolunu yeniden kullanır). Tempo araçları izlemeleri sorgular, Loki günlüklerini değil; bu nedenle baypas değildirler. Pano anlık görüntüleri (--disable-snapshot), zorunluluk dışında yakalanan günlük paneli verilerini de gömmektedir.

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ıldı ve veri kaynağı işlemleri önceki 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! Lütfen önce CONTRIBUTING.md dosyasını okuyun — bu sunucuda neyin yer alması gerektiğini ve nasıl önerileceğini kapsar. Eğer yeni bir araç ekliyorsanız, lütfen kodu yazmadan önce bir araç önerisi açın. Varsayılan olarak açık olan her araç, her istekte her kullanıcı tarafından modele gönderilir; bu yüzden tamamlanmış bir pull request'i reddetmek yerine fikri tartışmayı tercih ederiz. Hata düzeltmeleri, dokümantasyon, testler ve mevcut araçlara eklenen yeni parametreler için öneri gerekmez — sadece bir PR gönderin.

Bu proje Go ile yazılmıştır. Go'yu platformunuz için verilen talimatlara göre kurun.

Sunucuyu yerel olarak STDIO modunda çalıştırmak için (yerel geliştirme için varsayılan mod budur), ş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şımacılığı ile de çalıştırabilirsiniz. Yayınlanan Docker imajı gibi, bu özel imajın giriş noktası da varsayılan olarak SSE moduna ayarlıdı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 ayarını geçersiz kılın:

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

Test Etme

Üç tür test mevcuttur:

Birim Testleri (harici bağımlılık gerektirmez):

make test-unit

Birim testlerini şu şekilde de çalıştırabilirsiniz:

make test

Entegrasyon Testleri (docker konteynerlerinin çalışır durumda olmasını gerektirir):

make test-integration

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, yerel olarak 3000 portunda çalışan bir Grafana örneği gerektirir; Docker Compose ile bir tane başlatabilirsiniz:

docker-compose up -d

Entegrasyon testleri şu şekilde ç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 struct etiketlerinde kaçışsız virgülleri kontrol eden özel bir linter içerir. description alanlarındaki virgüller, sessiz kesilmeyi önlemek için \\, ile kaçışlanmalıdır. Bu linter'ı tek başına şu şekilde çalıştırabilirsiniz:

make lint-jsonschema

Daha fazla ayrıntı için JSONSchema Linter dokümantasyonuna bakın.

Lisans

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