Grafana

resmi

Cari dasbor, selidiki insiden, dan kueri sumber data di instance Grafana Anda

GitHub
3.4k

Apa yang bisa Anda lakukan dengan Grafana MCP?

  • Cari dan periksa dasbor — Gunakan search_dashboards dan get_dashboard_summary untuk menemukan dasbor dan mendapatkan ringkasan ringkas tanpa JSON lengkap.
  • Kueri Prometheus dan Loki — Jalankan kueri PromQL dan LogQL terhadap sumber data Anda, termasuk metadata dan persentil histogram.
  • Kelola alerting — Daftarkan, buat, perbarui, dan hapus aturan alert, serta lihat kebijakan notifikasi dan titik kontak.
  • Buat deeplink — Buat URL yang akurat ke dasbor, panel, dan Explore dengan rentang waktu melalui alat navigasi.
  • Jalankan kueri panel — Jalankan kueri panel dasbor dengan rentang waktu dan variabel kustom menggunakan run_panel_query.

Dokumentasi

Server MCP Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Server Model Context Protocol (MCP) untuk Grafana.

Ini menyediakan akses ke instance Grafana Anda dan ekosistem di sekitarnya.

Memulai Cepat

Membutuhkan uv. Tambahkan berikut ini ke konfigurasi klien MCP Anda (misalnya Claude Desktop, Cursor):

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

