Grafana MCP sunucusu

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

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

Hızlı Başlangıç

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

{
  "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 örneğinizin URL'si ile değiştirin (örn. https://myinstance.grafana.net). Docker, binary ve Helm dahil daha fazla kurulum seçeneği için Kullanım bölümüne bakın.

Gereksinimler

• Grafana sürüm 9.0 veya üstü tam işlevsellik için gereklidir. Bazı özellikler, özellikle veri kaynağı ile ilgili işlemler, eksik API endpoint'leri nedeniyle önceki sürümlerle düzgün çalışmayabilir.

Özellikler

Aşağıdaki özellikler şu anda MCP sunucusunda mevcuttur. Bu liste yalnızca bilgi amaçlıdır ve gelecekteki özellikler hakkında bir yol haritası veya taahhüt oluşturmaz.

Panolar

• Panolar arayın: Başlık veya diğer meta verilere göre panoları bulun
• Panoyu UID ile alın: Benzersiz tanımlayıcıyı kullanarak tam pano ayrıntılarını alın. Uyarı: Büyük panolar önemli ölçüde kontekst penceresi alanı tüketebilir.
• Pano özetini alın: Başlık, panel sayısı, panel türleri, değişkenler ve meta veri dahil olmak üzere tam JSON olmadan pano hakkında kompakt bir genel bakış elde edin ve kontekst penceresi kullanımını en aza indirin
• Pano özelliğini alın: JSONPath ifadelerini kullanarak pano parçalarını çıkarın (örn. $.title, $.panels[*].title) yalnızca gerekli verileri alın ve kontekst penceresi tüketimini azaltın
• Panoyu güncelleyin veya oluşturun: Mevcut panoları değiştirin veya yenilerini oluşturun. Uyarı: Tam pano JSON gerekli olup büyük miktarda kontekst penceresi alanı tüketebilir.
• Panoyu yamalayın: Tam JSON gerektirmeden pano üzerinde belirli değişiklikleri uygulayın, hedeflenen değişiklikler için kontekst penceresi kullanımını önemli ölçüde azaltın
• Panel sorguları ve veri kaynağı bilgisini alın: Bir panodaki her panelden başlık, sorgu dizesi ve veri kaynağı bilgilerini (UID ve tür dahil, varsa) 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 runpanelquery değerini --enabled-tools bayrağına ekleyin.

• Panel sorgusu çalıştırın: Pano panelinin sorgusu özel zaman aralıkları ve değişken geçersiz kılmaları ile çalıştırın.

Kontekst Penceresi Yönetimi

Pano araçları artık kontekst penceresi kullanımını etkili bir şekilde yönetmek için birkaç strateji içerir (issue #101):

• Pano genel bakışı ve değişiklik planlaması için get_dashboard_summary kullanın
• Yalnızca belirli pano parçalarına ihtiyaç duyduğunuzda get_dashboard_property öğesini JSONPath ile kullanın
• get_dashboard_by_uid kullanmaktan kaçının tam pano JSON'ı özellikle gerekli olmadığı sürece

Veri Kaynakları

• Veri kaynağı bilgilerini listeleyin ve alın: Yapılandırılan tüm veri kaynaklarını görüntüleyin ve her biri hakkında ayrıntılı bilgiler 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 examples değerini --enabled-tools bayrağına ekleyin.

• Sorgu örneklerini alın: Sorgu söz dizimini öğrenmek için farklı veri kaynağı türleri için örnek sorguları alın.

Prometheus Sorgulaması

• Prometheus sorgula: PromQL sorgularını (hem anında hem de aralık metrik sorguları destekler) Prometheus veri kaynakları arasında çalıştırın.
• Prometheus meta verilerini sorgula: Prometheus veri kaynaklarından metrik meta verileri, metrik adları, etiket adları ve etiket değerlerini alın.
• Histogram yüzdelikleri sorgula: histogram_quantile kullanarak histogram yüzdelik değerlerini (p50, p90, p95, p99) hesaplayın.

Loki Sorgulaması

• Loki günlüklerini ve metriklerini sorgula: Loki veri kaynakları arasında LogQL kullanarak hem günlük sorguları hem de metrik sorguları çalıştırın.
• Loki meta verilerini sorgula: Loki veri kaynaklarından etiket adları, etiket değerleri ve akış istatistiklerini alın.
• Loki desenlerini sorgula: Ortak günlük yapılarını ve anormalliklerini tanımlamak için Loki tarafından tespit edilen günlük desenleri alın.

InfluxDB Sorgulaması

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

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

ClickHouse Sorgulaması

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

• ClickHouse tablolarını listeleyin: Bir ClickHouse veritabanındaki tüm tabloları satır sayıları ve boyutları ile listeleyin.
• Tablo şemasını tanımlayın: Bir ClickHouse tablosu için sütun adları, türleri ve meta verileri alın.
• ClickHouse sorgula: Grafana makro ve değişken ikame desteği ile SQL sorguları çalıştırın.

CloudWatch Sorgulaması

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

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

Graphite Sorgulaması

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

• Graphite sorgula: Graphite render API sorgularını Graphite veri kaynağı arasında çalıştırın.
• Graphite metriklerini listeleyin: Graphite metrik yollarını göz atın ve keşfedin.
• Graphite etiketlerini listeleyin: 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.

Athena Sorgulaması

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

• Athena kataloglarını listeleyin: Kullanılabilir veri kataloglarını (örn. AwsDataCatalog, Iceberg bağlayıcıları) keşfedin.
• Athena veritabanlarını listeleyin: Bir Athena kataloğunda veritabanları listeleyin.
• Athena tablolarını listeleyin: Bir Athena veritabanında tabloları listeleyin.
• Athena tablosunu tanımlayın: Bir Athena tablosu için sütun adlarını alın.
• Athena sorgula: Makro ikame, limit zorlama ve şablon değişkeni desteği ile Grafana aracılığıyla Amazon Athena arasında SQL sorguları çalıştırın.

Snowflake Sorgulaması

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

Sorgular Grafana'nın Snowflake veri kaynağı (Grafana Enterprise eklentisi grafana-snowflake-datasource) aracılığıyla gider, bu nedenle kimlik doğrulama Grafana'da veri kaynağı yapılandırması tarafından yönetilir — kimlik bilgileri hiçbir zaman MCP sunucusu tarafından görülmez. Bu, ClickHouse araçları için kullanılan model ile aynıdır.

• Snowflake tablolarını listeleyin: INFORMATION_SCHEMA.TABLES aracılığıyla tabloları keşfedin (veritabanı, şema, tür, satır sayısı ve boyut dahil). İsteğe bağlı veritabanı/şema filtreleri.
• Tablo şemasını tanımlayın: Bir Snowflake tablosu için sütun adları, veri türleri, null olabilirlik, varsayılanlar ve açıklamaları alın.
• Snowflake sorgula: Makro ve değişken ikame desteği ile SQL sorguları çalıştırın. Snowflake'in olay tablolarını (örn. SNOWFLAKE.TELEMETRY.EVENTS) günlükler ve izler için sorgulamak veya herhangi bir kullanıcı tablosunu sorgulamak için kullanışlı.
  • Desteklenen makrolar: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (saniye), $__interval_ms ve ${varname} şablon değişkeni ikamesi için.

Elasticsearch/OpenSearch Sorgulaması

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

• Elasticsearch/OpenSearch sorgula: Lucene sorgu söz dizimini veya Elasticsearch Query DSL kullanarak Elasticsearch veya OpenSearch veri kaynakları arasında arama sorguları çalıştırın. Zaman aralığına göre filtrelemeyi ve günlükleri, metrikleri veya herhangi bir dizinlenmiş veriyi almayı destekler. Dizin, ID, kaynak alanları ve isteğe bağlı ilgi puanı ile belgeleri döndürür.

Olaylar

• Olayları ara, oluşturun ve güncelleyin: Grafana Incident'te olayları yönetin, arayın, oluşturun ve etkinlikler ekleyin.

Sift Araştırmaları

• Sift araştırmalarını listeleyin: Sift araştırmalarının listesini alın, limit parametresi desteği ile.
• Sift araştırması alın: UUID'sine göre belirli bir Sift araştırması alın.
• Sift analizlerini alın: Bir Sift araştırmasından belirli bir analizi alın.
• Günlüklerdeki hata modellerini bulun: Sift kullanarak Loki günlüklerinde yükseltilmiş hata modellerini tespit edin.
• Yavaş istekleri bulun: Sift'i kullanarak yavaş istekleri tespit edin (Tempo).

Uyarı Verme

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

Grafana OnCall

• Çizelgeleri listeleyin ve yönetin: Grafana OnCall'da nöbetçi çizelgelerini görüntüleyin ve yönetin.
• Vardiya ayrıntılarını alın: Belirli nöbetçi vardiyaları hakkında ayrıntılı bilgiler alın.
• Mevcut nöbetçi kullanıcılarını alın: Bir çizelge için şu anda nöbetçi olan kullanıcıları görün.
• Takımları ve kullanıcıları listeleyin: Tüm OnCall takımlarını ve kullanıcılarını görüntüleyin.
• Uyarı gruplarını listeleyin: Grafana OnCall'dan uyarı gruplarını çeşitli kriterler (durum, entegrasyon, etiketler ve zaman aralığı) dahil olmak üzere görüntüleyin ve filtreleyin.
• Uyarı grubu ayrıntılarını alın: Belirli bir uyarı grubu hakkında ID'sine göre ayrıntılı bilgiler alın.

Yönetici

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

• Takımları listeleyin: Grafana'da yapılandırılan tüm takımları görüntüleyin.
• Kullanıcıları listeleyin: Grafana'da bir kuruluştaki tüm kullanıcıları görüntüleyin.
• Tüm rolleri listeleyin: Tüm Grafana rollerini, devredilecek roller için isteğe bağlı filtre ile listeleyin.
• Rol ayrıntılarını alın: UID'ye göre belirli bir Grafana rolü ayrıntılarını alın.
• Bir rol için atamalar listeleyin: Bir role atanan tüm kullanıcıları, takımları ve hizmet hesaplarını listeleyin.
• Kullanıcılar için rolleri listeleyin: Bir veya daha fazla kullanıcıya atanan tüm rolleri listeleyin.
• Takımlar için rolleri listeleyin: Bir veya daha fazla takıma atanan tüm rolleri listeleyin.
• Kaynak için izinleri listeleyin: Belirli bir kaynak (pano, veri kaynağı, klasör vb.) için tanımlanan tüm izinleri listeleyin.
• Grafana kaynağını tanımlayın: Bir kaynak türü için kullanılabilir izinleri ve atama yeteneklerini listeleyin.

Gezinti

• Derin bağlantılar oluşturun: LLM URL tahminine güvenmek yerine Grafana kaynakları için doğru derin bağlantı URL'leri oluşturun.
  • 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 parametresi ile pano içindeki belirli panellere bağlantılar oluşturun (örn. http://localhost:3000/d/dashboard-uid?viewPanel=5)
  • Explore bağlantıları: Önceden yapılandırılan veri kaynakları ile Grafana Explore bağlantıları oluşturun (örn. http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
  • Zaman aralığı desteği: Bağlantılara zaman aralığı parametreleri ekleyin (from=now-1h&to=now)
  • Özel parametreler: Pano değişkenleri veya yenileme aralıkları gibi ek sorgu parametrelerini ekleyin

Ek Açıklamalar

• Ek Açıklamaları Alın: Filtreler ile ek açıklamaları sorgulayın. Zaman aralığı, pano UID, etiketler ve eşleşme modunu destekler.
• Ek Açıklama Oluşturun: Bir pano veya panelde yeni bir ek açıklama oluşturun.
• Graphite Ek Açıklaması Oluşturun: Graphite formatı (what, when, tags, data) kullanarak ek açıklamalar oluşturun.
• Ek Açıklamayı Güncelleyin: Mevcut bir ek açıklamanın tüm alanlarını değiştirin (tam güncelleme).
• Ek Açıklamayı Yamalayın: Bir ek açıklamanın yalnızca belirli alanlarını güncelleyin (kısmi güncelleme).
• Ek Açıklama Etiketlerini Alın: Mevcut ek açıklama etiketlerini isteğe bağlı filtreleme ile listeleyin.

Render Etme

• Panel veya pano görüntüsü alın: Grafana pano panelini veya tam panoyu PNG görüntüsü olarak render edin. Raporlar, uyarılar veya sunumlar için kullanmak üzere görüntüyü base64 kodlanmış veri olarak döndürür. Boyutları, zaman aralığı, temayı, ölçeği ve pano değişkenlerini özelleştirmeyi destekler.
  • Not: Grafana Image Renderer hizmetinin kurulu ve yapılandırılmış olması gerekir.

Araçlar listesi yapılandırılabilir, bu nedenle MCP istemcisine hangi araçları kullanılabilir hale getirmek istediğinizi seçebilirsiniz. Bu, belirli işlevselliği kullanmıyorsanız veya kontekst penceresinin çok fazla alanını kaplayacağını istemiyorsanız yararlıdır. Bir araç kategorisini devre dışı bırakmak için sunucu başlatırken --disable-<category> bayrağını kullanın. Örneğin, OnCall araçlarını devre dışı bırakmak için --disable-oncall değerini, veya gezinti derin bağlantı oluşturmayı devre dışı bırakmak için --disable-navigation değerini kullanın.

RBAC İzinleri

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

İ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ü, MCP sunucusu işlemlerinin çoğunu işlemesine izin verecek geniş okuma/yazma erişimi sağlar; el ile uygulanan kapsamlardan daha az ayrıntılıdır (ve dolayısıyla daha az kısıtlayıcıdır), bu nedenle bunu yalnızca kolaylık en az ayrıcalık erişiminden daha önemli olduğunda kullanın.

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

• Viewer rolü: Salt okunur işlemler için gereklidir (olayları listeleyin, araştırmaları alın)
• Editor rolü: Yazma işlemleri için gereklidir (olayları oluşturun, araştırmaları değiştirin)

Grafana RBAC hakkında daha fazla bilgi için resmi belgelendirme sayfasına bakın.

RBAC Kapsamları

Kapsamlar, izinlerin geçerli olduğu belirli kaynakları tanımlar. Her eylem hem uygun izin hem de kapsam kombinasyonu gerektirir.

Yaygın Kapsam Desenleri:

• Geniş erişim: Kuruluş çapında erişim için * joker kartlarını 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 takımlara erişim

• Sınırlı erişim: Erişimi ayrı kaynaklar ile sınırlamak için belirli UID'ler veya ID'ler kullanın

  • datasources:uid:prometheus-uid - Yalnızca belirli bir Prometheus veri kaynağına erişim
  • dashboards:uid:abc123 - UID abc123 olan panoye yalnızca erişim
  • folders:uid:xyz789 - UID xyz789 olan klasöre yalnızca erişim
  • teams:id:5 - ID 5 olan takıma yalnızca erişim
  • global.users:id:123 - ID 123 olan kullanıcıya yalnızca erişim

Örnekler:

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

  datasources:* (datasources:read, datasources:query)
  dashboards:* (dashboards:read, dashboards:create, dashboards:write)
  folders:* (pano oluşturma ve uyarı kuralları için)
  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)
  

• Pano özel erişimi: 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	Admin	Tüm takımları listeleyin	teams:read	teams:* veya teams:id:1
list_users_by_org	Admin	Bir kuruluştaki tüm kullanıcıları listeleyin	users:read	global.users:* veya global.users:id:123
list_all_roles	Admin	Tüm Grafana rollerini listeleyin	roles:read	roles:*
get_role_details	Admin	Bir Grafana rolü ayrıntılarını alın	roles:read	roles:uid:editor
get_role_assignments	Admin	Bir rol için atamalar listeleyin	roles:read	roles:uid:editor
list_user_roles	Admin	Kullanıcılar için rolleri listeleyin	roles:read	global.users:id:123
list_team_roles	Admin	Takımlar için roll