Grafana MCP Server

ทางการ

ค้นหาแดชบอร์ด ตรวจสอบเหตุการณ์ และสอบถามแหล่งข้อมูลในอินสแตนซ์ Grafana ของคุณ

GitHub
3.2k

เอกสาร

เซิร์ฟเวอร์ Grafana MCP

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

เซิร์ฟเวอร์ Model Context Protocol (MCP) สำหรับ Grafana

สิ่งนี้ให้การเข้าถึงอินสแตนซ์ Grafana และระบบนิเวศโดยรอบของคุณ

เริ่มต้นอย่างรวดเร็ว

ต้องการ uv เพิ่มสิ่งต่อไปนี้ในการกำหนดค่าไคลเอนต์ MCP ของคุณ (เช่น 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 ให้แทนที่ GRAFANA_URL ด้วย URL อินสแตนซ์ของคุณ (เช่น https://myinstance.grafana.net) ดู การใช้งาน สำหรับตัวเลือกการติดตั้งเพิ่มเติม รวมถึง Docker, ไบนารี และ Helm

ข้อกำหนด

  • Grafana เวอร์ชัน 9.0 หรือใหม่กว่า จำเป็นสำหรับฟังก์ชันการทำงานเต็มรูปแบบ คุณสมบัติบางอย่าง โดยเฉพาะการดำเนินการที่เกี่ยวข้องกับแหล่งข้อมูล อาจทำงานไม่ถูกต้องกับเวอร์ชันก่อนหน้าเนื่องจากปลายทาง API ที่ขาดหายไป

คุณสมบัติ

คุณสมบัติต่อไปนี้มีให้ใช้งานในปัจจุบันในเซิร์ฟเวอร์ MCP รายการนี้มีวัตถุประสงค์เพื่อให้ข้อมูลเท่านั้น และไม่ได้แสดงถึงแผนงานหรือข้อผูกมัดสำหรับคุณสมบัติในอนาคต

แดชบอร์ด

  • ค้นหาแดชบอร์ด: ค้นหาแดชบอร์ดตามชื่อหรือข้อมูลเมตาอื่นๆ
  • รับแดชบอร์ดตาม UID: ดึงรายละเอียดแดชบอร์ดทั้งหมดโดยใช้ตัวระบุเฉพาะ คำเตือน: แดชบอร์ดขนาดใหญ่สามารถใช้พื้นที่หน้าต่างบริบทได้มาก
  • รับสรุปแดชบอร์ด: รับภาพรวมที่กะทัดรัดของแดชบอร์ด รวมถึงชื่อ จำนวนแผง ประเภทแผง ตัวแปร และข้อมูลเมตา โดยไม่มี JSON เต็ม เพื่อลดการใช้หน้าต่างบริบท
  • รับคุณสมบัติแดชบอร์ด: แยกส่วนเฉพาะของแดชบอร์ดโดยใช้นิพจน์ JSONPath (เช่น $.title, $.panels[*].title) เพื่อดึงเฉพาะข้อมูลที่จำเป็นและลดการใช้หน้าต่างบริบท
  • อัปเดตหรือสร้างแดชบอร์ด: แก้ไขแดชบอร์ดที่มีอยู่หรือสร้างใหม่ คำเตือน: ต้องการ JSON แดชบอร์ดเต็มรูปแบบซึ่งสามารถใช้พื้นที่หน้าต่างบริบทได้มาก
  • แพตช์แดชบอร์ด: ใช้การเปลี่ยนแปลงเฉพาะกับแดชบอร์ดโดยไม่ต้องใช้ JSON เต็มรูปแบบ ลดการใช้หน้าต่างบริบทสำหรับการแก้ไขเฉพาะจุดอย่างมาก
  • รับคิวรีแผงและข้อมูลแหล่งข้อมูล: รับชื่อ สตริงคิวรี และข้อมูลแหล่งข้อมูล (รวมถึง UID และประเภท หากมี) จากทุกแผงในแดชบอร์ด

เรียกใช้คิวรีแผง

หมายเหตุ: เครื่องมือเรียกใช้คิวรีแผงถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม runpanelquery ลงในแฟล็ก --enabled-tools ของคุณ

  • เรียกใช้คิวรีแผง: ดำเนินการคิวรีของแผงแดชบอร์ดด้วยช่วงเวลาแบบกำหนดเองและการแทนที่ตัวแปร

การจัดการหน้าต่างบริบท

เครื่องมือแดชบอร์ดตอนนี้มีกลยุทธ์หลายอย่างในการจัดการการใช้หน้าต่างบริบทอย่างมีประสิทธิภาพ (issue #101):

  • ใช้ get_dashboard_summary สำหรับภาพรวมแดชบอร์ดและการวางแผนการแก้ไข
  • ใช้ get_dashboard_property กับ JSONPath เมื่อคุณต้องการเฉพาะส่วนของแดชบอร์ด
  • หลีกเลี่ยง get_dashboard_by_uid เว้นแต่คุณต้องการ JSON แดชบอร์ดที่สมบูรณ์โดยเฉพาะ

แหล่งข้อมูล

  • แสดงรายการและดึงข้อมูลแหล่งข้อมูล: ดูแหล่งข้อมูลที่กำหนดค่าทั้งหมดและดึงข้อมูลรายละเอียดเกี่ยวกับแต่ละรายการ
    • ประเภทแหล่งข้อมูลที่รองรับ: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena

ตัวอย่างคิวรี

หมายเหตุ: เครื่องมือตัวอย่างคิวรีถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม examples ลงในแฟล็ก --enabled-tools ของคุณ

  • รับตัวอย่างคิวรี: ดึงตัวอย่างคิวรีสำหรับประเภทแหล่งข้อมูลต่างๆ เพื่อเรียนรู้ไวยากรณ์คิวรี

การคิวรี Prometheus

  • คิวรี Prometheus: ดำเนินการคิวรี PromQL (รองรับทั้งคิวรีเมตริกแบบทันทีและแบบช่วง) กับแหล่งข้อมูล Prometheus
  • คิวรีข้อมูลเมตา Prometheus: ดึงข้อมูลเมตาเมตริก ชื่อเมตริก ชื่อป้ายกำกับ และค่าป้ายกำกับจากแหล่งข้อมูล Prometheus
  • คิวรีเปอร์เซ็นไทล์ฮิสโตแกรม: คำนวณค่าเปอร์เซ็นไทล์ฮิสโตแกรม (p50, p90, p95, p99) โดยใช้ histogram_quantile

การคิวรี Loki

  • คิวรีบันทึกและเมตริก Loki: เรียกใช้ทั้งคิวรีบันทึกและคิวรีเมตริกโดยใช้ LogQL กับแหล่งข้อมูล Loki
  • คิวรีข้อมูลเมตา Loki: ดึงชื่อป้ายกำกับ ค่าป้ายกำกับ และสถิติสตรีมจากแหล่งข้อมูล Loki
  • คิวรีรูปแบบ Loki: ดึงรูปแบบบันทึกที่ตรวจพบโดย Loki เพื่อระบุโครงสร้างบันทึกทั่วไปและความผิดปกติ

การคิวรี InfluxDB

หมายเหตุ: เครื่องมือ InfluxDB ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม influxdb ลงในแฟล็ก --enabled-tools ของคุณ

  • คิวรี InfluxDB: ดำเนินการคิวรีกับแหล่งข้อมูล InfluxDB โดยใช้ InfluxQL (v1.x) หรือ Flux (v2.x) ภาษาถูกอนุมานจากการกำหนดค่าแหล่งข้อมูล หรือสามารถตั้งค่าอย่างชัดเจนผ่านพารามิเตอร์ dialect

การคิวรี ClickHouse

หมายเหตุ: เครื่องมือ ClickHouse ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม clickhouse ลงในแฟล็ก --enabled-tools ของคุณ

  • แสดงรายการตาราง ClickHouse: แสดงรายการตารางทั้งหมดในฐานข้อมูล ClickHouse พร้อมจำนวนแถวและขนาด
  • อธิบายสคีมาตาราง: รับชื่อคอลัมน์ ประเภท และข้อมูลเมตาสำหรับตาราง ClickHouse
  • คิวรี ClickHouse: ดำเนินการคิวรี SQL ด้วยการสนับสนุนการแทนที่แมโครและตัวแปรของ Grafana

การคิวรี CloudWatch

หมายเหตุ: เครื่องมือ CloudWatch ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม cloudwatch ลงในแฟล็ก --enabled-tools ของคุณ

  • แสดงรายการเนมสเปซ CloudWatch: ค้นพบเนมสเปซ AWS CloudWatch ที่พร้อมใช้งาน
  • แสดงรายการเมตริก CloudWatch: แสดงรายการเมตริกที่มีอยู่ในเนมสเปซเฉพาะ
  • แสดงรายการไดเมนชัน CloudWatch: รับไดเมนชันสำหรับการกรองคิวรีเมตริก
  • คิวรี CloudWatch: ดำเนินการคิวรีเมตริก CloudWatch ด้วยการสนับสนุนช่วงเวลา

การคิวรี Graphite

หมายเหตุ: เครื่องมือ Graphite ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม graphite ลงในแฟล็ก --enabled-tools ของคุณ

  • คิวรี Graphite: ดำเนินการคิวรี Graphite render API กับแหล่งข้อมูล Graphite
  • แสดงรายการเมตริก Graphite: เรียกดูและค้นพบเส้นทางเมตริก Graphite
  • แสดงรายการแท็ก Graphite: แสดงรายการแท็ก Graphite และค่าแท็กที่พร้อมใช้งาน
  • คิวรีความหนาแน่น Graphite: คิวรีความหนาแน่นของเมตริก Graphite สำหรับรูปแบบที่กำหนด

การคิวรี Athena

หมายเหตุ: เครื่องมือ Athena ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม athena ลงในแฟล็ก --enabled-tools ของคุณ

  • แสดงรายการแคตตาล็อก Athena: ค้นพบแคตตาล็อกข้อมูลที่พร้อมใช้งาน (เช่น AwsDataCatalog, ตัวเชื่อมต่อ Iceberg)
  • แสดงรายการฐานข้อมูล Athena: แสดงรายการฐานข้อมูลในแคตตาล็อก Athena
  • แสดงรายการตาราง Athena: แสดงรายการตารางในฐานข้อมูล Athena
  • อธิบายตาราง Athena: รับชื่อคอลัมน์สำหรับตาราง Athena
  • คิวรี Athena: ดำเนินการคิวรี SQL กับ Amazon Athena ผ่าน Grafana ด้วยการแทนที่แมโคร การบังคับใช้ขีดจำกัด และการสนับสนุนตัวแปรเทมเพลต

การคิวรี Snowflake

หมายเหตุ: เครื่องมือ Snowflake ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม snowflake ลงในแฟล็ก --enabled-tools ของคุณ

คิวรีผ่านแหล่งข้อมูล Snowflake ของ Grafana (ปลั๊กอิน Grafana Enterprise grafana-snowflake-datasource) ดังนั้นการตรวจสอบสิทธิ์จึงถูกจัดการโดยการกำหนดค่าแหล่งข้อมูลใน Grafana — เซิร์ฟเวอร์ MCP ไม่เห็นข้อมูลประจำตัว นี่เป็นโมเดลเดียวกับที่ใช้สำหรับเครื่องมือ ClickHouse

  • แสดงรายการตาราง Snowflake: ค้นพบตาราง (พร้อมฐานข้อมูล สคีมา ชนิด จำนวนแถว และขนาด) ผ่าน INFORMATION_SCHEMA.TABLES ตัวกรองฐานข้อมูล/สคีมาเพิ่มเติม
  • อธิบายสคีมาตาราง: รับชื่อคอลัมน์ ประเภทข้อมูล ความสามารถในการเป็นค่าว่าง ค่าเริ่มต้น และความคิดเห็นสำหรับตาราง Snowflake
  • คิวรี Snowflake: ดำเนินการคิวรี SQL ด้วยการสนับสนุนการแทนที่แมโครและตัวแปร มีประโยชน์สำหรับการคิวรีตารางเหตุการณ์ของ Snowflake (เช่น SNOWFLAKE.TELEMETRY.EVENTS) สำหรับบันทึกและการติดตาม หรือตารางผู้ใช้ใดๆ
    • แมโครที่รองรับ: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (วินาที), $__interval_ms และ ${varname} สำหรับการแทนที่ตัวแปรเทมเพลต

การคิวรี Elasticsearch/OpenSearch

หมายเหตุ: เครื่องมือ Elasticsearch/OpenSearch ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม elasticsearch ลงในแฟล็ก --enabled-tools ของคุณ

  • คิวรี Elasticsearch/OpenSearch: ดำเนินการคิวรีค้นหากับแหล่งข้อมูล Elasticsearch หรือ OpenSearch โดยใช้ไวยากรณ์คิวรี Lucene หรือ Elasticsearch Query DSL รองรับการกรองตามช่วงเวลาและดึงบันทึก เมตริก หรือข้อมูลที่จัดทำดัชนีใดๆ ส่งคืนเอกสารพร้อมดัชนี ID ฟิลด์ต้นทาง และคะแนนความเกี่ยวข้องเพิ่มเติม

การคิวรี Quickwit

หมายเหตุ: เครื่องมือ Quickwit ถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้เพิ่ม quickwit ลงในแฟล็ก --enabled-tools ของคุณ

  • คิวรี Quickwit: ดำเนินการคิวรีค้นหากับแหล่งข้อมูล Quickwit โดยใช้ไวยากรณ์คิวรี Lucene หรือ Query DSL ที่เข้ากันได้กับ Elasticsearch บางส่วน รองรับการกรองตามช่วงเวลาและดึงบันทึกหรือเอกสารที่จัดทำดัชนีอื่นๆ ส่งคืนเอกสารพร้อมดัชนี ID ฟิลด์ต้นทาง และคะแนนความเกี่ยวข้องเพิ่มเติม

เหตุการณ์

  • ค้นหา สร้าง และอัปเดตเหตุการณ์: จัดการเหตุการณ์ใน Grafana Incident รวมถึงการค้นหา การสร้าง และการเพิ่มกิจกรรมลงในเหตุการณ์

การสืบสวน Sift

  • แสดงรายการการสืบสวน Sift: ดึงรายการการสืบสวน Sift พร้อมการสนับสนุนพารามิเตอร์จำกัด
  • รับการสืบสวน Sift: ดึงรายละเอียดของการสืบสวน Sift เฉพาะโดย UUID
  • รับการวิเคราะห์ Sift: ดึงการวิเคราะห์เฉพาะจากการสืบสวน Sift
  • ค้นหารูปแบบข้อผิดพลาดในบันทึก: ตรวจจับรูปแบบข้อผิดพลาดที่เพิ่มขึ้นในบันทึก Loki โดยใช้ Sift
  • ค้นหาคำขอที่ช้า: ตรวจจับคำขอที่ช้าโดยใช้ Sift (Tempo)

การแจ้งเตือน

  • แสดงรายการและดึงข้อมูลกฎการแจ้งเตือน: ดูกฎการแจ้งเตือนและสถานะ (กำลังทำงาน/ปกติ/ข้อผิดพลาด/ฯลฯ) ใน Grafana รองรับทั้งกฎที่จัดการโดย Grafana และกฎที่จัดการโดยแหล่งข้อมูลจากแหล่งข้อมูล Prometheus หรือ Loki
  • สร้างและอัปเดตกฎการแจ้งเตือน: สร้างกฎการแจ้งเตือนใหม่หรือแก้ไขกฎที่มีอยู่
  • ลบกฎการแจ้งเตือน: ลบกฎการแจ้งเตือนตาม UID
  • จัดการการกำหนดเส้นทางการแจ้งเตือน: ดูนโยบายการแจ้งเตือน จุดติดต่อ และช่วงเวลา รองรับทั้งจุดติดต่อที่จัดการโดย Grafana และผู้รับจากแหล่งข้อมูล Alertmanager ภายนอก (Prometheus Alertmanager, Mimir, Cortex)

Grafana OnCall

  • แสดงรายการและจัดการตารางเวลา: ดูและจัดการตารางเวลา on-call ใน Grafana OnCall
  • รับรายละเอียดกะ: ดึงข้อมูลรายละเอียดเกี่ยวกับกะ on-call เฉพาะ
  • รับผู้ใช้ on-call ปัจจุบัน: ดูว่าผู้ใช้คนใดกำลัง on-call สำหรับตารางเวลา
  • แสดงรายการทีมและผู้ใช้: ดูทีมและผู้ใช้ OnCall ทั้งหมด
  • แสดงรายการกลุ่มการแจ้งเตือน: ดูและกรองกลุ่มการแจ้งเตือนจาก Grafana OnCall ตามเกณฑ์ต่างๆ รวมถึงสถานะ การรวม ป้ายกำกับ และช่วงเวลา
  • รับรายละเอียดกลุ่มการแจ้งเตือน: ดึงข้อมูลรายละเอียดเกี่ยวกับกลุ่มการแจ้งเตือนเฉพาะโดย ID

ผู้ดูแลระบบ

หมายเหตุ: เครื่องมือผู้ดูแลระบบถูก ปิดใช้งานโดยค่าเริ่มต้น หากต้องการเปิดใช้งาน ให้รวม admin ไว้ในแฟล็ก --enabled-tools ของคุณ

  • แสดงรายการทีม: ดูทีมที่กำหนดค่าทั้งหมดใน Grafana
  • แสดงรายการผู้ใช้: ดูผู้ใช้ทั้งหมดในองค์กรใน Grafana
  • แสดงรายการบทบาททั้งหมด: แสดงรายการบทบาท Grafana ทั้งหมด พร้อมตัวกรองเพิ่มเติมสำหรับบทบาทที่มอบหมายได้
  • รับรายละเอียดบทบาท: รับรายละเอียดสำหรับบทบาท Grafana เฉพาะโดย UID
  • แสดงรายการการมอบหมายสำหรับบทบาท: แสดงรายการผู้ใช้ ทีม และบัญชีบริการทั้งหมดที่ได้รับมอบหมายให้กับบทบาท
  • แสดงรายการบทบาทสำหรับผู้ใช้: แสดงรายการบทบาททั้งหมดที่มอบหมายให้กับผู้ใช้หนึ่งรายขึ้นไป
  • แสดงรายการบทบาทสำหรับทีม: แสดงรายการบทบาททั้งหมดที่มอบหมายให้กับทีมหนึ่งทีมขึ้นไป
  • แสดงรายการสิทธิ์สำหรับทรัพยากร: แสดงรายการสิทธิ์ทั้งหมดที่กำหนดไว้สำหรับทรัพยากรเฉพาะ (แดชบอร์ด แหล่งข้อมูล โฟลเดอร์ ฯลฯ)
  • อธิบายทรัพยากร Grafana: แสดงรายการสิทธิ์ที่พร้อมใช้งานและความสามารถในการมอบหมายสำหรับประเภททรัพยากร

การนำทาง

  • สร้างดีพลิงก์: สร้าง URL ดีพลิงก์ที่แม่นยำสำหรับทรัพยากร Grafana แทนที่จะพึ่งพาการเดา URL ของ LLM
    • ลิงก์แดชบอร์ด: สร้างลิงก์ตรงไปยังแดชบอร์ดโดยใช้ UID (เช่น http://localhost:3000/d/dashboard-uid)
    • ลิงก์พาเนล: สร้างลิงก์ไปยังพาเนลเฉพาะภายในแดชบอร์ดด้วยพารามิเตอร์ viewPanel (เช่น http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • ลิงก์ Explore: สร้างลิงก์ไปยัง Grafana Explore พร้อมแหล่งข้อมูลที่กำหนดค่าไว้ล่วงหน้า (เช่น http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • รองรับช่วงเวลา: เพิ่มพารามิเตอร์ช่วงเวลาลงในลิงก์ (from=now-1h&to=now)
    • พารามิเตอร์กำหนดเอง: รวมพารามิเตอร์คิวรีเพิ่มเติม เช่น ตัวแปรแดชบอร์ดหรือช่วงเวลารีเฟรช

คำอธิบายประกอบ

  • รับคำอธิบายประกอบ: คิวรีคำอธิบายประกอบด้วยตัวกรอง รองรับช่วงเวลา, UID แดชบอร์ด, แท็ก และโหมดการจับคู่
  • สร้างคำอธิบายประกอบ: สร้างคำอธิบายประกอบใหม่บนแดชบอร์ดหรือพาเนล
  • สร้างคำอธิบายประกอบ Graphite: สร้างคำอธิบายประกอบโดยใช้รูปแบบ Graphite (what, when, tags, data)
  • อัปเดตคำอธิบายประกอบ: แทนที่ฟิลด์ทั้งหมดของคำอธิบายประกอบที่มีอยู่ (อัปเดตแบบเต็ม)
  • แพตช์คำอธิบายประกอบ: อัปเดตเฉพาะฟิลด์ที่ระบุของคำอธิบายประกอบ (อัปเดตบางส่วน)
  • รับแท็กคำอธิบายประกอบ: แสดงรายการแท็กคำอธิบายประกอบที่มีอยู่พร้อมตัวกรองเพิ่มเติม

สแนปช็อต

  • รายการสแนปช็อต: แสดงรายการสแนปช็อตแดชบอร์ดพร้อมตัวกรองคิวรีและขีดจำกัดเพิ่มเติม
  • รับสแนปช็อต: ดึงข้อมูลเมตาดาต้าสแนปช็อตและเพย์โหลดแดชบอร์ดด้วยคีย์สแนปช็อต
  • สร้างสแนปช็อต: สร้างสแนปช็อตแดชบอร์ดจากเพย์โหลดแดชบอร์ดแบบเต็ม พร้อมตัวเลือกการหมดอายุและสแนปช็อตภายนอกเพิ่มเติม
  • ลบสแนปช็อต: ลบสแนปช็อตด้วยคีย์สแนปช็อต

การเรนเดอร์

  • รับภาพพาเนลหรือแดชบอร์ด: เรนเดอร์พาเนลแดชบอร์ด Grafana หรือแดชบอร์ดแบบเต็มเป็นภาพ PNG ส่งคืนภาพเป็นข้อมูลที่เข้ารหัส base64 สำหรับใช้ในรายงาน การแจ้งเตือน หรืองานนำเสนอ รองรับการปรับแต่งขนาด, ช่วงเวลา, ธีม, มาตราส่วน และตัวแปรแดชบอร์ด นอกจากนี้ยังรองรับการเรนเดอร์แดชบอร์ดที่ยังไม่ได้ปรับใช้จากสาขาของที่เก็บการจัดเตรียม (เช่น ตัวอย่าง PR ของ git-sync) ผ่านพารามิเตอร์ provisioningPreview เพิ่มเติม
    • หมายเหตุ: ต้องติดตั้งและกำหนดค่าบริการ Grafana Image Renderer ไว้

การจัดเตรียม

  • รายการที่เก็บการจัดเตรียม: แสดงรายการที่เก็บการจัดเตรียมที่กำหนดค่าสำหรับอินสแตนซ์ Grafana นี้ (เช่น แหล่ง git-sync) โดยส่งคืน slug ของแต่ละที่เก็บพร้อมกับ URL ต้นทาง, สาขา, พาธ, สถานะการซิงค์ และความสมบูรณ์
  • ตรวจสอบไฟล์การจัดเตรียม: ทดลองปรับใช้ไฟล์จากที่เก็บการจัดเตรียมที่สาขาหรือคอมมิตที่กำหนด ส่งคืนว่าจะได้รับการยอมรับหรือไม่, การดำเนินการกับทรัพยากร (สร้าง/อัปเดต), ประเภททรัพยากรเป้าหมาย และข้อผิดพลาดในการตรวจสอบที่มีโครงสร้าง — ซึ่งเป็นพื้นผิวการรับเข้าเดียวกันกับที่ตัวแสดงความคิดเห็น PR ของ Grafana ใช้

รายการเครื่องมือสามารถกำหนดค่าได้ คุณจึงเลือกได้ว่าต้องการให้เครื่องมือใดพร้อมใช้งานสำหรับไคลเอนต์ MCP สิ่งนี้มีประโยชน์หากคุณไม่ได้ใช้ฟังก์ชันบางอย่าง หรือหากคุณไม่ต้องการใช้พื้นที่หน้าต่างบริบทมากเกินไป หากต้องการปิดใช้งานหมวดหมู่ของเครื่องมือ ให้ใช้แฟล็ก --disable-<category> เมื่อเริ่มต้นเซิร์ฟเวอร์ ตัวอย่างเช่น หากต้องการปิดใช้งาน เครื่องมือ OnCall ให้ใช้ --disable-oncall หรือหากต้องการปิดใช้งานการสร้างดีพลิงก์การนำทาง ให้ใช้ --disable-navigation

สิทธิ์ RBAC

แต่ละเครื่องมือต้องการสิทธิ์ RBAC เฉพาะเพื่อให้ทำงานได้อย่างถูกต้อง เมื่อสร้างบัญชีบริการสำหรับเซิร์ฟเวอร์ MCP ตรวจสอบให้แน่ใจว่ามีสิทธิ์ที่จำเป็นตามเครื่องมือที่คุณวางแผนจะใช้ สิทธิ์ที่แสดงเป็นรายการคือการดำเนินการขั้นต่ำที่จำเป็น - คุณอาจต้องมีขอบเขตที่เหมาะสมด้วย (เช่น datasources:*, dashboards:*, folders:*) ขึ้นอยู่กับกรณีการใช้งานของคุณ

เคล็ดลับ: หากคุณไม่คุ้นเคยกับ RBAC ของ Grafana หรือต้องการการตั้งค่าที่รวดเร็วและง่ายกว่าแทนที่จะกำหนดค่าขอบเขตย่อยจำนวนมาก คุณสามารถกำหนดบทบาทในตัว เช่น Editor ให้กับบัญชีบริการ บทบาท Editor ให้สิทธิ์การอ่าน/เขียนแบบกว้างที่จะอนุญาตการดำเนินการเซิร์ฟเวอร์ MCP ส่วนใหญ่ ซึ่งมีความละเอียดน้อยกว่า (และดังนั้นจึงมีข้อจำกัดน้อยกว่า) กว่าขอบเขตที่ปรับใช้ด้วยตนเอง ดังนั้นให้ใช้เฉพาะเมื่อความสะดวกมีความสำคัญมากกว่าการเข้าถึงแบบจำกัดสิทธิ์ขั้นต่ำอย่างเคร่งครัด

หมายเหตุ: เครื่องมือ Grafana Incident และ Sift ใช้บทบาท Grafana พื้นฐานแทนสิทธิ์ RBAC แบบละเอียด:

  • บทบาท Viewer: จำเป็นสำหรับการดำเนินการแบบอ่านอย่างเดียว (รายการเหตุการณ์, รับการสืบสวน)
  • บทบาท Editor: จำเป็นสำหรับการดำเนินการเขียน (สร้างเหตุการณ์, แก้ไขการสืบสวน)

สำหรับข้อมูลเพิ่มเติมเกี่ยวกับ RBAC ของ Grafana โปรดดู เอกสารอย่างเป็นทางการ

ขอบเขต RBAC

ขอบเขตกำหนดทรัพยากรเฉพาะที่สิทธิ์นำไปใช้ แต่ละการดำเนินการต้องการทั้งสิทธิ์และการรวมขอบเขตที่เหมาะสม

รูปแบบขอบเขตทั่วไป:

  • การเข้าถึงแบบกว้าง: ใช้ไวลด์การ์ด * สำหรับการเข้าถึงทั่วทั้งองค์กร

    • datasources:* - เข้าถึงแหล่งข้อมูลทั้งหมด
    • dashboards:* - เข้าถึงแดชบอร์ดทั้งหมด
    • folders:* - เข้าถึงโฟลเดอร์ทั้งหมด
    • teams:* - เข้าถึงทีมทั้งหมด

  • การเข้าถึงแบบจำกัด: ใช้ UID หรือ ID เฉพาะเพื่อจำกัดการเข้าถึงทรัพยากรแต่ละรายการ

    • datasources:uid:prometheus-uid - เข้าถึงเฉพาะแหล่งข้อมูล Prometheus ที่ระบุ
    • dashboards:uid:abc123 - เข้าถึงเฉพาะแดชบอร์ดที่มี UID abc123
    • folders:uid:xyz789 - เข้าถึงเฉพาะโฟลเดอร์ที่มี UID xyz789
    • teams:id:5 - เข้าถึงเฉพาะทีมที่มี ID 5
    • global.users:id:123 - เข้าถึงเฉพาะผู้ใช้ที่มี ID 123

ตัวอย่าง:

  • การเข้าถึงเซิร์ฟเวอร์ MCP แบบเต็ม: ให้สิทธิ์แบบกว้างสำหรับเครื่องมือทั้งหมด

    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)

  • การเข้าถึงแหล่งข้อมูลแบบจำกัด: คิวรีเฉพาะอินสแตนซ์ Prometheus และ Loki ที่ระบุ

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

  • การเข้าถึงเฉพาะแดชบอร์ด: อ่านเฉพาะแดชบอร์ดที่ระบุ

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

เครื่องมือ

เครื่องมือหมวดหมู่คำอธิบายสิทธิ์ RBAC ที่จำเป็นขอบเขตที่จำเป็น
list_teamsผู้ดูแลระบบแสดงรายการทีมทั้งหมดteams:readteams:* หรือ teams:id:1
list_users_by_orgผู้ดูแลระบบแสดงรายการผู้ใช้ทั้งหมดในองค์กรusers:readglobal.users:* หรือ global.users:id:123
list_all_rolesผู้ดูแลระบบแสดงรายการบทบาท Grafana ทั้งหมดroles:readroles:*
get_role_detailsผู้ดูแลระบบดูรายละเอียดของบทบาท Grafanaroles:readroles:uid:editor
get_role_assignmentsผู้ดูแลระบบแสดงรายการมอบหมายสำหรับบทบาทroles:readroles:uid:editor
list_user_rolesผู้ดูแลระบบแสดงรายการบทบาทสำหรับผู้ใช้roles:readglobal.users:id:123
list_team_rolesผู้ดูแลระบบแสดงรายการบทบาทสำหรับทีมroles:readteams:id:7
get_resource_permissionsผู้ดูแลระบบแสดงรายการสิทธิ์สำหรับทรัพยากรpermissions:readdashboards:uid:abcd1234
get_resource_descriptionผู้ดูแลระบบอธิบายชนิดทรัพยากร Grafanapermissions:readdashboards:*
search_dashboardsค้นหาค้นหาแดชบอร์ดdashboards:readdashboards:* หรือ dashboards:uid:abc123
get_dashboard_by_uidแดชบอร์ดรับแดชบอร์ดด้วย uiddashboards:readdashboards:uid:abc123
update_dashboardแดชบอร์ดอัปเดตหรือสร้างแดชบอร์ดใหม่dashboards:create, dashboards:writedashboards:*, folders:* หรือ folders:uid:xyz789
get_dashboard_panel_queriesแดชบอร์ดรับชื่อแผง, คิวรี, UID แหล่งข้อมูล และชนิดจากแดชบอร์ดdashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*ดำเนินการคิวรีแผงแดชบอร์ดหนึ่งรายการขึ้นไปdashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyแดชบอร์ดแยกส่วนเฉพาะของแดชบอร์ดโดยใช้นิพจน์ JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryแดชบอร์ดรับสรุปย่อของแดชบอร์ดโดยไม่มี JSON เต็มdashboards:readdashboards:uid:abc123
list_datasourcesแหล่งข้อมูลแสดงรายการแหล่งข้อมูลdatasources:readdatasources:*
get_datasourceแหล่งข้อมูลรับแหล่งข้อมูลด้วย UID หรือชื่อdatasources:readdatasources:uid:prometheus-uid
get_query_examplesตัวอย่าง*รับคิวรีตัวอย่างสำหรับชนิดแหล่งข้อมูลdatasources:readdatasources:*
query_prometheusPrometheusดำเนินการคิวรีกับแหล่งข้อมูล Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusแสดงรายการเมตาดาต้าของเมตริกdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusแสดงรายการชื่อเมตริกที่ใช้ได้datasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusแสดงรายการชื่อเลเบิลที่ตรงกับตัวเลือกdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusแสดงรายการค่าสำหรับเลเบิลที่ระบุdatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusคำนวณค่าเปอร์เซ็นไทล์ของฮิสโตแกรมdatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentแสดงรายการเหตุการณ์ใน Grafana Incidentบทบาท ViewerN/A
create_incidentIncidentสร้างเหตุการณ์ใน Grafana Incidentบทบาท EditorN/A
add_activity_to_incidentIncidentเพิ่มรายการกิจกรรมไปยังเหตุการณ์ใน Grafana Incidentบทบาท EditorN/A
get_incidentIncidentรับเหตุการณ์เดียวด้วย IDบทบาท ViewerN/A
query_loki_logsLokiคิวรีและดึงข้อมูลล็อกโดยใช้ LogQL (คิวรีล็อกหรือเมตริก)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiแสดงรายการชื่อเลเบิลทั้งหมดที่ใช้ได้ในล็อกdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiแสดงรายการค่าสำหรับเลเบิลล็อกที่ระบุdatasources:querydatasources:uid:loki-uid
query_loki_statsLokiรับสถิติเกี่ยวกับสตรีมล็อกdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiคิวรีรูปแบบล็อกที่ตรวจพบเพื่อระบุโครงสร้างทั่วไปdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiตรวจสอบกลยุทธ์เลเบิลของ Loki (สดหรือคงที่) และวินิจฉัยประสิทธิภาพคิวรีเพิ่มเติมdatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configการตั้งค่าสร้างส่วนย่อย loki.process ของ Alloy ที่บังคับใช้เลเบิลที่อนุมัติN/AN/A
query_influxdbInfluxDBคิวรี InfluxDB โดยใช้ InfluxQL (v1) หรือ Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*แสดงรายการตารางในฐานข้อมูล ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*รับสกีมาของตารางพร้อมชนิดคอลัมน์datasources:querydatasources:uid:*
query_clickhouseClickHouse*ดำเนินการคิวรี SQL ด้วยการแทนที่แมโครdatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*แสดงรายการเนมสเปซ AWS CloudWatch ที่ใช้ได้datasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*แสดงรายการมิติข้อมูลสำหรับเมตริกdatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*ดำเนินการคิวรีเมตริกของ CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*แสดงรายการแค็ตตาล็อกข้อมูล Athena ที่พร้อมใช้งานdatasources:querydatasources:uid:*
list_athena_databasesAthena*แสดงรายการฐานข้อมูลในแค็ตตาล็อก Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*แสดงรายการตารางในฐานข้อมูล Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*รับชื่อคอลัมน์สำหรับตาราง Athenadatasources:querydatasources:uid:*
query_athenaAthena*ดำเนินการคิวรี SQL ด้วยการแทนที่แมโครdatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*คิวรี Elasticsearch หรือ OpenSearch โดยใช้ไวยากรณ์ Lucene หรือ Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*คิวรี Quickwit โดยใช้ไวยากรณ์ Lucene หรือ Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*แสดงรายการตารางในฐานข้อมูล/สกีมา Snowflake ผ่าน INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*รับสกีมาตาราง (ประเภทคอลัมน์, การอนุญาตให้เป็นค่าว่าง, ค่าเริ่มต้น, ความคิดเห็น)datasources:querydatasources:uid:*
query_snowflakeSnowflake*ดำเนินการคิวรี SQL ด้วยการแทนที่แมโคร/ตัวแปรdatasources:querydatasources:uid:*
alerting_manage_rulesการแจ้งเตือนจัดการกฎการแจ้งเตือน (แสดงรายการ, รับ, เวอร์ชัน, สร้าง, อัปเดต, ลบ)alert.rules:read + alert.rules:write สำหรับการเปลี่ยนแปลงfolders:* หรือ folders:uid:alerts-folder
alerting_manage_routingการแจ้งเตือนจัดการนโยบายการแจ้งเตือน, จุดติดต่อ, และช่วงเวลาalert.notifications:readขอบเขตทั่วโลก
list_oncall_schedulesOnCallแสดงรายการตารางเวลาจาก Grafana OnCallgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
get_oncall_shiftOnCallรับรายละเอียดสำหรับกะ OnCall เฉพาะgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
get_current_oncall_usersOnCallรับผู้ใช้ที่กำลังปฏิบัติหน้าที่สำหรับตารางเวลาเฉพาะgrafana-oncall-app.schedules:readขอบเขตเฉพาะปลั๊กอิน
list_oncall_teamsOnCallแสดงรายการทีมจาก Grafana OnCallgrafana-oncall-app.user-settings:readขอบเขตเฉพาะปลั๊กอิน
list_oncall_usersOnCallแสดงรายการผู้ใช้จาก Grafana OnCallgrafana-oncall-app.user-settings:readขอบเขตเฉพาะปลั๊กอิน
list_alert_groupsOnCallแสดงรายการกลุ่มการแจ้งเตือนจาก Grafana OnCall พร้อมตัวเลือกการกรองgrafana-oncall-app.alert-groups:readขอบเขตเฉพาะปลั๊กอิน
get_alert_groupOnCallรับกลุ่มการแจ้งเตือนเฉพาะจาก Grafana OnCall โดยใช้ IDgrafana-oncall-app.alert-groups:readขอบเขตเฉพาะปลั๊กอิน
get_sift_investigationSiftดึงข้อมูลการสืบสวน Sift ที่มีอยู่โดยใช้ UUIDบทบาทผู้ชมN/A
get_sift_analysisSiftดึงข้อมูลการวิเคราะห์เฉพาะจากการสืบสวน Siftบทบาทผู้ชมN/A
list_sift_investigationsSiftดึงข้อมูลรายการการสืบสวน Sift พร้อมตัวเลือกการจำกัดจำนวนบทบาทผู้ชมN/A
find_error_pattern_logsSiftค้นหารูปแบบข้อผิดพลาดที่เพิ่มขึ้นในบันทึก Lokiบทบาทผู้แก้ไขN/A
find_slow_requestsSiftค้นหาคำขอที่ช้าจากแหล่งข้อมูล tempo ที่เกี่ยวข้องบทบาทผู้แก้ไขN/A
list_pyroscope_label_namesPyroscopeแสดงรายการชื่อป้ายกำกับที่ตรงกับตัวเลือกdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeแสดงรายการค่าป้ายกำกับที่ตรงกับตัวเลือกสำหรับชื่อป้ายกำกับdatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeแสดงรายการประเภทโปรไฟล์ที่พร้อมใช้งานdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeคิวรีโปรไฟล์, เมตริก, หรือทั้งสองอย่างจาก Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsรับสรุปการยืนยันสำหรับเอนทิตีที่กำหนดสิทธิ์เฉพาะปลั๊กอินขอบเขตเฉพาะปลั๊กอิน
generate_deeplinkการนำทางสร้าง URL deeplink ที่แม่นยำสำหรับทรัพยากร Grafanaไม่มี (การสร้าง URL แบบอ่านอย่างเดียว)N/A
get_annotationsคำอธิบายประกอบดึงข้อมูลคำอธิบายประกอบพร้อมตัวกรองannotations:readannotations:* หรือ annotations:id:123
create_annotationคำอธิบายประกอบสร้างคำอธิบายประกอบใหม่ (รูปแบบมาตรฐานหรือ Graphite)annotations:writeannotations:*
update_annotationคำอธิบายประกอบอัปเดตฟิลด์เฉพาะของคำอธิบายประกอบ (การอัปเดตบางส่วน)annotations:writeannotations:*
get_annotation_tagsคำอธิบายประกอบแสดงรายการแท็กคำอธิบายประกอบพร้อมตัวเลือกการกรองannotations:readannotations:*
list_snapshotsสแนปช็อตแสดงรายการสแนปช็อตแดชบอร์ดพร้อมตัวเลือกการคิวรีและการจำกัดจำนวนdashboards:readdashboards:* หรือ dashboards:uid:abc123
get_snapshotสแนปช็อตรับข้อมูลเมตาสแนปช็อตและเพย์โหลดแดชบอร์ดโดยใช้คีย์สแนปช็อตdashboards:readdashboards:* หรือ dashboards:uid:abc123
create_snapshotสแนปช็อตสร้างสแนปช็อตแดชบอร์ดจากเพย์โหลดแดชบอร์ดแบบเต็มdashboards:writedashboards:* หรือ dashboards:uid:abc123
delete_snapshotสแนปช็อตลบสแนปช็อตแดชบอร์ดโดยใช้คีย์สแนปช็อตdashboards:writedashboards:* หรือ dashboards:uid:abc123
get_panel_imageการเรนเดอร์เรนเดอร์แดชบอร์ดหรือพาเนลที่จัดเก็บไว้ — หรือตัวอย่างการจัดเตรียมจากสาขาของที่เก็บ — เป็นรูปภาพ PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesการจัดเตรียมแสดงรายการที่เก็บการจัดเตรียม (เช่น แหล่ง git-sync) พร้อม URL แหล่งที่มา, สาขา, สถานะการซิงค์, และความสมบูรณ์provisioning.repositories:readN/A
validate_provisioning_fileการจัดเตรียมทดลองปรับใช้ไฟล์จากที่เก็บการจัดเตรียมและรายงานข้อผิดพลาดในการตรวจสอบการยอมรับprovisioning.repositories:readไม่มี
* ปิดใช้งานโดยค่าเริ่มต้น เพิ่มหมวดหมู่ไปยัง --enabled-tools เพื่อเปิดใช้งาน

การอ้างอิงแฟล็ก CLI

ไบนารี mcp-grafana รองรับแฟล็กบรรทัดคำสั่งต่างๆ สำหรับการกำหนดค่า:

ตัวเลือกการขนส่ง:

  • -t, --transport: ประเภทการขนส่ง (stdio, sse, หรือ streamable-http) - ค่าเริ่มต้น: stdio
  • --address: โฮสต์และพอร์ตสำหรับเซิร์ฟเวอร์ SSE/streamable-http - ค่าเริ่มต้น: localhost:8000
  • --base-path: เส้นทางฐานสำหรับเซิร์ฟเวอร์ SSE/streamable-http
  • --endpoint-path: เส้นทางปลายทางสำหรับเซิร์ฟเวอร์ streamable-http - ค่าเริ่มต้น: /

การดีบักและการบันทึก:

  • --debug: เปิดใช้งานโหมดดีบักสำหรับการบันทึกคำขอ/การตอบกลับ HTTP โดยละเอียด
  • --log-level: ระดับการบันทึก (debug, info, warn, error) - ค่าเริ่มต้น: info

การสังเกตการณ์:

  • --metrics: เปิดใช้งานปลายทางเมตริก Prometheus ที่ /metrics
  • --metrics-address: ที่อยู่แยกต่างหากสำหรับเซิร์ฟเวอร์เมตริก (เช่น :9090) หากเว้นว่างไว้ เมตริกจะถูกให้บริการบนเซิร์ฟเวอร์หลัก
  • --slow-request-threshold: บันทึกเหตุการณ์เมื่อคำขอ MCP ใดๆ (การเรียกใช้เครื่องมือ, รายการ, การอ่านทรัพยากร ฯลฯ) ใช้เวลานานกว่าระยะเวลานี้ ยอมรับสตริงระยะเวลา Go (เช่น 500ms, 5s) ค่าเริ่มต้น 0 ปิดใช้งานการบันทึกคำขอที่ช้า ดูส่วน การบันทึกคำขอที่ช้า
  • --slow-request-log-level: ระดับการบันทึกสำหรับเหตุการณ์คำขอที่ช้า (info หรือ warn) - ค่าเริ่มต้น: warn

การจัดการเซสชัน:

  • --session-idle-timeout-minutes: ระยะหมดเวลาไม่ได้ใช้งานเซสชันเป็นนาที เซสชันที่ไม่มีกิจกรรมในช่วงเวลานี้จะถูกเก็บกวาดโดยอัตโนมัติ - ค่าเริ่มต้น: 30 ตั้งค่าเป็น 0 เพื่อปิดใช้งานการเก็บกวาดเซสชัน เกี่ยวข้องเฉพาะกับการขนส่ง SSE และ streamable-http

การกำหนดค่าเครื่องมือ:

  • --enabled-tools: รายการหมวดหมู่ที่เปิดใช้งานคั่นด้วยเครื่องหมายจุลภาค - ค่าเริ่มต้น: ทุกหมวดหมู่ยกเว้น admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, และ snowflake หากต้องการเปิดใช้งานหมวดหมู่ที่ปิดใช้งาน ให้เพิ่มลงในรายการ (เช่น "search,datasource,...,snowflake")
  • --max-loki-log-limit: จำนวนบรรทัดบันทึกสูงสุดที่ส่งคืนต่อการเรียก query_loki_logs - ค่าเริ่มต้น: 100 หมายเหตุ: ตั้งค่านี้ให้ต่ำกว่า max_entries_limit_per_query ฝั่งเซิร์ฟเวอร์ของ Loki อย่างน้อย 1 เพื่อให้สามารถตรวจจับการตัดทอนได้ (เครื่องมือร้องขอ limit+1 ภายในเพื่อตรวจจับว่ามีข้อมูลเพิ่มเติมหรือไม่)
  • --disable-search: ปิดใช้งานเครื่องมือค้นหา
  • --disable-datasource: ปิดใช้งานเครื่องมือแหล่งข้อมูล
  • --disable-incident: ปิดใช้งานเครื่องมือเหตุการณ์
  • --disable-prometheus: ปิดใช้งานเครื่องมือ prometheus
  • --disable-write: ปิดใช้งานเครื่องมือเขียน (การดำเนินการสร้าง/อัปเดต)
  • --disable-loki: ปิดใช้งานเครื่องมือ loki
  • --disable-elasticsearch: ปิดใช้งานเครื่องมือ elasticsearch และ opensearch
  • --disable-quickwit: ปิดใช้งานเครื่องมือ quickwit
  • --disable-influxdb: ปิดใช้งานเครื่องมือ InfluxDB
  • --disable-alerting: ปิดใช้งานเครื่องมือแจ้งเตือน
  • --disable-dashboard: ปิดใช้งานเครื่องมือแดชบอร์ด
  • --disable-oncall: ปิดใช้งานเครื่องมือ oncall
  • --disable-asserts: ปิดใช้งานเครื่องมือ asserts
  • --disable-sift: ปิดใช้งานเครื่องมือ sift
  • --disable-admin: ปิดใช้งานเครื่องมือผู้ดูแลระบบ
  • --disable-pyroscope: ปิดใช้งานเครื่องมือ pyroscope
  • --disable-navigation: ปิดใช้งานเครื่องมือการนำทาง
  • --disable-rendering: ปิดใช้งานเครื่องมือการเรนเดอร์ (การส่งออกภาพแผง/แดชบอร์ด)
  • --disable-snapshot: ปิดใช้งานเครื่องมือสแนปช็อต
  • --disable-cloudwatch: ปิดใช้งานเครื่องมือ CloudWatch
  • --disable-examples: ปิดใช้งานเครื่องมือตัวอย่างคิวรี
  • --disable-clickhouse: ปิดใช้งานเครื่องมือ ClickHouse
  • --disable-snowflake: ปิดใช้งานเครื่องมือ Snowflake
  • --disable-runpanelquery: ปิดใช้งานเครื่องมือรันคิวรีแผง
  • --disable-graphite: ปิดใช้งานเครื่องมือ Graphite
  • --disable-athena: ปิดใช้งานเครื่องมือ Athena
  • --disable-provisioning: ปิดใช้งานเครื่องมือการจัดเตรียม

โหมดอ่านอย่างเดียว

แฟล็ก --disable-write ให้วิธีการรันเซิร์ฟเวอร์ MCP ในโหมดอ่านอย่างเดียว ป้องกันการดำเนินการเขียนใดๆ ไปยังอินสแตนซ์ Grafana ของคุณ สิ่งนี้มีประโยชน์สำหรับสถานการณ์ที่คุณต้องการให้การเข้าถึงแบบอ่านอย่างเดียวที่ปลอดภัย เช่น:

  • การใช้บัญชีบริการที่มีสิทธิ์อ่านอย่างเดียวที่จำกัด
  • การให้ผู้ช่วย AI เข้าถึงข้อมูลการสังเกตการณ์โดยไม่มีความสามารถในการแก้ไข
  • การรันในสภาพแวดล้อมการผลิตที่ควรจำกัดการเข้าถึงการเขียน
  • สถานการณ์การทดสอบและพัฒนาที่คุณต้องการป้องกันการแก้ไขโดยไม่ตั้งใจ

เมื่อเปิดใช้งาน --disable-write การดำเนินการเขียนต่อไปนี้จะถูกปิดใช้งาน:

เครื่องมือแดชบอร์ด:

  • update_dashboard

เครื่องมือโฟลเดอร์:

  • create_folder

เครื่องมือเหตุการณ์:

  • create_incident
  • add_activity_to_incident

เครื่องมือแจ้งเตือน:

  • alerting_manage_rules (การดำเนินการสร้าง, อัปเดต, ลบ)

เครื่องมือคำอธิบายประกอบ:

  • create_annotation
  • update_annotation

เครื่องมือ Sift:

  • find_error_pattern_logs (สร้างการตรวจสอบ)
  • find_slow_requests (สร้างการตรวจสอบ)

เครื่องมือสแนปช็อต:

  • create_snapshot
  • delete_snapshot

การดำเนินการอ่านทั้งหมดยังคงใช้งานได้ ทำให้คุณสามารถคิวรีแดชบอร์ด รันคิวรี PromQL/LogQL แสดงรายการทรัพยากร และดึงข้อมูลได้

การกำหนดค่า TLS ของไคลเอนต์ (สำหรับการเชื่อมต่อ Grafana):

  • --tls-cert-file: เส้นทางไปยังไฟล์ใบรับรอง TLS สำหรับการตรวจสอบสิทธิ์ไคลเอนต์
  • --tls-key-file: เส้นทางไปยังไฟล์คีย์ส่วนตัว TLS สำหรับการตรวจสอบสิทธิ์ไคลเอนต์
  • --tls-ca-file: เส้นทางไปยังไฟล์ใบรับรอง CA TLS สำหรับการตรวจสอบเซิร์ฟเวอร์
  • --tls-skip-verify: ข้ามการตรวจสอบใบรับรอง TLS (ไม่ปลอดภัย)

การกำหนดค่า TLS ของเซิร์ฟเวอร์ (การขนส่ง streamable-http เท่านั้น):

  • --server.tls-cert-file: เส้นทางไปยังไฟล์ใบรับรอง TLS สำหรับเซิร์ฟเวอร์ HTTPS
  • --server.tls-key-file: เส้นทางไปยังไฟล์คีย์ส่วนตัว TLS สำหรับเซิร์ฟเวอร์ HTTPS

การใช้งาน

เซิร์ฟเวอร์ MCP นี้ทำงานร่วมกับทั้งอินสแตนซ์ Grafana ในเครื่องและ Grafana Cloud สำหรับ Grafana Cloud ให้ใช้ URL อินสแตนซ์ของคุณ (เช่น https://myinstance.grafana.net) แทน http://localhost:3000 ในตัวอย่างการกำหนดค่าด้านล่าง

  1. หากใช้การตรวจสอบสิทธิ์ด้วยโทเค็นบัญชีบริการ ให้สร้างบัญชีบริการใน Grafana ที่มีสิทธิ์เพียงพอในการใช้เครื่องมือที่คุณต้องการใช้ สร้างโทเค็นบัญชีบริการ และคัดลอกไปยังคลิปบอร์ดเพื่อใช้ในไฟล์การกำหนดค่า ทำตาม เอกสารบัญชีบริการ Grafana สำหรับรายละเอียดเกี่ยวกับการสร้างโทเค็นบัญชีบริการ เคล็ดลับ: หากคุณไม่สะดวกใจในการกำหนดค่าขอบเขต RBAC แบบละเอียด ตัวเลือกที่ง่ายกว่า (แต่มีข้อจำกัดน้อยกว่า) คือการกำหนดบทบาท Editor ในตัวให้กับบัญชีบริการ สิ่งนี้ให้สิทธิ์การอ่าน/เขียนแบบกว้างซึ่งครอบคลุมการดำเนินการเซิร์ฟเวอร์ MCP ส่วนใหญ่ — ใช้เมื่อความสะดวกมีน้ำหนักมากกว่าข้อกำหนดสิทธิ์ขั้นต่ำที่เข้มงวด

    หมายเหตุ: ตัวแปรสภาพแวดล้อม GRAFANA_API_KEY เลิกใช้งานแล้วและจะถูกลบออกในเวอร์ชันอนาคต โปรดย้ายไปใช้ GRAFANA_SERVICE_ACCOUNT_TOKEN แทน ชื่อตัวแปรเก่าจะยังคงทำงานเพื่อความเข้ากันได้ย้อนหลัง แต่จะแสดงคำเตือนการเลิกใช้งาน

การอ่านโทเค็นบัญชีบริการจากไฟล์

แทนที่จะส่งโทเค็นแบบอินไลน์ผ่าน GRAFANA_SERVICE_ACCOUNT_TOKEN คุณสามารถชี้ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE ไปยังเส้นทางไฟล์ที่มีโทเค็น ไฟล์จะถูกอ่านใหม่ทุกคำขอ ดังนั้นโทเค็นที่หมุนเวียนจะถูกหยิบขึ้นมาโดยอัตโนมัติโดยไม่ต้องรีสตาร์ทเซิร์ฟเวอร์

สิ่งนี้มีประโยชน์อย่างยิ่งใน Kubernetes ที่ Secret ซึ่งเมาท์เป็นโวลุ่มจะถูกอัปเดตในตำแหน่งเมื่อ Secret พื้นฐานเปลี่ยนแปลง (โดยทั่วไปภายใน ~1 นาที) เมื่อรวมกับแคชไคลเอนต์ต่อคำขอ — ซึ่งคีย์ตามค่าโทเค็น — โทเค็นที่หมุนเวียนจะสร้างไคลเอนต์ใหม่อย่างโปร่งใสโดยไม่ต้องรีสตาร์ทพ็อดและไม่มีเวลาหยุดทำงาน:

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

ช่องว่างโดยรอบ (รวมถึงการขึ้นบรรทัดใหม่ต่อท้าย) จะถูกตัดออกจากเนื้อหาไฟล์ หากตั้งค่าทั้ง GRAFANA_SERVICE_ACCOUNT_TOKEN และ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE โทเค็นแบบอินไลน์จะมีความสำคัญกว่า

การสนับสนุนหลายองค์กร

คุณสามารถระบุองค์กรที่จะโต้ตอบด้วยโดยใช้:

  • ตัวแปรสภาพแวดล้อม: ตั้งค่า GRAFANA_ORG_ID เป็นรหัสองค์กรตัวเลข
  • ส่วนหัว HTTP: ตั้งค่า X-Grafana-Org-Id เมื่อใช้การขนส่ง SSE หรือ streamable HTTP (ส่วนหัวมีความสำคัญกว่าตัวแปรสภาพแวดล้อม - หมายความว่าคุณสามารถตั้งค่าองค์กรเริ่มต้นได้เช่นกัน)

เมื่อระบุรหัสองค์กร เซิร์ฟเวอร์ MCP จะตั้งค่าส่วนหัว X-Grafana-Org-Id ในทุกคำขอไปยัง Grafana เพื่อให้แน่ใจว่าการดำเนินการจะดำเนินการภายในบริบทองค์กรที่ระบุ

ตัวอย่างพร้อมรหัสองค์กร:

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

ส่วนหัว HTTP ที่กำหนดเอง

คุณสามารถเพิ่มส่วนหัว HTTP ตามอำเภอใจไปยังคำขอ Grafana API ทั้งหมดโดยใช้ตัวแปรสภาพแวดล้อม GRAFANA_EXTRA_HEADERS ค่าควรเป็นอ็อบเจกต์ JSON ที่แมปชื่อส่วนหัวกับค่า

ตัวอย่างพร้อมส่วนหัวที่กำหนดเอง:

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

การส่งต่อส่วนหัวจากไคลเอนต์ (SSE/Streamable-HTTP เท่านั้น)

เมื่อเซิร์ฟเวอร์ MCP ทำงานหลังเกตเวย์หรือพร็อกซีย้อนกลับที่จัดการ SSO (เช่น AWS ALB กับ OIDC) คุกกี้เซสชันของผู้ใช้แต่ละคนต้องไปถึง Grafana เพื่อให้สามารถเชื่อมโยงคำขอกับผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว ตัวแปรสภาพแวดล้อม GRAFANA_FORWARD_HEADERS เปิดใช้งานสิ่งนี้โดยระบุรายการอนุญาตที่คั่นด้วยเครื่องหมายจุลภาคของชื่อส่วนหัวที่จะคัดลอกจากคำขอ HTTP ขาเข้า ไปยังทุกคำขอ Grafana API ขาออก

สิ่งนี้ใช้เฉพาะเมื่อใช้การขนส่ง SSE (-t sse) หรือ streamable-http (-t streamable-http) ไม่มีผลในโหมด stdio

ตัวอย่าง: ส่งต่อคุกกี้เซสชัน

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

คุณสามารถส่งต่อหลายส่วนหัวโดยคั่นด้วยเครื่องหมายจุลภาค:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

ส่วนหัวที่ส่งต่อจะถูกรวมเข้ากับส่วนหัวใดๆ ที่กำหนดใน GRAFANA_EXTRA_HEADERS หากชื่อส่วนหัวปรากฏในทั้งสองแห่ง ค่าจากคำขอขาเข้าจะมีความสำคัญกว่าสำหรับคำขอนั้น

  1. คุณมีหลายตัวเลือกในการติดตั้ง mcp-grafana:

    • uvx (แนะนำ): หากคุณติดตั้ง uv ไว้แล้ว ไม่จำเป็นต้องตั้งค่าเพิ่มเติม — uvx จะดาวน์โหลดและรันเซิร์ฟเวอร์โดยอัตโนมัติ:

      uvx mcp-grafana

    • อิมเมจ Docker: ใช้อิมเมจ Docker ที่สร้างไว้ล่วงหน้าจาก Docker Hub

      สำคัญ: จุดเข้าใช้งานของอิมเมจ Docker ถูกกำหนดค่าให้รันเซิร์ฟเวอร์ MCP ในโหมด SSE ตามค่าเริ่มต้น แต่ผู้ใช้ส่วนใหญ่จะต้องการใช้โหมด STDIO สำหรับการรวมโดยตรงกับผู้ช่วย AI เช่น Claude Desktop:

      1. โหมด STDIO: สำหรับโหมด stdio คุณต้องแทนที่ค่าเริ่มต้นอย่างชัดเจนด้วย -t stdio และรวมแฟล็ก -i เพื่อให้ stdin เปิดอยู่:
      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
      1. โหมด SSE: ในโหมดนี้ เซิร์ฟเวอร์ทำงานเป็นเซิร์ฟเวอร์ HTTP ที่ไคลเอนต์เชื่อมต่อ คุณต้องเปิดเผยพอร์ต 8000 โดยใช้แฟล็ก -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> grafana/mcp-grafana
      1. โหมด Streamable HTTP: ในโหมดนี้ เซิร์ฟเวอร์ทำงานเป็นกระบวนการอิสระที่สามารถจัดการการเชื่อมต่อไคลเอนต์หลายรายการ คุณต้องเปิดเผยพอร์ต 8000 โดยใช้แฟล็ก -p: สำหรับโหมดนี้คุณต้องแทนที่ค่าเริ่มต้นอย่างชัดเจนด้วย -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> grafana/mcp-grafana -t streamable-http

      สำหรับโหมด HTTPS streamable HTTP พร้อมใบรับรอง TLS ของเซิร์ฟเวอร์:

      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> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • ดาวน์โหลดไบนารี: ดาวน์โหลดรุ่นล่าสุดของ mcp-grafana จาก หน้ารุ่น และวางไว้ใน $PATH ของคุณ

    • สร้างจากซอร์ส: หากคุณติดตั้ง Go toolchain ไว้ คุณสามารถสร้างและติดตั้งจากซอร์สได้ โดยใช้ตัวแปรสภาพแวดล้อม GOBIN เพื่อระบุไดเรกทอรีที่ควรติดตั้งไบนารี สิ่งนี้ควรอยู่ใน $PATH ของคุณด้วย

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

    • ปรับใช้กับ Kubernetes โดยใช้ Helm: ใช้ แผนภูมิ Helm จากที่เก็บ Grafana helm-charts

      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. เพิ่มการกำหนดค่าเซิร์ฟเวอร์ไปยังไฟล์การกำหนดค่าไคลเอนต์ของคุณ ตัวอย่างเช่น สำหรับ Claude Desktop:

    หากใช้ uvx:

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

    หากใช้ไบนารี:

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

หมายเหตุ: หากคุณเห็น Error: spawn mcp-grafana ENOENT ใน Claude Desktop คุณต้องระบุเส้นทางแบบเต็มไปยัง mcp-grafana

หากใช้ 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"
      }
    }
  }
}

หมายเหตุ: อาร์กิวเมนต์ -t stdio จำเป็นที่นี่เพราะมันแทนที่โหมด SSE เริ่มต้นในอิมเมจ Docker

การใช้ VSCode กับเซิร์ฟเวอร์ MCP ระยะไกล

หากคุณใช้ VSCode และรันเซิร์ฟเวอร์ MCP ในโหมด SSE (ซึ่งเป็นค่าเริ่มต้นเมื่อใช้อิมเมจ Docker โดยไม่แทนที่การขนส่ง) ตรวจสอบให้แน่ใจว่า .vscode/settings.json ของคุณรวมสิ่งต่อไปนี้:

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

สำหรับโหมด HTTP แบบสตรีมได้ผ่าน HTTPS พร้อมใบรับรอง TLS ของเซิร์ฟเวอร์:

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

โหมดดีบัก

คุณสามารถเปิดใช้งานโหมดดีบักสำหรับการขนส่ง Grafana ได้โดยเพิ่มแฟล็ก -debug ลงในคำสั่ง ซึ่งจะให้การบันทึกรายละเอียดของคำขอและการตอบกลับ HTTP ระหว่างเซิร์ฟเวอร์ MCP และ Grafana API ซึ่งมีประโยชน์สำหรับการแก้ไขปัญหา

หากต้องการใช้โหมดดีบักกับการกำหนดค่า Claude Desktop ให้อัปเดตการกำหนดค่าของคุณดังนี้:

หากใช้ไบนารี:

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

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

หมายเหตุ: เช่นเดียวกับการกำหนดค่ามาตรฐาน อาร์กิวเมนต์ -t stdio จำเป็นต้องใช้เพื่อแทนที่โหมด SSE เริ่มต้นในอิมเมจ Docker

การกำหนดค่า TLS

หากอินสแตนซ์ Grafana ของคุณอยู่หลัง mTLS หรือต้องการใบรับรอง TLS แบบกำหนดเอง คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP ให้ใช้ใบรับรองแบบกำหนดเองได้ เซิร์ฟเวอร์รองรับตัวเลือกการกำหนดค่า TLS ต่อไปนี้:

  • --tls-cert-file: พาธไปยังไฟล์ใบรับรอง TLS สำหรับการตรวจสอบสิทธิ์ไคลเอนต์
  • --tls-key-file: พาธไปยังไฟล์คีย์ส่วนตัว TLS สำหรับการตรวจสอบสิทธิ์ไคลเอนต์
  • --tls-ca-file: พาธไปยังไฟล์ใบรับรอง CA ของ TLS สำหรับการตรวจสอบเซิร์ฟเวอร์
  • --tls-skip-verify: ข้ามการตรวจสอบใบรับรอง TLS (ไม่ปลอดภัย ใช้สำหรับการทดสอบเท่านั้น)

ตัวอย่างการตรวจสอบสิทธิ์ด้วยใบรับรองไคลเอนต์:

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

{
  "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 จะนำไปใช้กับไคลเอนต์ HTTP ทั้งหมดที่เซิร์ฟเวอร์ MCP ใช้ รวมถึง:

  • ไคลเอนต์ Grafana OpenAPI หลัก
  • ไคลเอนต์แหล่งข้อมูล Prometheus
  • ไคลเอนต์แหล่งข้อมูล Loki
  • ไคลเอนต์การจัดการเหตุการณ์
  • ไคลเอนต์การตรวจสอบ Sift
  • ไคลเอนต์การแจ้งเตือน
  • ไคลเอนต์ Asserts

ตัวอย่างการใช้งาน CLI โดยตรง:

สำหรับการทดสอบด้วยใบรับรองที่ลงนามด้วยตนเอง:

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

ด้วยการตรวจสอบสิทธิ์ใบรับรองไคลเอนต์:

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

ด้วยใบรับรอง CA แบบกำหนดเองเท่านั้น:

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

การใช้งานเชิงโปรแกรม:

หากคุณใช้ไลบรารีนี้ในเชิงโปรแกรม คุณยังสามารถสร้างฟังก์ชันบริบทที่เปิดใช้งาน 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)

การตรวจสอบ URL เมื่อเชื่อมต่อเซิร์ฟเวอร์ HTTP ของคุณเอง:

เมื่อผู้ใช้ไลบรารีเชื่อมต่อฟังก์ชันบริบทของ mcp-grafana เข้ากับ http.Server ของตนเอง ให้ติดตั้ง ValidateGrafanaURLMiddleware เพื่อปฏิเสธส่วนหัว X-Grafana-URL ที่มีรูปแบบไม่ถูกต้องด้วย 400 Bad Request (ตรงกับพฤติกรรมของไบนารี):

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

เมื่อเรียก NewGrafanaClient โดยตรง (stdio หรือการสร้างเชิงโปรแกรม) ให้ตรวจสอบ URL ที่ไม่น่าเชื่อถือล่วงหน้าเพื่อหลีกเลี่ยง panic ที่อาจเกิดขึ้นได้:

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

ทั้งสองรูปแบบใช้ ValidateGrafanaURL ร่วมกันเป็นตัวตรวจสอบเดียว

การกำหนดค่า TLS ของเซิร์ฟเวอร์ (เฉพาะการขนส่ง HTTP แบบสตรีมได้)

เมื่อใช้การขนส่ง HTTP แบบสตรีมได้ (-t streamable-http) คุณสามารถกำหนดค่าเซิร์ฟเวอร์ MCP ให้ให้บริการ HTTPS แทน HTTP ได้ ซึ่งมีประโยชน์เมื่อคุณต้องการรักษาความปลอดภัยการเชื่อมต่อระหว่างไคลเอนต์ MCP และเซิร์ฟเวอร์เอง

เซิร์ฟเวอร์รองรับตัวเลือกการกำหนดค่า TLS ต่อไปนี้สำหรับการขนส่ง HTTP แบบสตรีมได้:

  • --server.tls-cert-file: พาธไปยังไฟล์ใบรับรอง TLS สำหรับ HTTPS ของเซิร์ฟเวอร์ (จำเป็นสำหรับ TLS)
  • --server.tls-key-file: พาธไปยังไฟล์คีย์ส่วนตัว TLS สำหรับ HTTPS ของเซิร์ฟเวอร์ (จำเป็นสำหรับ TLS)

หมายเหตุ: แฟล็กเหล่านี้แยกจากแฟล็ก TLS ของไคลเอนต์ที่ระบุไว้ข้างต้นโดยสิ้นเชิง แฟล็ก TLS ของไคลเอนต์กำหนดค่าวิธีที่เซิร์ฟเวอร์ MCP เชื่อมต่อกับ Grafana ในขณะที่แฟล็ก TLS ของเซิร์ฟเวอร์เหล่านี้กำหนดค่าวิธีที่ไคลเอนต์เชื่อมต่อกับเซิร์ฟเวอร์ MCP เมื่อใช้การขนส่ง HTTP แบบสตรีมได้

ตัวอย่างกับเซิร์ฟเวอร์ HTTP แบบสตรีมได้ผ่าน HTTPS:

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

การดำเนินการนี้จะเริ่มเซิร์ฟเวอร์ MCP บนพอร์ต HTTPS 8443 จากนั้นไคลเอนต์จะเชื่อมต่อกับ https://localhost:8443/ แทน http://localhost:8000/

ตัวอย่าง Docker กับ TLS ของเซิร์ฟเวอร์:

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

ปลายทางการตรวจสอบความสมบูรณ์

เมื่อใช้การขนส่ง SSE (-t sse) หรือ HTTP แบบสตรีมได้ (-t streamable-http) เซิร์ฟเวอร์ MCP จะแสดงปลายทางการตรวจสอบความสมบูรณ์ที่ /healthz ปลายทางนี้สามารถใช้โดยตัวจัดสรรภาระงาน ระบบตรวจสอบ หรือแพลตฟอร์มการจัดการ เพื่อตรวจสอบว่าเซิร์ฟเวอร์กำลังทำงานและยอมรับการเชื่อมต่อ

ปลายทาง: GET /healthz

การตอบกลับ:

  • รหัสสถานะ: 200 OK
  • เนื้อหา: ok

ตัวอย่างการใช้งาน:

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

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

หมายเหตุ: ปลายทางการตรวจสอบความสมบูรณ์จะพร้อมใช้งานเมื่อใช้การขนส่ง SSE หรือ HTTP แบบสตรีมได้เท่านั้น จะไม่พร้อมใช้งานเมื่อใช้การขนส่ง stdio (-t stdio) เนื่องจาก stdio ไม่ได้แสดงเซิร์ฟเวอร์ HTTP

ความสามารถในการสังเกต

เซิร์ฟเวอร์ MCP รองรับเมตริก Prometheus, การติดตามแบบกระจาย OpenTelemetry และการส่งออกบันทึก OpenTelemetry ตาม ข้อตกลงเชิงความหมายของ OTel MCP การกำหนดค่าการติดตามและการส่งออกบันทึกทำผ่านตัวแปรสภาพแวดล้อม OTEL_* มาตรฐาน และทำงานร่วมกับการขนส่งใดๆ

หมายเหตุ: ปัจจุบัน mcp-grafana รองรับเฉพาะการขนส่ง OTLP/gRPC สำหรับทั้งการติดตามและบันทึก OTEL_EXPORTER_OTLP_PROTOCOL (และตัวแปร _TRACES_PROTOCOL / _LOGS_PROTOCOL) จะไม่ถูกนำมาใช้ — จะใช้ gRPC เสมอ

เมตริก

เมื่อใช้การขนส่ง SSE หรือ HTTP แบบสตรีมได้ ให้เปิดใช้งานเมตริก Prometheus ด้วยแฟล็ก --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

เมตริกที่พร้อมใช้งาน:

เมตริกประเภทคำอธิบาย
mcp_server_operation_duration_secondsHistogramระยะเวลาของการดำเนินการ MCP (ป้ายกำกับ: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramระยะเวลาของเซสชันไคลเอนต์ MCP (ป้ายกำกับ: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramระยะเวลาของคำขอเซิร์ฟเวอร์ HTTP (จาก otelhttp)

หมายเหตุ: เมตริกจะพร้อมใช้งานเมื่อใช้การขนส่ง SSE หรือ HTTP แบบสตรีมได้เท่านั้น จะไม่พร้อมใช้งานกับการขนส่ง stdio

การบันทึกคำขอที่ช้า

แฟล็ก --slow-request-threshold จะส่งเหตุการณ์บันทึกที่มีโครงสร้างเมื่อใดก็ตามที่คำขอ MCP (การเรียกใช้เครื่องมือ, รายการ, การอ่านทรัพยากร ฯลฯ) ใช้เวลาเกินระยะเวลาที่กำหนด มีประโยชน์สำหรับการวินิจฉัยคิวรีและการเรียกใช้เครื่องมือที่ช้า โดยไม่ต้องจมอยู่กับบันทึกดีบักทั้งหมด

# 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

เหตุการณ์บันทึกมีแอตทริบิวต์ที่มีโครงสร้างเหล่านี้:

แอตทริบิวต์คำอธิบาย
mcp.methodเมธอด MCP (เช่น tools/call, tools/list, resources/read)
durationระยะเวลาคำขอที่สังเกตได้
thresholdเกณฑ์ที่กำหนดค่าไว้
toolชื่อเครื่องมือ (มีเฉพาะสำหรับเมธอด tools/call)
errorค่าข้อผิดพลาด เมื่อคำขอล้มเหลว (บริบทที่พยายามอย่างดีที่สุด เนื้อหาถูกควบคุมโดยการห่อข้อผิดพลาดต้นทาง)
error.typeการจำแนกข้อผิดพลาดที่มีจำนวนสมาชิกจำกัด (_OTHER สำหรับข้อผิดพลาดที่ไม่มีประเภท)

การบันทึกคำขอที่ช้าทำงานได้กับการขนส่งทั้งหมด (รวมถึง stdio) และไม่จำเป็นต้องใช้ --metrics เกณฑ์เริ่มต้นที่ 0 จะปิดใช้งานโดยสิ้นเชิง เครื่องมือพร็อกซีจะไหลผ่าน tools/call และครอบคลุมโดยอัตโนมัติ

การติดตาม

การติดตามแบบกระจายถูกกำหนดค่าผ่านตัวแปรสภาพแวดล้อม OTEL_* มาตรฐาน และทำงานอย่างอิสระจากแฟล็ก --metrics เมื่อตั้งค่า OTEL_EXPORTER_OTLP_ENDPOINT เซิร์ฟเวอร์จะส่งออกการติดตามผ่าน 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

สแปนการเรียกใช้เครื่องมือเป็นไปตามการตั้งชื่อ semconv (tools/call <tool_name>) และรวมแอตทริบิวต์เช่น gen_ai.tool.name, mcp.method.name และ mcp.session.id เซิร์ฟเวอร์ยังรองรับการเผยแพร่บริบทการติดตาม W3C จากฟิลด์ _meta ของคำขอเรียกใช้เครื่องมือ

บันทึก

เมื่อตั้งค่า OTEL_EXPORTER_OTLP_ENDPOINT (หรือ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT เฉพาะสัญญาณ) — ซึ่งเป็นทริกเกอร์เดียวกับที่เปิดใช้งานการติดตาม — เซิร์ฟเวอร์จะส่งออกบันทึกที่มีโครงสร้างผ่าน OTLP/gRPC นอกเหนือจากเอาต์พุต stderr ข้อความธรรมดาที่มีอยู่ บริดจ์ otelslog จะแนบ trace_id และ span_id จากสแปนที่ใช้งานอยู่โดยอัตโนมัติ ดังนั้นระเบียนบันทึกจึงสัมพันธ์กับการติดตามที่เซิร์ฟเวอร์ส่งออกอยู่แล้ว

การบันทึก stderr จะไม่เปลี่ยนแปลงเมื่อเปิดใช้งานการบันทึก OTLP คุณสามารถพึ่งพาบันทึกคอนเทนเนอร์หรือไพพ์ stderr ไปยัง /dev/null ต่อไปได้หากต้องการ

# 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

การขนส่งคือ OTLP/gRPC (พอร์ตเริ่มต้น 4317) สามารถส่งบันทึกโดยตรงไปยังแบ็กเอนด์ที่มีการจัดการใดๆ ที่ยอมรับ OTLP/gRPC — ตัวอย่างเช่น Grafana Cloud — โดยชี้ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (หรือ OTEL_EXPORTER_OTLP_ENDPOINT ทั่วไป) ไปยังปลายทาง gRPC ระยะไกล และให้การตรวจสอบสิทธิ์ผ่าน OTEL_EXPORTER_OTLP_LOGS_HEADERS (หรือ OTEL_EXPORTER_OTLP_HEADERS) ซึ่งสะท้อนตัวอย่างการติดตามข้างต้น ตัวรวบรวม OTel ในเครื่องเป็น ทางเลือก — มีประโยชน์สำหรับการแยกสาขา การจัดชุด หรือการกำหนดเส้นทางหลายแบ็กเอนด์ แต่ไม่จำเป็น

ตัวแปรเฉพาะสัญญาณ 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 และ OTEL_EXPORTER_OTLP_LOGS_COMPRESSION จะถูกนำมาใช้และแทนที่คู่เทียบ OTEL_EXPORTER_OTLP_* ทั่วไป — ดู ข้อกำหนดผู้ส่งออก OTel สำหรับรายการทั้งหมดและกฎลำดับความสำคัญ

หากตัวรวบรวมที่กำหนดค่าไว้ไม่สามารถเข้าถึงได้ ระเบียนบันทึกจะถูกบัฟเฟอร์ในหน่วยความจำ (คิวเริ่มต้น: 2048) และระเบียนที่เก่าที่สุดจะถูกทิ้งเมื่อคิวเต็ม กระบวนการจะดำเนินต่อไปโดยไม่บล็อกบริการ กำหนดค่าตัวรวบรวม OTel ในเครื่องหากคุณต้องการบัฟเฟอร์แบบไม่สูญหายระหว่างไฟดับ

บันทึกยังถูกส่งออกภายใต้การขนส่ง stdio ซึ่งทำให้ง่ายต่อการรวมศูนย์บันทึกจากอินสแตนซ์ mcp-grafana ในเครื่องที่เรียกใช้โดยไคลเอนต์ IDE

ตัวอย่าง Docker พร้อมเมตริก การติดตาม และบันทึก:

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

การแก้ไขปัญหา

ความเข้ากันได้ของเวอร์ชัน Grafana

หากคุณพบข้อผิดพลาดต่อไปนี้เมื่อใช้เครื่องมือที่เกี่ยวข้องกับแหล่งข้อมูล:

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

โดยทั่วไปสิ่งนี้บ่งชี้ว่าคุณกำลังใช้ Grafana เวอร์ชันก่อน 9.0 ปลายทาง API /datasources/uid/{uid} ถูกนำมาใช้ใน Grafana 9.0 และการดำเนินการแหล่งข้อมูลจะล้มเหลวในเวอร์ชันก่อนหน้า

วิธีแก้ไข: อัปเกรดอินสแตนซ์ Grafana ของคุณเป็นเวอร์ชัน 9.0 หรือใหม่กว่าเพื่อแก้ไขปัญหานี้

การพัฒนา

ยินดีต้อนรับการมีส่วนร่วม! โปรดเปิด issue หรือส่ง pull request หากคุณมีข้อเสนอแนะหรือการปรับปรุงใดๆ

โปรเจกต์นี้เขียนด้วยภาษา Go ติดตั้ง Go ตามคำแนะนำสำหรับแพลตฟอร์มของคุณ

หากต้องการรันเซิร์ฟเวอร์ในเครื่องในโหมด STDIO (ซึ่งเป็นค่าเริ่มต้นสำหรับการพัฒนาในเครื่อง) ให้ใช้:

make run

หากต้องการรันเซิร์ฟเวอร์ในเครื่องในโหมด SSE ให้ใช้:

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

คุณยังสามารถรันเซิร์ฟเวอร์โดยใช้การขนส่ง SSE ภายในอิมเมจ Docker ที่สร้างขึ้นเองได้ เช่นเดียวกับอิมเมจ Docker ที่เผยแพร่ จุดเริ่มต้นของอิมเมจที่กำหนดเองนี้จะเริ่มต้นเป็นโหมด SSE หากต้องการสร้างอิมเมจ ให้ใช้:

make build-image

และเพื่อรันอิมเมจในโหมด SSE (ค่าเริ่มต้น) ให้ใช้:

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

หากคุณต้องการรันในโหมด STDIO แทน ให้แทนที่การตั้งค่าการขนส่ง:

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

การทดสอบ

มีการทดสอบสามประเภท:

  1. การทดสอบหน่วย (ไม่จำเป็นต้องมีการพึ่งพาภายนอก):
make test-unit

คุณยังสามารถรันการทดสอบหน่วยด้วย:

make test
  1. การทดสอบการรวมระบบ (ต้องให้คอนเทนเนอร์ Docker ทำงานอยู่):
make test-integration
  1. การทดสอบคลาวด์ (ต้องใช้อินสแตนซ์ Grafana คลาวด์และข้อมูลประจำตัว):
make test-cloud

หมายเหตุ: การทดสอบคลาวด์ได้รับการกำหนดค่าโดยอัตโนมัติใน CI สำหรับการพัฒนาในเครื่อง คุณจะต้องตั้งค่าอินสแตนซ์ Grafana Cloud และข้อมูลประจำตัวของคุณเอง

การทดสอบการรวมระบบที่ครอบคลุมมากขึ้นจะต้องใช้อินสแตนซ์ Grafana ที่ทำงานในเครื่องบนพอร์ต 3000 คุณสามารถเริ่มต้นด้วย Docker Compose:

docker-compose up -d

การทดสอบการรวมระบบสามารถรันได้ด้วย:

make test-all

หากคุณกำลังเพิ่มเครื่องมือเพิ่มเติม โปรดเพิ่มการทดสอบการรวมระบบสำหรับเครื่องมือเหล่านั้น การทดสอบที่มีอยู่ควรเป็นจุดเริ่มต้นที่ดี

การตรวจสอบโค้ด

ในการตรวจสอบโค้ด ให้รัน:

make lint

ซึ่งรวมถึง linter แบบกำหนดเองที่ตรวจสอบเครื่องหมายจุลภาคที่ไม่ได้ escape ในแท็ก struct jsonschema เครื่องหมายจุลภาคในฟิลด์ description ต้อง escape ด้วย \\, เพื่อป้องกันการตัดทอนแบบเงียบ คุณสามารถรันเฉพาะ linter นี้ด้วย:

make lint-jsonschema

ดู เอกสาร JSONSchema Linter สำหรับรายละเอียดเพิ่มเติม

ใบอนุญาต

โปรเจกต์นี้ได้รับอนุญาตภายใต้ Apache License, Version 2.0