Untuk Grafana Cloud, ganti GRAFANA_URL dengan URL instance Anda (misalnya https://myinstance.grafana.net). Lihat Penggunaan untuk opsi instalasi lainnya termasuk Docker, biner, dan Helm.

Persyaratan

  • Grafana versi 9.0 atau lebih baru diperlukan untuk fungsionalitas penuh. Beberapa fitur, terutama operasi terkait sumber data, mungkin tidak berfungsi dengan benar pada versi sebelumnya karena titik akhir API yang tidak tersedia.

Fitur

Fitur-fitur berikut saat ini tersedia di server MCP. Daftar ini hanya untuk tujuan informasi dan tidak mewakili peta jalan atau komitmen terhadap fitur-fitur di masa mendatang.

Dasbor

  • Cari dasbor: Temukan dasbor berdasarkan judul atau metadata lainnya
  • Dapatkan dasbor berdasarkan UID: Ambil detail dasbor lengkap menggunakan pengidentifikasi uniknya. Peringatan: Dasbor besar dapat menghabiskan ruang jendela konteks yang signifikan.
  • Dapatkan ringkasan dasbor: Dapatkan gambaran ringkas tentang dasbor termasuk judul, jumlah panel, jenis panel, variabel, dan metadata tanpa JSON lengkap untuk meminimalkan penggunaan jendela konteks
  • Dapatkan properti dasbor: Ekstrak bagian-bagian tertentu dari dasbor menggunakan ekspresi JSONPath (misalnya, $.title, $.panels[*].title) untuk mengambil hanya data yang diperlukan dan mengurangi konsumsi jendela konteks
  • Perbarui atau buat dasbor: Ubah dasbor yang ada atau buat yang baru. Peringatan: Membutuhkan JSON dasbor lengkap yang dapat menghabiskan banyak ruang jendela konteks.
  • Tambal dasbor: Terapkan perubahan spesifik pada dasbor tanpa memerlukan JSON lengkap, secara signifikan mengurangi penggunaan jendela konteks untuk modifikasi yang ditargetkan
  • Dapatkan kueri panel dan info sumber data: Dapatkan judul, string kueri, dan informasi sumber data (termasuk UID dan tipe, jika tersedia) dari setiap panel dalam dasbor

Jalankan Kueri Panel

Catatan: Alat kueri panel berjalan dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan runpanelquery ke flag --enabled-tools Anda.

  • Jalankan kueri panel: Jalankan kueri panel dasbor dengan rentang waktu kustom dan pengesampingan variabel.

Manajemen Jendela Konteks

Alat dasbor kini menyertakan beberapa strategi untuk mengelola penggunaan jendela konteks secara efektif (masalah #101):

  • Gunakan get_dashboard_summary untuk ringkasan dasbor dan perencanaan modifikasi
  • Gunakan get_dashboard_property dengan JSONPath ketika Anda hanya memerlukan bagian dasbor tertentu
  • Hindari get_dashboard_by_uid kecuali Anda benar-benar memerlukan JSON dasbor lengkap

Sumber Data

  • Daftar dan ambil informasi sumber data: Lihat semua sumber data yang dikonfigurasi dan ambil informasi terperinci tentang masing-masing.
    • Jenis sumber data yang didukung: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Contoh Kueri

Catatan: Alat contoh kueri dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan examples ke flag --enabled-tools Anda.

  • Dapatkan contoh kueri: Ambil contoh kueri untuk berbagai jenis sumber data untuk mempelajari sintaks kueri.

Kueri Prometheus

  • Kueri Prometheus: Jalankan kueri PromQL (mendukung kueri metrik instan dan rentang) terhadap sumber data Prometheus.
  • Kueri metadata Prometheus: Ambil metadata metrik, nama metrik, nama label, dan nilai label dari sumber data Prometheus.
  • Kueri persentil histogram: Hitung nilai persentil histogram (p50, p90, p95, p99) menggunakan histogram_quantile.

Kueri Loki

  • Kueri log dan metrik Loki: Jalankan kueri log dan kueri metrik menggunakan LogQL terhadap sumber data Loki.
  • Kueri metadata Loki: Ambil nama label, nilai label, dan statistik aliran dari sumber data Loki.
  • Kueri pola Loki: Ambil pola log yang terdeteksi oleh Loki untuk mengidentifikasi struktur log umum dan anomali.

Kueri InfluxDB

Catatan: Alat InfluxDB dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan influxdb ke flag --enabled-tools Anda.

  • Kueri InfluxDB: Jalankan kueri terhadap sumber data InfluxDB menggunakan InfluxQL (v1.x) atau Flux (v2.x). Dialek disimpulkan dari konfigurasi sumber data, atau dapat diatur secara eksplisit melalui parameter dialect.

Kueri ClickHouse

Catatan: Alat ClickHouse dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan clickhouse ke flag --enabled-tools Anda.

  • Daftar tabel ClickHouse: Daftar semua tabel dalam database ClickHouse dengan jumlah baris dan ukuran.
  • Jelaskan skema tabel: Dapatkan nama kolom, tipe, dan metadata untuk tabel ClickHouse.
  • Kueri ClickHouse: Jalankan kueri SQL dengan dukungan substitusi makro dan variabel Grafana.

Kueri CloudWatch

Catatan: Alat CloudWatch dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan cloudwatch ke flag --enabled-tools Anda.

  • Daftar namespace CloudWatch: Temukan namespace AWS CloudWatch yang tersedia.
  • Daftar metrik CloudWatch: Daftar metrik yang tersedia dalam namespace tertentu.
  • Daftar dimensi CloudWatch: Dapatkan dimensi untuk memfilter kueri metrik.
  • Kueri CloudWatch: Jalankan kueri metrik CloudWatch dengan dukungan rentang waktu.

Kueri Graphite

Catatan: Alat Graphite dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan graphite ke flag --enabled-tools Anda.

  • Kueri Graphite: Jalankan kueri API render Graphite terhadap sumber data Graphite.
  • Daftar metrik Graphite: Jelajahi dan temukan jalur metrik Graphite.
  • Daftar tag Graphite: Daftar tag Graphite yang tersedia dan nilai tag.
  • Kueri kepadatan Graphite: Kueri kepadatan metrik Graphite untuk pola tertentu.

Kueri Athena

Catatan: Alat Athena dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan athena ke flag --enabled-tools Anda.

  • Daftar katalog Athena: Temukan katalog data yang tersedia (misalnya AwsDataCatalog, konektor Iceberg).
  • Daftar database Athena: Daftar database dalam katalog Athena.
  • Daftar tabel Athena: Daftar tabel dalam database Athena.
  • Jelaskan tabel Athena: Dapatkan nama kolom untuk tabel Athena.
  • Kueri Athena: Jalankan kueri SQL terhadap Amazon Athena melalui Grafana dengan substitusi makro, penegakan batas, dan dukungan variabel templat.

Kueri Snowflake

Catatan: Alat Snowflake dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan snowflake ke flag --enabled-tools Anda.

Kueri berjalan melalui sumber data Snowflake Grafana (plugin Grafana Enterprise grafana-snowflake-datasource), sehingga autentikasi ditangani oleh konfigurasi sumber data di Grafana — kredensial tidak pernah terlihat oleh server MCP. Ini adalah model yang sama yang digunakan untuk alat ClickHouse.

  • Daftar tabel Snowflake: Temukan tabel (dengan database, skema, jenis, jumlah baris, dan ukuran) melalui INFORMATION_SCHEMA.TABLES. Filter database/skema opsional.
  • Jelaskan skema tabel: Dapatkan nama kolom, tipe data, kemampuan null, nilai default, dan komentar untuk tabel Snowflake.
  • Kueri Snowflake: Jalankan kueri SQL dengan dukungan substitusi makro dan variabel. Berguna untuk mengkueri tabel peristiwa Snowflake (misalnya SNOWFLAKE.TELEMETRY.EVENTS) untuk log dan jejak, atau tabel pengguna apa pun.
    • Makro yang didukung: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (ms Unix), $__interval (detik), $__interval_ms, dan ${varname} untuk substitusi variabel templat.

Kueri Elasticsearch/OpenSearch

Catatan: Alat Elasticsearch/OpenSearch dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan elasticsearch ke flag --enabled-tools Anda.

  • Kueri Elasticsearch/OpenSearch: Jalankan kueri pencarian terhadap sumber data Elasticsearch atau OpenSearch menggunakan sintaks kueri Lucene atau Elasticsearch Query DSL. Mendukung pemfilteran berdasarkan rentang waktu dan pengambilan log, metrik, atau data terindeks apa pun. Mengembalikan dokumen dengan indeks, ID, bidang sumber, dan skor relevansi opsional.

Kueri Quickwit

Catatan: Alat Quickwit dinonaktifkan secara default. Untuk mengaktifkannya, tambahkan quickwit ke flag --enabled-tools Anda.

  • Kueri Quickwit: Jalankan kueri pencarian terhadap sumber data Quickwit menggunakan sintaks kueri Lucene atau sebagian Query DSL yang kompatibel dengan Elasticsearch. Mendukung pemfilteran berdasarkan rentang waktu dan pengambilan log atau dokumen terindeks lainnya. Mengembalikan dokumen dengan indeks, ID, bidang sumber, dan skor relevansi opsional.

Observabilitas Agen

Catatan: Alat Observabilitas Agen dinonaktifkan secara default dan hanya berfungsi di Grafana Cloud. Untuk mengaktifkannya, tambahkan agento11y ke flag --enabled-tools Anda.

  • Daftar dan cari percakapan: Daftar percakapan LLM terbaru atau cari dengan ekspresi filter (model, penyedia, agen, status, jenis kesalahan, hasil evaluasi, dan lainnya) dalam rentang waktu. Hasil pencarian mencakup jumlah kesalahan, ringkasan peringkat, ringkasan evaluasi, dan ID jejak.
  • Dapatkan detail percakapan: Ambil satu percakapan dengan semua generasinya, termasuk prompt dan keluaran.
  • Dapatkan detail dan skor generasi: Ambil satu generasi berdasarkan ID, dan skor evaluasinya (evaluator, kunci skor, nilai, lulus, penjelasan).
  • Baca katalog agen: Daftar agen yang mengirim telemetri, ambil satu versi agen secara lengkap (prompt sistem lengkap, setiap alat dengan skema JSON-nya, dan model yang dijalankannya), telusuri riwayat versi agen, dan bandingkan agregat skor evaluasi per versi. Versi efektif adalah hash sha256: yang tidak pernah terpengaruh oleh perubahan alat; untuk agen yang tidak melaporkan versinya sendiri, hash tersebut menggunakan prompt sistem, sehingga pengeditan prompt menghasilkan versi baru. Baris katalog dan versi membawa token_estimate, yang layak diperiksa sebelum mengambil prompt lengkap.
  • Periksa evaluator dan templat: Baca evaluator asal skor, templat asal evaluator tersebut, serta penyedia dan model juri yang tersedia untuk evaluator juri LLM. Dengan alat tulis diaktifkan, juga buat, fork, uji, dan hapus evaluator.
  • Periksa aturan eval dan penjaga: Baca aturan eval asinkron yang mengikat evaluator ke lalu lintas produksi, dan penjaga (aturan hook) yang berjalan inline dan dapat memperingatkan atau menolak. Dengan alat tulis diaktifkan, juga buat, perbarui, pratinjau, dan hapus. Operasi tulis serta operasi preview_rule dan test_evaluator yang tidak persisten memerlukan izin grafana-agento11y-app.eval:write, yang diberikan oleh peran Agento11y Admin.
  • Kurasi percakapan dan koleksi tersimpan: Baca percakapan tersimpan (penanda yang memberikan ID, nama, dan tag yang stabil pada percakapan) dan koleksi yang mengelompokkannya, termasuk jumlah anggota setiap koleksi dan koleksi yang tertanam di setiap baris percakapan tersimpan. Dengan alat tulis diaktifkan, juga tandai percakapan, buat dan edit koleksi, serta tambah atau hapus anggota. Operasi tulis ini memerlukan izin grafana-agento11y-app.eval:write yang sama.
  • Baca dan edit rangkaian pengujian: Daftar rangkaian pengujian berversi yang digunakan untuk eksperimen offline, baca satu dengan riwayat versi lengkapnya, dan telusuri kasus pengujian dari sebuah versi. Dengan alat tulis diaktifkan, juga buat rangkaian, ganti nama atau beri tag ulang, buka versi draf, publikasikan, dan tulis atau hapus kasus pengujiannya. Versi yang dipublikasikan dibekukan, sehingga pengeditan berarti membuka draf baru. Operasi tulis ini memerlukan grafana-agento11y-app.eval:write.
  • Baca eksperimen offline: Daftar proses evaluasi pada rangkaian pengujian dan baca satu dengan tingkat kelulusan utama, biaya, dan total token. Telusuri laporan per kasus pengujian hingga percobaan, skornya dengan penjelasan setiap juri, dan metadata artefaknya. Dengan alat tulis diaktifkan, juga ganti nama atau beri tag ulang eksperimen dan batalkan eksperimen yang sedang berjalan, yang memerlukan grafana-agento11y-app.eval:write. Eksperimen dibuat oleh runner SDK, bukan oleh alat ini.

Asisten Grafana

Catatan: Alat asisten dinonaktifkan secara bawaan dan memerlukan plugin Grafana Assistant (grafana-assistant-app) yang terinstal pada instance Grafana target. Alat-alat ini juga merupakan alat tulis (asisten dapat mengubah status stack), sehingga dilewati saat --disable-write disetel. Untuk mengaktifkannya, tambahkan assistant ke flag --enabled-tools Anda.

  • Tanyakan pada asisten: Kirim prompt bahasa alami ke Grafana Assistant dan tunggu balasan teks lengkap. Asisten dapat menggunakan alat, metrik, log, dan konteks stack lainnya—lebih luas daripada sekadar menjalankan satu kueri sumber data yang terisolasi. Teruskan contextId yang dikembalikan dalam panggilan lanjutan untuk melanjutkan percakapan yang sama. Tugas yang kompleks dapat memakan waktu beberapa menit; panggilan akan memblokir hingga balasan selesai atau permintaan habis waktu (5 menit).

Insiden

  • Cari, buat, dan perbarui insiden: Kelola insiden di Grafana Incident, termasuk mencari, membuat, dan menambahkan aktivitas ke insiden.

Investigasi Sift

  • Daftar investigasi Sift: Ambil daftar investigasi Sift, dengan dukungan parameter limit.
  • Dapatkan investigasi Sift: Ambil detail investigasi Sift tertentu berdasarkan UUID-nya.
  • Dapatkan analisis Sift: Ambil analisis tertentu dari investigasi Sift.
  • Temukan pola kesalahan di log: Deteksi pola kesalahan yang meningkat di log Loki menggunakan Sift.
  • Temukan permintaan lambat: Deteksi permintaan lambat menggunakan Sift (Tempo).

Alerting

  • Daftar dan ambil informasi aturan alert: Lihat aturan alert dan statusnya (firing/normal/error/dll.) di Grafana. Mendukung aturan yang dikelola Grafana dan aturan yang dikelola sumber data dari sumber data Prometheus atau Loki.
  • Buat dan perbarui aturan alert: Buat aturan alert baru atau ubah aturan yang sudah ada.
  • Hapus aturan alert: Hapus aturan alert berdasarkan UID.
  • Kelola perutean alerting: Lihat kebijakan notifikasi, contact point, dan interval waktu. Mendukung contact point yang dikelola Grafana dan receiver dari sumber data Alertmanager eksternal (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

  • Daftar dan kelola jadwal: Lihat dan kelola jadwal on-call di Grafana OnCall.
  • Dapatkan detail shift: Ambil informasi terperinci tentang shift on-call tertentu.
  • Dapatkan pengguna on-call saat ini: Lihat pengguna mana yang sedang on-call untuk suatu jadwal.
  • Daftar tim dan pengguna: Lihat semua tim dan pengguna OnCall.
  • Daftar grup alert: Lihat dan filter grup alert dari Grafana OnCall berdasarkan berbagai kriteria termasuk status, integrasi, label, dan rentang waktu.
  • Dapatkan detail grup alert: Ambil informasi terperinci tentang grup alert tertentu berdasarkan ID-nya.

Admin

Catatan: Alat admin dinonaktifkan secara bawaan. Untuk mengaktifkannya, sertakan admin di flag --enabled-tools Anda.

  • Daftar tim: Lihat semua tim yang dikonfigurasi di Grafana.
  • Daftar pengguna: Lihat semua pengguna dalam organisasi di Grafana.
  • Daftar semua peran: Daftar semua peran Grafana, dengan filter opsional untuk peran yang dapat didelegasikan.
  • Dapatkan detail peran: Dapatkan detail untuk peran Grafana tertentu berdasarkan UID.
  • Daftar penugasan untuk suatu peran: Daftar semua pengguna, tim, dan akun layanan yang ditugaskan ke suatu peran.
  • Daftar peran untuk pengguna: Daftar semua peran yang ditugaskan ke satu atau lebih pengguna.
  • Daftar peran untuk tim: Daftar semua peran yang ditugaskan ke satu atau lebih tim.
  • Daftar izin untuk suatu sumber daya: Daftar semua izin yang ditentukan untuk sumber daya tertentu (dashboard, sumber data, folder, dll.).
  • Jelaskan sumber daya Grafana: Daftar izin yang tersedia dan kemampuan penugasan untuk suatu jenis sumber daya.

Navigasi

  • Buat deeplink: Buat URL deeplink yang akurat untuk sumber daya Grafana alih-alih mengandalkan tebakan URL LLM.
    • Tautan dashboard: Buat tautan langsung ke dashboard menggunakan UID-nya (mis., http://localhost:3000/d/dashboard-uid)
    • Tautan panel: Buat tautan ke panel tertentu di dalam dashboard dengan parameter viewPanel (mis., http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Tautan Explore: Buat tautan ke Grafana Explore dengan sumber data yang telah dikonfigurasi (mis., http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • Dukungan rentang waktu: Tambahkan parameter rentang waktu ke tautan (from=now-1h&to=now)
    • Parameter kustom: Sertakan parameter kueri tambahan seperti variabel dashboard atau interval penyegaran

Anotasi

  • Dapatkan Anotasi: Kueri anotasi dengan filter. Mendukung rentang waktu, UID dashboard, tag, dan mode pencocokan.
  • Buat Anotasi: Buat anotasi baru di dashboard atau panel.
  • Buat Anotasi Graphite: Buat anotasi menggunakan format Graphite (what, when, tags, data).
  • Perbarui Anotasi: Ganti semua bidang anotasi yang ada (pembaruan penuh).
  • Patch Anotasi: Perbarui hanya bidang tertentu dari anotasi (pembaruan parsial).
  • Dapatkan Tag Anotasi: Daftar tag anotasi yang tersedia dengan pemfilteran opsional.

Snapshot

  • Daftar snapshot: Daftar snapshot dashboard dengan filter kueri dan limit opsional.
  • Dapatkan snapshot: Ambil metadata snapshot dan payload dashboard berdasarkan kunci snapshot.
  • Buat snapshot: Buat snapshot dashboard dari payload dashboard lengkap, dengan opsi kedaluwarsa dan snapshot eksternal opsional.
  • Hapus snapshot: Hapus snapshot berdasarkan kunci snapshot.

Rendering

  • Dapatkan gambar panel atau dashboard: Render panel dashboard Grafana atau dashboard lengkap sebagai gambar PNG. Mengembalikan gambar sebagai data berenkode base64 untuk digunakan dalam laporan, alert, atau presentasi. Mendukung penyesuaian dimensi, rentang waktu, tema, skala, dan variabel dashboard. Juga mendukung rendering dashboard yang belum diterapkan dari cabang repositori provisioning (mis., pratinjau PR git-sync) melalui parameter provisioningPreview opsional.

Provisioning

  • Daftar repositori provisioning: Daftar repositori provisioning yang dikonfigurasi untuk instance Grafana ini (mis., sumber git-sync), mengembalikan slug setiap repositori beserta URL sumber, cabang, jalur, status sinkronisasi, dan kesehatannya.
  • Validasi file provisioning: Terapkan dry-run file dari repositori provisioning pada cabang atau commit tertentu. Mengembalikan apakah file tersebut akan diterima, tindakan sumber daya (buat/perbarui), jenis sumber daya target, dan kesalahan validasi terstruktur—permukaan penerimaan yang sama yang digunakan oleh komentator PR Grafana.

Daftar alat dapat dikonfigurasi, sehingga Anda dapat memilih alat mana yang ingin Anda sediakan untuk klien MCP. Ini berguna jika Anda tidak menggunakan fungsionalitas tertentu atau jika Anda tidak ingin menghabiskan terlalu banyak ruang di jendela konteks. Untuk menonaktifkan kategori alat, gunakan flag --disable-<category> saat memulai server. Misalnya, untuk menonaktifkan alat OnCall, gunakan --disable-oncall, atau untuk menonaktifkan pembuatan deeplink navigasi, gunakan --disable-navigation.

Izin RBAC

Setiap alat memerlukan izin RBAC tertentu agar berfungsi dengan benar. Saat membuat akun layanan untuk server MCP, pastikan akun tersebut memiliki izin yang diperlukan berdasarkan alat yang ingin Anda gunakan. Izin yang tercantum adalah tindakan minimum yang diperlukan—Anda mungkin juga memerlukan cakupan yang sesuai (mis., datasources:*, dashboards:*, folders:*) tergantung pada kasus penggunaan Anda.

Tips: Jika Anda tidak terbiasa dengan RBAC Grafana atau Anda menginginkan pengaturan yang lebih cepat dan sederhana daripada mengonfigurasi banyak cakupan granular, Anda dapat menetapkan peran bawaan seperti Editor ke akun layanan. Peran Editor memberikan akses baca/tulis yang luas yang akan memungkinkan sebagian besar operasi server MCP; peran ini kurang granular (dan karenanya kurang restriktif) daripada cakupan yang diterapkan secara manual, jadi gunakan hanya ketika kenyamanan lebih penting daripada akses hak-istimewa-minimum yang ketat.

Catatan: Alat Grafana Incident dan Sift menggunakan peran Grafana dasar alih-alih izin RBAC yang terperinci:

  • Peran Viewer: Diperlukan untuk operasi baca-saja (daftar insiden, dapatkan investigasi)
  • Peran Editor: Diperlukan untuk operasi tulis (buat insiden, ubah investigasi)

Untuk informasi lebih lanjut tentang RBAC Grafana, lihat dokumentasi resmi.

Cakupan RBAC

Cakupan menentukan sumber daya spesifik yang berlaku untuk izin. Setiap tindakan memerlukan kombinasi izin dan cakupan yang sesuai.

Pola Cakupan Umum:

  • Akses luas: Gunakan wildcard * untuk akses tingkat organisasi

    • datasources:* - Akses ke semua sumber data
    • dashboards:* - Akses ke semua dashboard
    • folders:* - Akses ke semua folder
    • teams:* - Akses ke semua tim

  • Akses terbatas: Gunakan UID atau ID spesifik untuk membatasi akses ke sumber daya individual

    • datasources:uid:prometheus-uid - Akses hanya ke sumber data Prometheus tertentu
    • dashboards:uid:abc123 - Akses hanya ke dashboard dengan UID abc123
    • folders:uid:xyz789 - Akses hanya ke folder dengan UID xyz789
    • teams:id:5 - Akses hanya ke tim dengan ID 5
    • global.users:id:123 - Akses hanya ke pengguna dengan ID 123

Contoh:

  • Akses server MCP penuh: Berikan izin luas untuk semua alat

    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)

  • Akses sumber data terbatas: Hanya kueri instance Prometheus dan Loki tertentu

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

  • Akses khusus dashboard: Hanya baca dashboard tertentu

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

Alat

ToolCategoryDescriptionRequired RBAC PermissionsRequired Scopes
list_teamsAdminDaftar semua timteams:readteams:* or teams:id:1
list_users_by_orgAdminDaftar semua pengguna dalam organisasiusers:readglobal.users:* or global.users:id:123
list_all_rolesAdminDaftar semua peran Grafanaroles:readroles:*
get_role_detailsAdminDapatkan detail untuk peran Grafanaroles:readroles:uid:editor
get_role_assignmentsAdminDaftar penugasan untuk peranroles:readroles:uid:editor
list_user_rolesAdminDaftar peran untuk penggunaroles:readglobal.users:id:123
list_team_rolesAdminDaftar peran untuk timroles:readteams:id:7
get_resource_permissionsAdminDaftar izin untuk sumber dayapermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdminJelaskan tipe sumber daya Grafanapermissions:readdashboards:*
search_dashboardsSearchCari dashboarddashboards:readdashboards:* or dashboards:uid:abc123
get_dashboard_by_uidDashboardDapatkan dashboard berdasarkan uiddashboards:readdashboards:uid:abc123
update_dashboardDashboardPerbarui atau buat dashboard barudashboards:create, dashboards:writedashboards:*, folders:* or folders:uid:xyz789
get_dashboard_panel_queriesDashboardDapatkan judul panel, kueri, UID sumber data, dan tipe dari dashboarddashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Jalankan satu atau lebih kueri panel dashboarddashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardEkstrak bagian tertentu dari dashboard menggunakan ekspresi JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboardDapatkan ringkasan ringkas dari dashboard tanpa JSON lengkapdashboards:readdashboards:uid:abc123
list_datasourcesDatasourcesDaftar sumber datadatasources:readdatasources:*
get_datasourceDatasourcesDapatkan sumber data berdasarkan UID atau namadatasources:readdatasources:uid:prometheus-uid
get_query_examplesExamples*Dapatkan contoh kueri untuk tipe sumber datadatasources:readdatasources:*
query_prometheusPrometheusJalankan kueri terhadap sumber data Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusDaftar metadata metrikdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusDaftar nama metrik yang tersediadatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusDaftar nama label yang cocok dengan pemilihdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusDaftar nilai untuk label tertentudatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusHitung nilai persentil histogramdatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentDaftar insiden di Grafana IncidentViewer roleN/A
create_incidentIncidentBuat insiden di Grafana IncidentEditor roleN/A
add_activity_to_incidentIncidentTambahkan item aktivitas ke insiden di Grafana IncidentEditor roleN/A
get_incidentIncidentDapatkan satu insiden berdasarkan IDViewer roleN/A
query_loki_logsLokiKueri dan ambil log menggunakan LogQL (kueri log atau metrik)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiDaftar semua nama label yang tersedia dalam logdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiDaftar nilai untuk label log tertentudatasources:querydatasources:uid:loki-uid
query_loki_statsLokiDapatkan statistik tentang aliran logdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiKueri pola log yang terdeteksi untuk mengidentifikasi struktur umumdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiAudit strategi label Loki (live atau statis) dan secara opsional diagnosis kinerja kueridatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfigHasilkan cuplikan Alloy loki.process yang menerapkan label yang disetujuiN/AN/A
query_influxdbInfluxDBKueri InfluxDB menggunakan InfluxQL (v1) atau Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Daftar tabel dalam basis data ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Dapatkan skema tabel dengan tipe kolomdatasources:querydatasources:uid:*
query_clickhouseClickHouse*Jalankan kueri SQL dengan substitusi makrodatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Daftar namespace AWS CloudWatch yang tersediadatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*Daftar metrik dalam namespacedatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Daftar dimensi untuk metrikdatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Jalankan kueri metrik CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Daftar katalog data Athena yang tersediadatasources:querydatasources:uid:*
list_athena_databasesAthena*Daftar database dalam katalog Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Daftar tabel dalam database Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Ambil nama kolom untuk tabel Athenadatasources:querydatasources:uid:*
query_athenaAthena*Jalankan kueri SQL dengan substitusi makrodatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Kueri Elasticsearch atau OpenSearch menggunakan sintaks Lucene atau Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Kueri Quickwit menggunakan sintaks Lucene atau Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Daftar tabel dalam database/skema Snowflake melalui INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Ambil skema tabel (tipe kolom, nullable, default, komentar)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Jalankan kueri SQL dengan substitusi makro/variabeldatasources:querydatasources:uid:*
alerting_manage_rulesAlertingKelola aturan alert (daftar, dapatkan, versi, buat, perbarui, hapus)alert.rules:read + alert.rules:write untuk mutasifolders:* atau folders:uid:alerts-folder
alerting_manage_routingAlertingKelola kebijakan notifikasi, titik kontak, dan interval waktualert.notifications:readLingkup global
list_oncall_schedulesOnCallDaftar jadwal dari Grafana OnCallgrafana-oncall-app.schedules:readLingkup khusus plugin
get_oncall_shiftOnCallDapatkan detail untuk shift OnCall tertentugrafana-oncall-app.schedules:readLingkup khusus plugin
get_current_oncall_usersOnCallDapatkan pengguna yang sedang on-call untuk jadwal tertentugrafana-oncall-app.schedules:readLingkup khusus plugin
list_oncall_teamsOnCallDaftar tim dari Grafana OnCallgrafana-oncall-app.user-settings:readLingkup khusus plugin
list_oncall_usersOnCallDaftar pengguna dari Grafana OnCallgrafana-oncall-app.user-settings:readLingkup khusus plugin
list_alert_groupsOnCallDaftar grup alert dari Grafana OnCall dengan opsi filtergrafana-oncall-app.alert-groups:readLingkup khusus plugin
get_alert_groupOnCallDapatkan grup alert tertentu dari Grafana OnCall berdasarkan ID-nyagrafana-oncall-app.alert-groups:readLingkup khusus plugin
get_sift_investigationSiftAmbil investigasi Sift yang ada berdasarkan UUID-nyaPeran PenontonN/A
get_sift_analysisSiftAmbil analisis tertentu dari investigasi SiftPeran PenontonN/A
list_sift_investigationsSiftAmbil daftar investigasi Sift dengan batas opsionalPeran PenontonN/A
find_error_pattern_logsSiftMenemukan pola error yang meningkat pada log Loki.Peran EditorN/A
find_slow_requestsSiftMenemukan permintaan lambat dari datasource tempo yang relevan.Peran EditorN/A
list_pyroscope_label_namesPyroscopeDaftar nama label yang cocok dengan selektordatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeDaftar nilai label yang cocok dengan selektor untuk nama labeldatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeDaftar tipe profil yang tersediadatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeKueri profil, metrik, atau keduanya dari Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsDapatkan ringkasan asersi untuk entitas tertentuIzin khusus pluginLingkup khusus plugin
agento11y_manage_conversationsAgent Observability*Daftar, cari, dan ambil percakapan LLM dari Grafana Agent Observabilitygrafana-agento11y-app.conversations:readN/A
agento11y_manage_generationsAgent Observability*Ambil detail generasi LLM dan skor evaluasi dari Grafana Agent Observabilitygrafana-agento11y-app.data:readN/A
agento11y_manage_agentsAgent Observability*Baca katalog agen: daftar agen, dapatkan satu versi agen secara lengkap, daftar riwayat versi, dan agregat skor per versigrafana-agento11y-app.data:readN/A
agento11y_manage_evaluatorsAgent Observability*Kelola evaluator, template evaluator, dan katalog juri (daftar, dapatkan, upsert, fork, uji, hapus)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write untuk mutasi dan pengujianN/A
agento11y_manage_eval_rulesAgent Observability*Kelola aturan eval dan guard (daftar, dapatkan, buat, perbarui, pratinjau, hapus)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write untuk mutasi dan pratinjauN/A
agento11y_manage_eval_collectionsAgent Observability*Kelola percakapan tersimpan dan koleksi yang mengelompokkannya (daftar, dapatkan, simpan, buat, perbarui, hapus, tambah dan hapus anggota)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write untuk mutasiN/A
agento11y_manage_experimentsAgent Observability*Baca eksperimen offline, uji coba, skor, metadata artefak, dan facet filter; perbarui dan batalkan eksperimengrafana-agento11y-app.data:read + grafana-agento11y-app.eval:write untuk mutasiN/A
agento11y_manage_test_suitesAgent Observability*Kelola suite pengujian yang digunakan eksperimen offline, versi mereka, dan kasus uji mereka (daftar, dapatkan, buat, perbarui, draf, terbitkan, upsert, hapus)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write untuk mutasiN/A
ask_assistantAssistant*Kirim prompt ke Grafana Assistant dan kembalikan jawaban teks lengkap (multi-putaran melalui contextId)Izin khusus pluginLingkup khusus plugin
generate_deeplinkNavigationHasilkan URL deeplink yang akurat untuk sumber daya GrafanaTidak ada (generasi URL hanya-baca)N/A
get_annotationsAnnotationsAmbil anotasi dengan filterannotations:readannotations:* atau annotations:id:123
create_annotationAnnotationsBuat anotasi baru (format standar atau Graphite)annotations:writeannotations:*
update_annotationAnnotationsPerbarui bidang tertentu dari suatu anotasi (pembaruan parsial)annotations:writeannotations:*
get_annotation_tagsAnnotationsDaftarkan tag anotasi dengan filter opsionalannotations:readannotations:*
list_snapshotsSnapshotDaftarkan tangkapan layar dashboard dengan filter kueri dan batas opsionaldashboards:readdashboards:* atau dashboards:uid:abc123
get_snapshotSnapshotAmbil metadata tangkapan layar dan muatan dashboard berdasarkan kunci tangkapan layardashboards:readdashboards:* atau dashboards:uid:abc123
create_snapshotSnapshotBuat tangkapan layar dashboard dari muatan dashboard lengkapdashboards:writedashboards:* atau dashboards:uid:abc123
delete_snapshotSnapshotHapus tangkapan layar dashboard berdasarkan kunci tangkapan layardashboards:writedashboards:* atau dashboards:uid:abc123
get_panel_imageRenderingRender dashboard atau panel yang tersimpan — atau pratinjau provisioning dari cabang repositori — sebagai gambar PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesProvisioningDaftarkan repositori provisioning (mis. sumber git-sync) beserta URL sumber, cabang, status sinkronisasi, dan kesehatannyaprovisioning.repositories:readN/A
validate_provisioning_fileProvisioningTerapkan uji-kering (dry-run) suatu file dari repositori provisioning dan laporkan kesalahan validasi penerimaanprovisioning.repositories:readN/A
* Nonaktif secara bawaan. Tambahkan kategori ke --enabled-tools untuk mengaktifkannya.

Referensi Flag CLI

Biner mcp-grafana mendukung berbagai flag baris perintah untuk konfigurasi:

Opsi Transport:

  • -t, --transport: Tipe transport (stdio, sse, atau streamable-http) - bawaan: stdio
  • --address: Host dan port untuk server SSE/streamable-http - bawaan: localhost:8000
  • --base-path: Jalur basis untuk server SSE/streamable-http
  • --endpoint-path: Jalur endpoint untuk server streamable-http - bawaan: /mcp
  • --server-name: Nama server yang digunakan dalam jabat tangan MCP dan OTel service.name - bawaan: mcp-grafana. Menimpa variabel env GRAFANA_MCP_SERVER_NAME

Keamanan Transport HTTP (khusus SSE / streamable-http):

Validasi Host/Origin diterapkan pada setiap rute di listener — /sse, /mcp, /healthz, dan /metrics — sehingga browser yang melakukan DNS-rebinding tidak dapat menjangkau salah satu dari rute tersebut. Transport stdio tidak terpengaruh.

  • --allowed-hosts: Daftar izin nilai header Host yang dipisahkan koma. Bawaan ke varian loopback dari --address (misalnya localhost:8000,127.0.0.1:8000,[::1]:8000). Nilai yang terurai menjadi kosong (tidak disetel, ,, ,, dst.) juga kembali ke bawaan sehingga salah ketik tidak dapat secara diam-diam menonaktifkan pemeriksaan. Permintaan dengan header Host di luar daftar izin ditolak dengan 403. Berikan * untuk menonaktifkan pemeriksaan — hanya aman saat berjalan di belakang reverse proxy tepercaya yang menulis ulang Host, atau di jaringan terisolasi. Probe K8s httpGet dan pengikisan /metrics eksternal akan memerlukan nama host eksplisit dalam daftar ini, *, atau probe tcpSocket / port metrik terpisah (--metrics-address).
  • --allowed-origins: Daftar izin nilai header Origin yang dipisahkan koma. Kosong secara bawaan — permintaan apa pun yang membawa header Origin ditolak (browser selalu mengirimkannya untuk permintaan lintas-origin, dan tidak ada browser yang seharusnya memanggil server ini secara langsung). Setel ke daftar eksplisit untuk mengizinkan klien berbasis browser, atau * untuk menonaktifkan pemeriksaan.

Autentikasi Pemanggil (khusus SSE / streamable-http):

Secara opsional mewajibkan klien MCP untuk melakukan autentikasi ke server. Ini terpisah dari kredensial yang digunakan server untuk menjangkau Grafana. Stdio tidak terpengaruh.

  • --server-auth-token: Token bearer yang harus dikirim pemanggil sebagai Authorization: Bearer <token>. Kembali ke variabel lingkungan MCP_GRAFANA_SERVER_TOKEN. Saat disetel, permintaan tanpa token valid ditolak dengan 401 sebelum alat apa pun dijalankan. Utamakan variabel env agar rahasia tidak terlihat dalam argumen proses.

Autentikasi pemanggil hanya diterapkan saat --server-auth-token disetel. Jika tidak disetel dan server mengikat alamat non-loopback, server mulai tetapi mencatat kesalahan keamanan — dikeluarkan pada level log error sehingga tidak disembunyikan oleh --log-level (loopback dan stdio tidak terpengaruh); rilis mayor mendatang akan menjadikannya kesalahan startup. Gunakan TLS (atau terminasi TLS) setiap kali autentikasi pemanggil diaktifkan pada alamat non-loopback. Saat autentikasi pemanggil diaktifkan, header Authorization yang tervalidasi dihilangkan sebelum permintaan mencapai Grafana; menggabungkan --server-auth-token dengan GRAFANA_FORWARD_HEADERS=Authorization ditolak saat startup.

Debug dan Pencatatan Log:

  • --debug: Aktifkan mode debug untuk pencatatan log permintaan/respons HTTP yang terperinci
  • --log-level: Level log (debug, info, warn, error) - bawaan: info

Opsi Klien Grafana:

  • --grafana-timeout: Batas waktu untuk permintaan yang dibuat oleh klien Grafana. Menerima string durasi Go (misalnya, 10s, 500ms) - bawaan: 10s
  • --include-args-in-spans: Sertakan argumen pemanggilan alat dalam span OpenTelemetry. Hanya aktifkan di lingkungan non-produksi atau saat argumen diketahui tidak mengandung PII - bawaan: false

Observabilitas:

  • --metrics: Aktifkan endpoint metrik Prometheus di /metrics
  • --metrics-address: Alamat terpisah untuk server metrik (misalnya, :9090). Jika kosong, metrik dilayani di server utama
  • --slow-request-threshold: Catat peristiwa saat permintaan MCP apa pun (invokasi alat, daftar, pembacaan sumber daya, dst.) memakan waktu lebih lama dari durasi ini. Menerima string durasi Go (misalnya, 500ms, 5s). Bawaan 0 menonaktifkan pencatatan permintaan lambat. Lihat bagian Pencatatan permintaan lambat.
  • --slow-request-log-level: Level log untuk peristiwa permintaan lambat (info atau warn) - bawaan: warn.

Manajemen Sesi:

  • --session-idle-timeout-minutes: Batas waktu idle sesi dalam menit. Sesi tanpa aktivitas selama durasi ini secara otomatis dibersihkan - bawaan: 30. Setel ke 0 untuk menonaktifkan pembersihan sesi. Hanya relevan untuk transport SSE dan streamable-http.

Konfigurasi Alat:

  • --enabled-tools: Daftar kategori yang diaktifkan, dipisahkan koma - bawaan: semua kategori kecuali admin, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, dan snowflake. Untuk mengaktifkan kategori yang dinonaktifkan, tambahkan ke daftar (misalnya, "search,datasource,...,snowflake")
  • --max-loki-log-limit: Jumlah maksimum baris log yang dikembalikan per panggilan query_loki_logs - bawaan: 100. Catatan: Setel ini setidaknya 1 di bawah max_entries_limit_per_query sisi server Loki untuk memungkinkan deteksi pemotongan (alat meminta limit+1 secara internal untuk mendeteksi apakah masih ada data).
  • --disable-search: Nonaktifkan alat pencarian
  • --disable-datasource: Nonaktifkan alat datasource
  • --disable-incident: Nonaktifkan alat insiden
  • --disable-prometheus: Nonaktifkan alat prometheus
  • --disable-write: Nonaktifkan alat tulis (operasi buat/perbarui)
  • --disable-loki: Nonaktifkan alat loki
  • --disable-elasticsearch: Nonaktifkan alat elasticsearch dan opensearch
  • --disable-quickwit: Nonaktifkan alat quickwit
  • --disable-influxdb: Nonaktifkan alat InfluxDB
  • --disable-alerting: Nonaktifkan alat alerting
  • --disable-dashboard: Nonaktifkan alat dashboard
  • --disable-oncall: Nonaktifkan alat oncall
  • --disable-asserts: Nonaktifkan alat asserts
  • --disable-sift: Nonaktifkan alat sift
  • --disable-admin: Nonaktifkan alat admin
  • --disable-pyroscope: Nonaktifkan alat pyroscope
  • --disable-navigation: Nonaktifkan alat navigasi
  • --disable-rendering: Nonaktifkan alat rendering (ekspor gambar panel/dashboard)
  • --disable-snapshot: Nonaktifkan alat snapshot
  • --disable-cloudwatch: Nonaktifkan alat CloudWatch
  • --disable-examples: Nonaktifkan alat contoh kueri
  • --disable-clickhouse: Nonaktifkan alat ClickHouse
  • --disable-snowflake: Nonaktifkan alat Snowflake
  • --disable-runpanelquery: Nonaktifkan alat kueri panel berjalan
  • --disable-graphite: Nonaktifkan alat Graphite
  • --disable-athena: Nonaktifkan alat Athena
  • --disable-provisioning: Nonaktifkan alat provisioning
  • --disable-agento11y: Nonaktifkan alat Agent Observability
  • --disable-assistant: Nonaktifkan alat Grafana Assistant

Mode Hanya-Baca

Flag --disable-write menyediakan cara untuk menjalankan server MCP dalam mode hanya-baca, mencegah operasi tulis apa pun ke instance Grafana Anda. Ini berguna untuk skenario di mana Anda ingin menyediakan akses hanya-baca yang aman seperti:

  • Menggunakan akun layanan dengan izin hanya-baca terbatas
  • Memberikan asisten AI data observabilitas tanpa kemampuan modifikasi
  • Berjalan di lingkungan produksi di mana akses tulis harus dibatasi
  • Skenario pengujian dan pengembangan di mana Anda ingin mencegah modifikasi yang tidak disengaja

Saat --disable-write diaktifkan, operasi tulis berikut dinonaktifkan:

Alat Dashboard:

  • update_dashboard

Alat Folder:

  • create_folder

Alat Insiden:

  • create_incident
  • add_activity_to_incident

Alat Alerting:

  • alerting_manage_rules (operasi buat, perbarui, hapus)

Alat Anotasi:

  • create_annotation
  • update_annotation

Alat Sift:

  • find_error_pattern_logs (membuat investigasi)
  • find_slow_requests (membuat investigasi)

Alat Snapshot:

  • create_snapshot
  • delete_snapshot

Alat Agent Observability:

  • agento11y_manage_evaluators (operasi upsert, hapus, fork, uji evaluator)
  • agento11y_manage_eval_rules (operasi buat, perbarui, hapus, pratinjau aturan dan guard)
  • agento11y_manage_eval_collections (simpan dan hapus percakapan tersimpan; buat, perbarui, hapus koleksi; tambah dan hapus anggota koleksi)
  • agento11y_manage_experiments (perbarui dan batalkan operasi eksperimen)
  • agento11y_manage_test_suites (buat dan perbarui rangkaian uji; buat dan terbitkan versi; upsert dan hapus kasus uji)

Semua operasi baca tetap tersedia, memungkinkan Anda untuk mengkueri dashboard, menjalankan kueri PromQL/LogQL, membuat daftar sumber daya, dan mengambil data.

Konfigurasi TLS Klien (untuk koneksi Grafana):

  • --tls-cert-file: Jalur ke file sertifikat TLS untuk autentikasi klien
  • --tls-key-file: Jalur ke file kunci privat TLS untuk autentikasi klien
  • --tls-ca-file: Jalur ke file sertifikat CA TLS untuk verifikasi server
  • --tls-skip-verify: Lewati verifikasi sertifikat TLS (tidak aman)

Konfigurasi TLS Server (khusus transport streamable-http):

  • --server.tls-cert-file: Jalur ke file sertifikat TLS untuk HTTPS server
  • --server.tls-key-file: Jalur ke file kunci privat TLS untuk HTTPS server

Penggunaan

Server MCP ini bekerja dengan instance Grafana lokal dan Grafana Cloud. Untuk Grafana Cloud, gunakan URL instance Anda (misalnya, https://myinstance.grafana.net) alih-alih http://localhost:3000 dalam contoh konfigurasi di bawah.

  1. Jika menggunakan autentikasi token akun layanan, buat akun layanan di Grafana dengan izin yang cukup untuk menggunakan alat yang ingin Anda gunakan, buat token akun layanan, dan salin ke clipboard untuk digunakan dalam file konfigurasi. Ikuti dokumentasi akun layanan Grafana untuk detail pembuatan token akun layanan. Tip: Jika Anda tidak nyaman mengonfigurasi cakupan RBAC berbutir halus, opsi yang lebih sederhana (tetapi kurang restriktif) adalah menetapkan peran bawaan Editor ke akun layanan. Ini memberikan akses baca/tulis luas yang mencakup sebagian besar operasi server MCP — gunakan saat kenyamanan lebih diutamakan daripada persyaratan hak-akses-minimum yang ketat.

    Catatan: Variabel lingkungan GRAFANA_API_KEY tidak digunakan lagi dan akan dihapus di versi mendatang. Harap migrasikan untuk menggunakan GRAFANA_SERVICE_ACCOUNT_TOKEN sebagai gantinya. Nama variabel lama akan terus berfungsi untuk kompatibilitas mundur tetapi akan menampilkan peringatan deprecation.

Membaca token akun layanan dari file

Alih-alih meneruskan token secara inline melalui GRAFANA_SERVICE_ACCOUNT_TOKEN, Anda dapat mengarahkan GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ke jalur file yang berisi token tersebut. File dibaca ulang pada setiap permintaan, sehingga token yang dirotasi diambil secara otomatis tanpa memulai ulang server.

Ini sangat berguna di Kubernetes, di mana Secret yang dipasang sebagai volume diperbarui di tempat ketika Secret yang mendasarinya berubah (biasanya dalam ~1 menit). Digabungkan dengan cache klien per-permintaan — yang dikunci berdasarkan nilai token — token yang dirotasi secara transparan menghasilkan klien baru tanpa restart pod dan tanpa waktu henti:

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

Spasi di sekitarnya (termasuk baris baru di akhir) dipangkas dari isi file. Jika GRAFANA_SERVICE_ACCOUNT_TOKEN dan GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE keduanya disetel, token inline lebih diutamakan.

Dukungan Multi-Organisasi

Anda dapat menentukan organisasi mana yang akan diinteraksikan menggunakan salah satu dari:

  • Variabel lingkungan: Setel GRAFANA_ORG_ID ke ID organisasi numerik
  • Header HTTP: Setel X-Grafana-Org-Id saat menggunakan transport SSE atau streamable HTTP (header lebih diutamakan daripada variabel lingkungan — artinya Anda juga dapat menyetel org bawaan).

Saat ID organisasi diberikan, server MCP akan menyetel header X-Grafana-Org-Id pada semua permintaan ke Grafana, memastikan bahwa operasi dilakukan dalam konteks organisasi yang ditentukan.

Contoh dengan ID organisasi:

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

Header HTTP Kustom

Anda dapat menambahkan header HTTP arbitrer ke semua permintaan API Grafana menggunakan variabel lingkungan GRAFANA_EXTRA_HEADERS. Nilainya harus berupa objek JSON yang memetakan nama header ke nilai.

Contoh dengan header kustom:

{
  "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\"}"
      }
    }
  }
}

Meneruskan Header dari Klien (Hanya SSE/Streamable-HTTP)

Ketika server MCP berjalan di belakang gateway atau proxy terbalik yang menangani SSO (misalnya AWS ALB dengan OIDC), cookie sesi setiap pengguna harus mencapai Grafana sehingga dapat mengaitkan permintaan dengan pengguna yang terautentikasi. Variabel lingkungan GRAFANA_FORWARD_HEADERS memungkinkan ini dengan menentukan daftar izin yang dipisahkan koma dari nama header untuk disalin dari permintaan HTTP masuk ke setiap permintaan API Grafana keluar.

Ini hanya berlaku saat menggunakan transport SSE (-t sse) atau streamable-http (-t streamable-http). Ini tidak berpengaruh dalam mode stdio.

Contoh: meneruskan cookie sesi

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

Anda dapat meneruskan beberapa header dengan memisahkannya dengan koma:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Header yang diteruskan digabungkan dengan header apa pun yang didefinisikan dalam GRAFANA_EXTRA_HEADERS. Jika nama header muncul di keduanya, nilai dari permintaan masuk lebih diutamakan untuk permintaan tersebut.

  1. Anda memiliki beberapa opsi untuk menginstal mcp-grafana:

    • uvx (disarankan): Jika Anda memiliki uv terinstal, tidak diperlukan pengaturan tambahan — uvx akan secara otomatis mengunduh dan menjalankan server:

      uvx mcp-grafana

    • Citra Docker: Gunakan citra Docker yang sudah dibuat dari Docker Hub.

      Penting: Entrypoint citra Docker dikonfigurasi untuk menjalankan server MCP dalam mode SSE secara default, tetapi sebagian besar pengguna akan ingin menggunakan mode STDIO untuk integrasi langsung dengan asisten AI seperti Claude Desktop:

      1. Mode STDIO: Untuk mode stdio, Anda harus secara eksplisit menimpa default dengan -t stdio dan menyertakan flag -i untuk menjaga stdin tetap terbuka:
      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

      Catatan — amankan mode jaringan: Dalam mode SSE dan streamable-http, kontainer mengikat alamat non-loopback (0.0.0.0:8000). Tanpa token pemanggil, server mulai tetapi mencatat kesalahan keamanan (pada tingkat log error, sehingga tidak disembunyikan oleh --log-level; dan akan menolak untuk mulai dalam rilis utama mendatang). Setel MCP_GRAFANA_SERVER_TOKEN untuk memerlukan Authorization: Bearer <token> dari klien (disarankan). Mode STDIO tidak terpengaruh. Lihat Autentikasi Pemanggil.

      1. Mode SSE: Dalam mode ini, server berjalan sebagai server HTTP yang terhubung oleh klien. Anda harus mengekspos port 8000 menggunakan flag -p:
      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. Mode HTTP Streamable: Dalam mode ini, server beroperasi sebagai proses independen yang dapat menangani beberapa koneksi klien. Anda harus mengekspos port 8000 menggunakan flag -p: Untuk mode ini, Anda harus secara eksplisit menimpa default dengan -t streamable-http
      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

      Untuk mode HTTP streamable HTTPS dengan sertifikat TLS server:

      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

    • Unduh biner: Unduh rilis terbaru dari mcp-grafana dari halaman rilis dan letakkan di $PATH Anda.

    • Bangun dari sumber: Jika Anda memiliki rantai alat Go terinstal, Anda juga dapat membangun dan menginstalnya dari sumber, menggunakan variabel lingkungan GOBIN untuk menentukan direktori tempat biner harus diinstal. Ini juga harus ada di $PATH Anda.

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

    • Terapkan ke Kubernetes menggunakan Helm: gunakan bagan Helm dari repositori helm-charts Grafana

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

  2. Tambahkan konfigurasi server ke file konfigurasi klien Anda. Misalnya, untuk Claude Desktop:

    Jika menggunakan uvx:

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

    Jika menggunakan biner:

    {
  "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"
      }
    }
  }
}

Catatan: jika Anda melihat Error: spawn mcp-grafana ENOENT di Claude Desktop, Anda perlu menentukan jalur lengkap ke mcp-grafana.

Jika menggunakan Docker:

{
  "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"
      }
    }
  }
}

Catatan: Argumen -t stdio sangat penting di sini karena menimpa mode SSE default dalam citra Docker.

Menggunakan VSCode dengan server MCP jarak jauh

Jika Anda menggunakan VSCode dan menjalankan server MCP dalam mode SSE (yang merupakan default saat menggunakan citra Docker tanpa menimpa transport), pastikan .vscode/settings.json Anda menyertakan yang berikut:

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

Untuk mode HTTP streamable HTTPS dengan sertifikat TLS server:

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

Mode Debug

Anda dapat mengaktifkan mode debug untuk transport Grafana dengan menambahkan flag -debug ke perintah. Ini akan memberikan pencatatan terperinci dari permintaan dan respons HTTP antara server MCP dan API Grafana, yang dapat membantu untuk pemecahan masalah.

Untuk menggunakan mode debug dengan konfigurasi Claude Desktop, perbarui konfigurasi Anda sebagai berikut:

Jika menggunakan biner:

{
  "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>"
      }
    }
  }
}

Jika menggunakan Docker:

{
  "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>"
      }
    }
  }
}

Catatan: Seperti dengan konfigurasi standar, argumen -t stdio diperlukan untuk menimpa mode SSE default dalam citra Docker.

Konfigurasi TLS

Jika instance Grafana Anda berada di belakang mTLS atau memerlukan sertifikat TLS kustom, Anda dapat mengonfigurasi server MCP untuk menggunakan sertifikat kustom. Server mendukung opsi konfigurasi TLS berikut:

  • --tls-cert-file: Jalur ke file sertifikat TLS untuk autentikasi klien
  • --tls-key-file: Jalur ke file kunci privat TLS untuk autentikasi klien
  • --tls-ca-file: Jalur ke file sertifikat CA TLS untuk verifikasi server
  • --tls-skip-verify: Lewati verifikasi sertifikat TLS (tidak aman, gunakan hanya untuk pengujian)

Contoh dengan autentikasi sertifikat klien:

{
  "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>"
      }
    }
  }
}

Contoh dengan Docker:

{
  "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>"
      }
    }
  }
}

Konfigurasi TLS diterapkan ke semua klien HTTP yang digunakan oleh server MCP, termasuk:

  • Klien OpenAPI Grafana utama
  • Klien sumber data Prometheus
  • Klien sumber data Loki
  • Klien manajemen insiden
  • Klien investigasi Sift
  • Klien alerting
  • Klien Asserts

Contoh Penggunaan CLI Langsung:

Untuk pengujian dengan sertifikat yang ditandatangani sendiri:

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

Dengan autentikasi sertifikat klien:

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

Dengan sertifikat CA kustom saja:

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

Penggunaan Programatik:

Jika Anda menggunakan pustaka ini secara programatik, Anda juga dapat membuat fungsi konteks yang mendukung TLS:

// 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)

Validasi URL:

Saat memanggil NewGrafanaClient secara langsung (stdio atau konstruksi programatik), validasi URL terlebih dahulu untuk menghindari panic yang dapat dijangkau:

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

Konfigurasi TLS Server (Hanya Transport HTTP Streamable)

Saat menggunakan transport HTTP streamable (-t streamable-http), Anda dapat mengonfigurasi server MCP untuk menyajikan HTTPS alih-alih HTTP. Ini berguna ketika Anda perlu mengamankan koneksi antara klien MCP dan server itu sendiri.

Server mendukung opsi konfigurasi TLS berikut untuk transport HTTP streamable:

  • --server.tls-cert-file: Jalur ke file sertifikat TLS untuk HTTPS server (diperlukan untuk TLS)
  • --server.tls-key-file: Jalur ke file kunci privat TLS untuk HTTPS server (diperlukan untuk TLS)

Catatan: Flag ini sepenuhnya terpisah dari flag TLS klien yang didokumentasikan di atas. Flag TLS klien mengonfigurasi bagaimana server MCP terhubung ke Grafana, sementara flag TLS server ini mengonfigurasi bagaimana klien terhubung ke server MCP saat menggunakan transport HTTP streamable.

Contoh dengan server HTTP streamable HTTPS:

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

Ini akan memulai server MCP pada port HTTPS 8443. Klien kemudian akan terhubung ke https://localhost:8443/ alih-alih http://localhost:8000/.

Contoh Docker dengan TLS server:

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

Titik Akhir Pemeriksaan Kesehatan

Saat menggunakan transport SSE (-t sse) atau HTTP streamable (-t streamable-http), server MCP mengekspos titik akhir pemeriksaan kesehatan di /healthz. Titik akhir ini dapat digunakan oleh penyeimbang beban, sistem pemantauan, atau platform orkestrasi untuk memverifikasi bahwa server berjalan dan menerima koneksi.

Titik Akhir: GET /healthz

Respons:

  • Kode Status: 200 OK
  • Badan: ok

Contoh penggunaan:

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

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

Catatan: Titik akhir pemeriksaan kesehatan hanya tersedia saat menggunakan transport SSE atau HTTP streamable. Ini tidak tersedia saat menggunakan transport stdio (-t stdio), karena stdio tidak mengekspos server HTTP.

Observabilitas

Server MCP mendukung metrik Prometheus, pelacakan terdistribusi OpenTelemetry, dan ekspor log OpenTelemetry, mengikuti konvensi semantik OTel MCP. Pelacakan dan ekspor log dikonfigurasi melalui variabel lingkungan standar OTEL_* dan bekerja dengan transport apa pun.

Catatan: mcp-grafana saat ini hanya mendukung transport OTLP/gRPC untuk jejak dan log. OTEL_EXPORTER_OTLP_PROTOCOL (dan varian _TRACES_PROTOCOL / _LOGS_PROTOCOL) tidak dihormati — gRPC digunakan apa pun.

Metrik

Saat menggunakan transport SSE atau HTTP streamable, aktifkan metrik Prometheus dengan flag --metrics:

# 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

Metrik yang Tersedia:

MetrikTipeDeskripsi
mcp_server_operation_duration_secondsHistogramDurasi operasi MCP (label: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramDurasi sesi klien MCP (label: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramDurasi permintaan server HTTP (dari otelhttp)

Catatan: Metrik hanya tersedia saat menggunakan transport SSE atau HTTP streamable. Metrik tidak tersedia dengan transport stdio.

Pencatatan permintaan lambat

Flag --slow-request-threshold mengeluarkan peristiwa log terstruktur setiap kali permintaan MCP (pemanggilan alat, daftar, pembacaan sumber daya, dll.) melebihi durasi yang diberikan. Ini berguna untuk mendiagnosis kueri dan panggilan alat yang lambat tanpa tenggelam dalam log debug penuh.

# 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

Peristiwa log membawa atribut terstruktur ini:

AtributDeskripsi
mcp.methodMetode MCP (misalnya, tools/call, tools/list, resources/read)
durationDurasi permintaan yang diamati
thresholdAmbang batas yang dikonfigurasi
toolNama alat (hanya ada untuk metode tools/call)
errorNilai kesalahan, saat permintaan gagal (konteks upaya terbaik; konten dikendalikan oleh pembungkusan kesalahan hulu)
error.typeKlasifikasi kesalahan dengan kardinalitas terbatas (_OTHER untuk kesalahan tanpa tipe)

Pencatatan permintaan lambat bekerja pada semua transport (termasuk stdio) dan tidak memerlukan --metrics. Ambang batas default dari 0 menonaktifkannya sepenuhnya. Alat yang diproksi mengalir melalui tools/call dan tercakup secara otomatis.

Pelacakan

Pelacakan terdistribusi dikonfigurasi melalui variabel lingkungan standar OTEL_* dan bekerja secara independen dari flag --metrics. Ketika OTEL_EXPORTER_OTLP_ENDPOINT (atau OTEL_EXPORTER_OTLP_TRACES_ENDPOINT khusus sinyal) diatur, server mengekspor jejak melalui OTLP/gRPC:

# 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

Rentang panggilan alat mengikuti penamaan semconv (tools/call <tool_name>) dan menyertakan atribut seperti gen_ai.tool.name, mcp.method.name, dan mcp.session.id. Server juga mendukung propagasi konteks jejak W3C dari bidang _meta dari permintaan panggilan alat.

Log

Ketika OTEL_EXPORTER_OTLP_ENDPOINT (atau OTEL_EXPORTER_OTLP_LOGS_ENDPOINT khusus sinyal) diatur, server juga mengekspor log terstruktur melalui OTLP/gRPC selain output stderr teks biasa yang ada. Jembatan otelslog secara otomatis melampirkan trace_id dan span_id dari rentang aktif, sehingga catatan log berkorelasi dengan jejak yang sudah dipancarkan server.

Jejak dan log menyelesaikan titik akhirnya secara independen, sehingga kedua sinyal dapat diaktifkan secara terpisah: mengatur hanya OTEL_EXPORTER_OTLP_TRACES_ENDPOINT mengaktifkan pelacakan tanpa ekspor log, mengatur hanya OTEL_EXPORTER_OTLP_LOGS_ENDPOINT mengaktifkan ekspor log tanpa pelacakan, dan OTEL_EXPORTER_OTLP_ENDPOINT generik mengaktifkan keduanya.

Jika Anda menggunakan OTEL_EXPORTER_OTLP_ENDPOINT generik tetapi ingin menonaktifkan ekspor log (misalnya backend Anda tidak mendukung LogsService), atur:

OTEL_LOGS_EXPORTER=none

This prevents the server from creating an OTLP logs exporter regardless of the endpoint configuration, avoiding errors like unknown service opentelemetry.proto.collector.logs.v1.LogsService.

Stderr logging is unchanged when OTLP logging is enabled; you can continue to rely on container logs or pipe stderr to /dev/null if you prefer.

# 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

The transport is OTLP/gRPC (default port 4317). Logs can be sent directly to any managed backend that accepts OTLP/gRPC — for example, Grafana Cloud — by pointing OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (or the generic OTEL_EXPORTER_OTLP_ENDPOINT) at the remote gRPC endpoint and supplying auth via OTEL_EXPORTER_OTLP_LOGS_HEADERS (or OTEL_EXPORTER_OTLP_HEADERS), mirroring the tracing example above. A local OTel collector is optional — useful for fan-out, batching, or multi-backend routing, but not required.

The signal-specific variants 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, and OTEL_EXPORTER_OTLP_LOGS_COMPRESSION are honored and override their generic OTEL_EXPORTER_OTLP_* counterparts — see the OTel exporter spec for the full list and precedence rules.

If the configured collector is unreachable, log records are buffered in memory (default queue: 2048) and the oldest records are dropped once the queue fills. The process continues without blocking the service. Configure a local OTel collector if you need lossless buffering during outages.

Logs are also exported under the stdio transport, which makes it easy to centralize logs from local mcp-grafana instances invoked by IDE clients.

Docker example with metrics, tracing, and logs:

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

Troubleshooting

Grafana Version Compatibility

If you encounter the following error when using datasource-related tools:

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

This typically indicates that you are using a Grafana version earlier than 9.0. The /datasources/uid/{uid} API endpoint was introduced in Grafana 9.0, and datasource operations will fail on earlier versions.

Solution: Upgrade your Grafana instance to version 9.0 or later to resolve this issue.

Development

Contributions are welcome! Please open an issue or submit a pull request if you have any suggestions or improvements.

This project is written in Go. Install Go following the instructions for your platform.

To run the server locally in STDIO mode (which is the default for local development), use:

make run

To run the server locally in SSE mode, use:

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

You can also run the server using the SSE transport inside a custom built Docker image. Just like the published Docker image, this custom image's entrypoint defaults to SSE mode. To build the image, use:

make build-image

And to run the image in SSE mode (the default), use:

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

If you need to run it in STDIO mode instead, override the transport setting:

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

Testing

There are three types of tests available:

  1. Unit Tests (no external dependencies required):
make test-unit

You can also run unit tests with:

make test
  1. Integration Tests (requires docker containers to be up and running):
make test-integration
  1. Cloud Tests (requires cloud Grafana instance and credentials):
make test-cloud

Note: Cloud tests are automatically configured in CI. For local development, you'll need to set up your own Grafana Cloud instance and credentials.

More comprehensive integration tests will require a Grafana instance to be running locally on port 3000; you can start one with Docker Compose:

docker-compose up -d

The integration tests can be run with:

make test-all

If you're adding more tools, please add integration tests for them. The existing tests should be a good starting point.

Linting

To lint the code, run:

make lint

This includes a custom linter that checks for unescaped commas in jsonschema struct tags. The commas in description fields must be escaped with \\, to prevent silent truncation. You can run just this linter with:

make lint-jsonschema

See the JSONSchema Linter documentation for more details.

License

This project is licensed under the Apache License, Version 2.0.