Grafana

chính thức

Tìm kiếm dashboard, điều tra sự cố và truy vấn nguồn dữ liệu trong phiên bản Grafana của bạn

GitHub
3.4k
Dùng thử MCP nàyĐược tài trợ

Bạn có thể làm gì với Grafana MCP?

  • Tìm kiếm và kiểm tra dashboard — Yêu cầu dashboard theo tiêu đề, lấy toàn bộ JSON qua get_dashboard_by_uid, hoặc trích xuất các phần cụ thể bằng get_dashboard_property sử dụng JSONPath.
  • Truy vấn trực tiếp nguồn dữ liệu — Chạy PromQL với Prometheus qua query_prometheus, LogQL với Loki, hoặc SQL với ClickHouse, Snowflake và Athena.
  • Quản lý cảnh báo và sự cố — Liệt kê, tạo, cập nhật hoặc xóa quy tắc cảnh báo, đồng thời tìm kiếm hoặc sửa đổi bản ghi Grafana Incident.
  • Tạo deeplink chính xác — Tạo URL dashboard, bảng điều khiển và Explore kèm khoảng thời gian thay vì đoán URL.
  • Kết xuất hình ảnh dashboard — Lấy một bảng điều khiển hoặc toàn bộ dashboard dưới dạng PNG base64 qua công cụ kết xuất cho báo cáo hoặc cảnh báo.
  • Khám phá khả năng quan sát của agent — Liệt kê và tìm kiếm hội thoại LLM, lấy chi tiết thế hệ, đồng thời kiểm tra bộ đánh giá và bộ kiểm thử trong Grafana Cloud.

Tài liệu

Máy chủ MCP Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Một máy chủ Giao thức Ngữ cảnh Mô hình (MCP) dành cho Grafana.

Máy chủ này cung cấp quyền truy cập vào phiên bản Grafana của bạn và hệ sinh thái xung quanh.

Bắt đầu nhanh

Yêu cầu uv. Thêm nội dung sau vào cấu hình máy khách MCP của bạn (ví dụ: Claude Desktop, Cursor):

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

Đối với Grafana Cloud, hãy thay GRAFANA_URL bằng URL phiên bản của bạn (ví dụ: https://myinstance.grafana.net). Xem Cách sử dụng để biết thêm các tùy chọn cài đặt bao gồm Docker, tệp nhị phân và Helm.

Yêu cầu

  • Phiên bản Grafana 9.0 trở lên được yêu cầu để có đầy đủ chức năng. Một số tính năng, đặc biệt là các thao tác liên quan đến nguồn dữ liệu, có thể không hoạt động chính xác với các phiên bản cũ hơn do thiếu các điểm cuối API.

Tính năng

Danh sách các tính năng sau hiện có sẵn trong máy chủ MCP. Danh sách này chỉ nhằm mục đích cung cấp thông tin và không đại diện cho lộ trình hoặc cam kết về các tính năng trong tương lai.

Bảng điều khiển

  • Tìm kiếm bảng điều khiển: Tìm bảng điều khiển theo tiêu đề hoặc siêu dữ liệu khác
  • Lấy bảng điều khiển theo UID: Truy xuất chi tiết đầy đủ của bảng điều khiển bằng mã định danh duy nhất của nó. Cảnh báo: Các bảng điều khiển lớn có thể tiêu tốn không gian cửa sổ ngữ cảnh đáng kể.
  • Lấy tóm tắt bảng điều khiển: Nhận tổng quan gọn gàng về bảng điều khiển bao gồm tiêu đề, số lượng bảng, loại bảng, biến và siêu dữ liệu mà không cần JSON đầy đủ để giảm thiểu việc sử dụng cửa sổ ngữ cảnh
  • Lấy thuộc tính bảng điều khiển: Trích xuất các phần cụ thể của bảng điều khiển bằng biểu thức JSONPath (ví dụ: $.title, $.panels[*].title) để chỉ lấy dữ liệu cần thiết và giảm mức tiêu thụ cửa sổ ngữ cảnh
  • Cập nhật hoặc tạo bảng điều khiển: Sửa đổi bảng điều khiển hiện có hoặc tạo bảng điều khiển mới. Cảnh báo: Yêu cầu JSON bảng điều khiển đầy đủ có thể tiêu tốn lượng lớn không gian cửa sổ ngữ cảnh.
  • Vá bảng điều khiển: Áp dụng các thay đổi cụ thể cho bảng điều khiển mà không cần JSON đầy đủ, giảm đáng kể việc sử dụng cửa sổ ngữ cảnh cho các sửa đổi có mục tiêu
  • Lấy truy vấn bảng và thông tin nguồn dữ liệu: Lấy tiêu đề, chuỗi truy vấn và thông tin nguồn dữ liệu (bao gồm UID và loại, nếu có) từ mọi bảng trong bảng điều khiển

Chạy truy vấn bảng

Lưu ý: Các công cụ chạy truy vấn bảng bị tắt theo mặc định. Để bật chúng, hãy thêm runpanelquery vào cờ --enabled-tools của bạn.

  • Chạy truy vấn bảng: Thực thi truy vấn của bảng trong bảng điều khiển với phạm vi thời gian tùy chỉnh và ghi đè biến.

Quản lý cửa sổ ngữ cảnh

Các công cụ bảng điều khiển hiện bao gồm một số chiến lược để quản lý hiệu quả việc sử dụng cửa sổ ngữ cảnh (vấn đề #101):

  • Sử dụng get_dashboard_summary để xem tổng quan bảng điều khiển và lập kế hoạch sửa đổi
  • Sử dụng get_dashboard_property với JSONPath khi bạn chỉ cần các phần cụ thể của bảng điều khiển
  • Tránh get_dashboard_by_uid trừ khi bạn thực sự cần JSON bảng điều khiển hoàn chỉnh

Nguồn dữ liệu

  • Liệt kê và lấy thông tin nguồn dữ liệu: Xem tất cả các nguồn dữ liệu đã cấu hình và truy xuất thông tin chi tiết về từng nguồn.
    • Các loại nguồn dữ liệu được hỗ trợ: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Ví dụ truy vấn

Lưu ý: Các công cụ ví dụ truy vấn bị tắt theo mặc định. Để bật chúng, hãy thêm examples vào cờ --enabled-tools của bạn.

  • Lấy ví dụ truy vấn: Truy xuất các truy vấn ví dụ cho các loại nguồn dữ liệu khác nhau để học cú pháp truy vấn.

Truy vấn Prometheus

  • Truy vấn Prometheus: Thực thi các truy vấn PromQL (hỗ trợ cả truy vấn số liệu tức thời và theo phạm vi) trên các nguồn dữ liệu Prometheus.
  • Truy vấn siêu dữ liệu Prometheus: Truy xuất siêu dữ liệu số liệu, tên số liệu, tên nhãn và giá trị nhãn từ các nguồn dữ liệu Prometheus.
  • Truy vấn phân vị biểu đồ: Tính toán các giá trị phân vị biểu đồ (p50, p90, p95, p99) bằng histogram_quantile.

Truy vấn Loki

  • Truy vấn nhật ký và số liệu Loki: Chạy cả truy vấn nhật ký và truy vấn số liệu bằng LogQL trên các nguồn dữ liệu Loki.
  • Truy vấn siêu dữ liệu Loki: Truy xuất tên nhãn, giá trị nhãn và thống kê luồng từ các nguồn dữ liệu Loki.
  • Truy vấn mẫu Loki: Truy xuất các mẫu nhật ký được Loki phát hiện để xác định các cấu trúc nhật ký phổ biến và các bất thường.

Truy vấn InfluxDB

Lưu ý: Các công cụ InfluxDB bị tắt theo mặc định. Để bật chúng, hãy thêm influxdb vào cờ --enabled-tools của bạn.

  • Truy vấn InfluxDB: Thực thi các truy vấn trên các nguồn dữ liệu InfluxDB bằng InfluxQL (v1.x) hoặc Flux (v2.x). Phương ngữ được suy ra từ cấu hình nguồn dữ liệu hoặc có thể được đặt rõ ràng qua tham số dialect.

Truy vấn ClickHouse

Lưu ý: Các công cụ ClickHouse bị tắt theo mặc định. Để bật chúng, hãy thêm clickhouse vào cờ --enabled-tools của bạn.

  • Liệt kê bảng ClickHouse: Liệt kê tất cả các bảng trong cơ sở dữ liệu ClickHouse với số hàng và kích thước.
  • Mô tả lược đồ bảng: Lấy tên cột, loại và siêu dữ liệu cho một bảng ClickHouse.
  • Truy vấn ClickHouse: Thực thi các truy vấn SQL với hỗ trợ thay thế biến và macro Grafana.

Truy vấn CloudWatch

Lưu ý: Các công cụ CloudWatch bị tắt theo mặc định. Để bật chúng, hãy thêm cloudwatch vào cờ --enabled-tools của bạn.

  • Liệt kê không gian tên CloudWatch: Khám phá các không gian tên AWS CloudWatch có sẵn.
  • Liệt kê số liệu CloudWatch: Liệt kê các số liệu có sẵn trong một không gian tên cụ thể.
  • Liệt kê thứ nguyên CloudWatch: Lấy các thứ nguyên để lọc các truy vấn số liệu.
  • Truy vấn CloudWatch: Thực thi các truy vấn số liệu CloudWatch với hỗ trợ phạm vi thời gian.

Truy vấn Graphite

Lưu ý: Các công cụ Graphite bị tắt theo mặc định. Để bật chúng, hãy thêm graphite vào cờ --enabled-tools của bạn.

  • Truy vấn Graphite: Thực thi các truy vấn API kết xuất Graphite trên một nguồn dữ liệu Graphite.
  • Liệt kê số liệu Graphite: Duyệt và khám phá các đường dẫn số liệu Graphite.
  • Liệt kê thẻ Graphite: Liệt kê các thẻ và giá trị thẻ Graphite có sẵn.
  • Truy vấn mật độ Graphite: Truy vấn mật độ số liệu Graphite cho một mẫu nhất định.

Truy vấn Athena

Lưu ý: Các công cụ Athena bị tắt theo mặc định. Để bật chúng, hãy thêm athena vào cờ --enabled-tools của bạn.

  • Liệt kê danh mục Athena: Khám phá các danh mục dữ liệu có sẵn (ví dụ: AwsDataCatalog, bộ kết nối Iceberg).
  • Liệt kê cơ sở dữ liệu Athena: Liệt kê các cơ sở dữ liệu trong một danh mục Athena.
  • Liệt kê bảng Athena: Liệt kê các bảng trong một cơ sở dữ liệu Athena.
  • Mô tả bảng Athena: Lấy tên cột cho một bảng Athena.
  • Truy vấn Athena: Thực thi các truy vấn SQL trên Amazon Athena qua Grafana với thay thế macro, thực thi giới hạn và hỗ trợ biến mẫu.

Truy vấn Snowflake

Lưu ý: Các công cụ Snowflake bị tắt theo mặc định. Để bật chúng, hãy thêm snowflake vào cờ --enabled-tools của bạn.

Các truy vấn đi qua nguồn dữ liệu Snowflake của Grafana (plugin Grafana Enterprise grafana-snowflake-datasource), vì vậy xác thực được xử lý bởi cấu hình nguồn dữ liệu trong Grafana — thông tin xác thực không bao giờ được máy chủ MCP nhìn thấy. Đây là mô hình tương tự được sử dụng cho các công cụ ClickHouse.

  • Liệt kê bảng Snowflake: Khám phá các bảng (với cơ sở dữ liệu, lược đồ, loại, số hàng và kích thước) qua INFORMATION_SCHEMA.TABLES. Bộ lọc cơ sở dữ liệu/lược đồ tùy chọn.
  • Mô tả lược đồ bảng: Lấy tên cột, loại dữ liệu, khả năng rỗng, giá trị mặc định và nhận xét cho một bảng Snowflake.
  • Truy vấn Snowflake: Thực thi các truy vấn SQL với hỗ trợ thay thế biến và macro. Hữu ích để truy vấn các bảng sự kiện của Snowflake (ví dụ: SNOWFLAKE.TELEMETRY.EVENTS) cho nhật ký và dấu vết, hoặc bất kỳ bảng người dùng nào.
    • Các macro được hỗ trợ: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (giây), $__interval_ms và ${varname} để thay thế biến mẫu.

Truy vấn Elasticsearch/OpenSearch

Lưu ý: Các công cụ Elasticsearch/OpenSearch bị tắt theo mặc định. Để bật chúng, hãy thêm elasticsearch vào cờ --enabled-tools của bạn.

  • Truy vấn Elasticsearch/OpenSearch: Thực thi các truy vấn tìm kiếm trên các nguồn dữ liệu Elasticsearch hoặc OpenSearch bằng cú pháp truy vấn Lucene hoặc Elasticsearch Query DSL. Hỗ trợ lọc theo phạm vi thời gian và truy xuất nhật ký, số liệu hoặc bất kỳ dữ liệu được lập chỉ mục nào. Trả về các tài liệu với chỉ mục, ID, trường nguồn và điểm liên quan tùy chọn của chúng.

Truy vấn Quickwit

Lưu ý: Các công cụ Quickwit bị tắt theo mặc định. Để bật chúng, hãy thêm quickwit vào cờ --enabled-tools của bạn.

  • Truy vấn Quickwit: Thực thi các truy vấn tìm kiếm trên các nguồn dữ liệu Quickwit bằng cú pháp truy vấn Lucene hoặc một phần Query DSL tương thích Elasticsearch. Hỗ trợ lọc theo phạm vi thời gian và truy xuất nhật ký hoặc các tài liệu được lập chỉ mục khác. Trả về các tài liệu với chỉ mục, ID, trường nguồn và điểm liên quan tùy chọn của chúng.

Quan sát tác nhân

Lưu ý: Các công cụ Quan sát tác nhân bị tắt theo mặc định và chỉ hoạt động trong Grafana Cloud. Để bật chúng, hãy thêm agento11y vào cờ --enabled-tools của bạn.

  • Liệt kê và tìm kiếm hội thoại: Liệt kê các hội thoại LLM gần đây hoặc tìm kiếm chúng bằng biểu thức lọc (mô hình, nhà cung cấp, tác nhân, trạng thái, loại lỗi, kết quả đánh giá, v.v.) trong một phạm vi thời gian. Kết quả tìm kiếm bao gồm số lượng lỗi, tóm tắt xếp hạng, tóm tắt đánh giá và ID dấu vết.
  • Lấy chi tiết hội thoại: Tìm nạp một hội thoại duy nhất với tất cả các thế hệ của nó, bao gồm lời nhắc và đầu ra.
  • Lấy chi tiết và điểm số thế hệ: Tìm nạp một thế hệ duy nhất theo ID và điểm số đánh giá của nó (người đánh giá, khóa điểm, giá trị, đạt, giải thích).
  • Đọc danh mục tác nhân: Liệt kê các tác nhân gửi dữ liệu từ xa, tìm nạp một phiên bản tác nhân đầy đủ (lời nhắc hệ thống hoàn chỉnh, mọi công cụ với lược đồ JSON của nó và các mô hình mà nó chạy trên đó), duyệt qua lịch sử phiên bản của tác nhân và so sánh tổng hợp điểm đánh giá theo phiên bản. Các phiên bản hiệu quả là các băm sha256: mà thay đổi công cụ không bao giờ ảnh hưởng; đối với tác nhân không báo cáo phiên bản riêng, chúng băm lời nhắc hệ thống, vì vậy chỉnh sửa lời nhắc sẽ tạo ra phiên bản mới. Các hàng danh mục và phiên bản mang token_estimate, đáng để kiểm tra trước khi tìm nạp lời nhắc đầy đủ.
  • Kiểm tra người đánh giá và mẫu: Đọc các người đánh giá mà điểm số đến từ đó, các mẫu mà chúng được suy ra và các nhà cung cấp thẩm phán và mô hình có sẵn cho người đánh giá LLM-judge. Với các công cụ ghi được bật, cũng tạo, phân nhánh, kiểm tra và xóa người đánh giá.
  • Kiểm tra quy tắc và bảo vệ đánh giá: Đọc các quy tắc đánh giá không đồng bộ ràng buộc người đánh giá với lưu lượng sản xuất và các bảo vệ (quy tắc hook) chạy nội tuyến và có thể cảnh báo hoặc từ chối. Với các công cụ ghi được bật, cũng tạo, cập nhật, xem trước và xóa chúng. Ghi và các thao tác không lưu trữ preview_rule và test_evaluator cần quyền grafana-agento11y-app.eval:write, được cấp bởi vai trò Quản trị viên Agento11y.
  • Quản lý hội thoại và bộ sưu tập đã lưu: Đọc các hội thoại đã lưu (dấu trang cung cấp cho hội thoại ID ổn định, tên và thẻ) và các bộ sưu tập nhóm chúng, bao gồm số lượng thành viên của mỗi bộ sưu tập và các bộ sưu tập được nhúng trong mọi hàng hội thoại đã lưu. Với các công cụ ghi được bật, cũng đánh dấu hội thoại, tạo và chỉnh sửa bộ sưu tập, thêm hoặc xóa thành viên. Các ghi này cần cùng quyền grafana-agento11y-app.eval:write.
  • Đọc và chỉnh sửa bộ kiểm thử: Liệt kê các bộ kiểm thử có phiên bản mà các thử nghiệm ngoại tuyến chạy trên đó, đọc một bộ với lịch sử phiên bản đầy đủ của nó và phân trang qua các trường hợp kiểm thử của một phiên bản. Với các công cụ ghi được bật, cũng tạo bộ, đổi tên hoặc gắn lại thẻ, mở phiên bản nháp, xuất bản nó và ghi hoặc xóa các trường hợp kiểm thử của nó. Phiên bản đã xuất bản bị đóng băng, vì vậy chỉnh sửa có nghĩa là mở nháp mới. Các ghi này cần grafana-agento11y-app.eval:write.
  • Đọc thử nghiệm ngoại tuyến: Liệt kê các lần chạy đánh giá trên một bộ kiểm thử và đọc một lần với tỷ lệ đạt nổi bật, chi phí và tổng token của nó. Đi sâu qua báo cáo theo trường hợp kiểm thử đến các thử nghiệm, điểm số của chúng với giải thích của mỗi thẩm phán và siêu dữ liệu tạo phẩm của chúng. Với các công cụ ghi được bật, cũng đổi tên hoặc gắn lại thẻ thử nghiệm và hủy thử nghiệm đang chạy, cần grafana-agento11y-app.eval:write. Thử nghiệm được tạo bởi các trình chạy SDK, không phải bởi công cụ này.

Trợ lý Grafana

Lưu ý: Các công cụ Trợ lý bị tắt theo mặc định và yêu cầu plugin Grafana Assistant (grafana-assistant-app) phải được cài đặt trên phiên bản Grafana mục tiêu. Chúng cũng là công cụ ghi (trợ lý có thể thay đổi trạng thái stack), vì vậy chúng bị bỏ qua khi --disable-write được đặt. Để kích hoạt chúng, hãy thêm assistant vào cờ --enabled-tools của bạn.

  • Hỏi trợ lý: Gửi một lời nhắc ngôn ngữ tự nhiên đến Grafana Assistant và chờ phản hồi văn bản đầy đủ. Trợ lý có thể sử dụng các công cụ, số liệu, nhật ký và bối cảnh stack khác—rộng hơn việc chỉ thực hiện một truy vấn nguồn dữ liệu riêng lẻ. Truyền contextId trả về trong một cuộc gọi tiếp theo để tiếp tục cùng một cuộc trò chuyện. Các tác vụ phức tạp có thể mất vài phút; cuộc gọi bị chặn cho đến khi phản hồi hoàn tất hoặc yêu cầu hết thời gian chờ (5 phút).

Sự cố

  • Tìm kiếm, tạo và cập nhật sự cố: Quản lý sự cố trong Grafana Incident, bao gồm tìm kiếm, tạo, thêm hoạt động và đọc hoặc đặt các trường tùy chỉnh.

Điều tra Sift

  • Liệt kê các cuộc điều tra Sift: Truy xuất danh sách các cuộc điều tra Sift, với hỗ trợ tham số giới hạn.
  • Lấy cuộc điều tra Sift: Truy xuất chi tiết của một cuộc điều tra Sift cụ thể theo UUID của nó.
  • Lấy phân tích Sift: Truy xuất một phân tích cụ thể từ một cuộc điều tra Sift.
  • Tìm mẫu lỗi trong nhật ký: Phát hiện các mẫu lỗi tăng cao trong nhật ký Loki bằng Sift.
  • Tìm yêu cầu chậm: Phát hiện các yêu cầu chậm bằng Sift (Tempo).

Cảnh báo

  • Liệt kê và lấy thông tin quy tắc cảnh báo: Xem các quy tắc cảnh báo và trạng thái của chúng (đang kích hoạt/bình thường/lỗi/v.v.) trong Grafana. Hỗ trợ cả quy tắc do Grafana quản lý và quy tắc do nguồn dữ liệu quản lý từ các nguồn dữ liệu Prometheus hoặc Loki.
  • Tạo và cập nhật quy tắc cảnh báo: Tạo quy tắc cảnh báo mới hoặc sửa đổi các quy tắc hiện có.
  • Xóa quy tắc cảnh báo: Xóa quy tắc cảnh báo theo UID.
  • Quản lý định tuyến cảnh báo: Xem các chính sách thông báo, điểm liên hệ và khoảng thời gian. Hỗ trợ cả điểm liên hệ do Grafana quản lý và bộ thu từ các nguồn dữ liệu Alertmanager bên ngoài (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

  • Liệt kê và quản lý lịch trình: Xem và quản lý lịch trình trực ca trong Grafana OnCall.
  • Lấy chi tiết ca trực: Truy xuất thông tin chi tiết về các ca trực cụ thể.
  • Lấy người dùng trực hiện tại: Xem người dùng nào hiện đang trực cho một lịch trình.
  • Liệt kê nhóm và người dùng: Xem tất cả nhóm và người dùng OnCall.
  • Liệt kê nhóm cảnh báo: Xem và lọc các nhóm cảnh báo từ Grafana OnCall theo nhiều tiêu chí khác nhau bao gồm trạng thái, tích hợp, nhãn và phạm vi thời gian.
  • Lấy chi tiết nhóm cảnh báo: Truy xuất thông tin chi tiết về một nhóm cảnh báo cụ thể theo ID của nó.

Quản trị

Lưu ý: Các công cụ Quản trị bị tắt theo mặc định. Để kích hoạt chúng, hãy bao gồm admin trong cờ --enabled-tools của bạn.

  • Liệt kê nhóm: Xem tất cả nhóm đã cấu hình trong Grafana.
  • Liệt kê người dùng: Xem tất cả người dùng trong một tổ chức trong Grafana.
  • Liệt kê tất cả vai trò: Liệt kê tất cả vai trò Grafana, với bộ lọc tùy chọn cho các vai trò có thể ủy quyền.
  • Lấy chi tiết vai trò: Lấy chi tiết cho một vai trò Grafana cụ thể theo UID.
  • Liệt kê các phân công cho một vai trò: Liệt kê tất cả người dùng, nhóm và tài khoản dịch vụ được phân công cho một vai trò.
  • Liệt kê vai trò cho người dùng: Liệt kê tất cả vai trò được phân công cho một hoặc nhiều người dùng.
  • Liệt kê vai trò cho nhóm: Liệt kê tất cả vai trò được phân công cho một hoặc nhiều nhóm.
  • Liệt kê quyền cho một tài nguyên: Liệt kê tất cả quyền được xác định cho một tài nguyên cụ thể (bảng điều khiển, nguồn dữ liệu, thư mục, v.v.).
  • Mô tả một tài nguyên Grafana: Liệt kê các quyền có sẵn và khả năng phân công cho một loại tài nguyên.

Người dùng

  • Thông tin người dùng: Lấy danh tính Grafana hiện tại — tên đăng nhập, email, tên, có phải là quản trị viên Grafana (máy chủ) hay không, tổ chức hiện tại và các tổ chức mà thông tin xác thực có thể truy cập (với vai trò). Sử dụng nó để khám phá các giá trị orgId hợp lệ cho các yêu cầu đa tổ chức.

Điều hướng

  • Tạo liên kết sâu: Tạo URL liên kết sâu chính xác cho các tài nguyên Grafana thay vì dựa vào việc đoán URL của LLM.
    • Liên kết bảng điều khiển: Tạo liên kết trực tiếp đến bảng điều khiển bằng UID của chúng (ví dụ: http://localhost:3000/d/dashboard-uid)
    • Liên kết bảng điều khiển con: Tạo liên kết đến các bảng điều khiển con cụ thể trong bảng điều khiển với tham số viewPanel (ví dụ: http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Liên kết Khám phá: Tạo liên kết đến Grafana Explore với các nguồn dữ liệu được cấu hình sẵn (ví dụ: http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • Hỗ trợ phạm vi thời gian: Thêm tham số phạm vi thời gian vào liên kết (from=now-1h&to=now)
    • Tham số tùy chỉnh: Bao gồm các tham số truy vấn bổ sung như biến bảng điều khiển hoặc khoảng thời gian làm mới

Chú thích

  • Lấy chú thích: Truy vấn chú thích với bộ lọc. Hỗ trợ phạm vi thời gian, UID bảng điều khiển, thẻ và chế độ khớp.
  • Tạo chú thích: Tạo chú thích mới trên bảng điều khiển hoặc bảng điều khiển con.
  • Tạo chú thích Graphite: Tạo chú thích bằng định dạng Graphite (what, when, tags, data).
  • Cập nhật chú thích: Thay thế tất cả trường của một chú thích hiện có (cập nhật đầy đủ).
  • Vá chú thích: Chỉ cập nhật các trường cụ thể của một chú thích (cập nhật một phần).
  • Lấy thẻ chú thích: Liệt kê các thẻ chú thích có sẵn với bộ lọc tùy chọn.

Ảnh chụp nhanh

  • Liệt kê ảnh chụp nhanh: Liệt kê ảnh chụp nhanh bảng điều khiển với bộ lọc truy vấn và giới hạn tùy chọn.
  • Lấy ảnh chụp nhanh: Truy xuất siêu dữ liệu ảnh chụp nhanh và tải trọng bảng điều khiển theo khóa ảnh chụp nhanh.
  • Tạo ảnh chụp nhanh: Tạo ảnh chụp nhanh bảng điều khiển từ tải trọng bảng điều khiển đầy đủ, với tùy chọn hết hạn và ảnh chụp nhanh bên ngoài.
  • Xóa ảnh chụp nhanh: Xóa ảnh chụp nhanh theo khóa ảnh chụp nhanh.

Kết xuất

  • Lấy hình ảnh bảng điều khiển con hoặc bảng điều khiển: Kết xuất bảng điều khiển con Grafana hoặc toàn bộ bảng điều khiển dưới dạng hình ảnh PNG. Trả về hình ảnh dưới dạng dữ liệu mã hóa base64 để sử dụng trong báo cáo, cảnh báo hoặc bài thuyết trình. Hỗ trợ tùy chỉnh kích thước, phạm vi thời gian, chủ đề, tỷ lệ và biến bảng điều khiển. Cũng hỗ trợ kết xuất các bảng điều khiển chưa được áp dụng từ một nhánh kho cung cấp (ví dụ: bản xem trước PR git-sync) qua tham số provisioningPreview tùy chọn.

Cung cấp

  • Liệt kê kho cung cấp: Liệt kê các kho cung cấp được cấu hình cho phiên bản Grafana này (ví dụ: nguồn git-sync), trả về slug của mỗi kho cùng với URL nguồn, nhánh, đường dẫn, trạng thái đồng bộ và tình trạng của nó.
  • Xác thực tệp cung cấp: Áp dụng thử một tệp từ kho cung cấp tại một nhánh hoặc cam kết nhất định. Trả về liệu nó có được chấp nhận hay không, hành động tài nguyên (tạo/cập nhật), loại tài nguyên mục tiêu và bất kỳ lỗi xác thực có cấu trúc nào — cùng một bề mặt chấp nhận mà trình bình luận PR của Grafana sử dụng.

Danh sách các công cụ có thể cấu hình, vì vậy bạn có thể chọn công cụ nào bạn muốn cung cấp cho máy khách MCP. Điều này hữu ích nếu bạn không sử dụng chức năng nhất định hoặc nếu bạn không muốn chiếm quá nhiều cửa sổ ngữ cảnh. Để tắt một danh mục công cụ, hãy sử dụng cờ --disable-<category> khi khởi động máy chủ. Ví dụ, để tắt các công cụ OnCall, hãy sử dụng --disable-oncall, hoặc để tắt tạo liên kết sâu điều hướng, hãy sử dụng --disable-navigation.

Quyền RBAC

Mỗi công cụ yêu cầu các quyền RBAC cụ thể để hoạt động đúng. Khi tạo tài khoản dịch vụ cho máy chủ MCP, hãy đảm bảo nó có các quyền cần thiết dựa trên các công cụ bạn định sử dụng. Các quyền được liệt kê là các hành động tối thiểu bắt buộc — bạn cũng có thể cần các phạm vi phù hợp (ví dụ: datasources:*, dashboards:*, folders:*) tùy thuộc vào trường hợp sử dụng của bạn.

Mẹo: Nếu bạn không quen với RBAC của Grafana hoặc bạn muốn thiết lập nhanh hơn, đơn giản hơn thay vì cấu hình nhiều phạm vi chi tiết, bạn có thể gán một vai trò tích hợp sẵn như Editor cho tài khoản dịch vụ. Vai trò Editor cấp quyền truy cập đọc/ghi rộng rãi cho phép hầu hết các hoạt động của máy chủ MCP; nó ít chi tiết hơn (và do đó ít hạn chế hơn) so với các phạm vi áp dụng thủ công, vì vậy chỉ sử dụng nó khi sự tiện lợi quan trọng hơn quyền truy cập tối thiểu nghiêm ngặt.

Lưu ý: Các công cụ Grafana Incident và Sift sử dụng vai trò Grafana cơ bản thay vì quyền RBAC chi tiết:

  • Vai trò Người xem: Bắt buộc cho các hoạt động chỉ đọc (liệt kê sự cố, lấy cuộc điều tra)
  • Vai trò Biên tập viên: Bắt buộc cho các hoạt động ghi (tạo sự cố, sửa đổi cuộc điều tra)

Để biết thêm thông tin về RBAC của Grafana, hãy xem tài liệu chính thức.

Phạm vi RBAC

Phạm vi xác định các tài nguyên cụ thể mà quyền áp dụng. Mỗi hành động yêu cầu cả sự kết hợp quyền và phạm vi phù hợp.

Các mẫu phạm vi phổ biến:

  • Truy cập rộng: Sử dụng ký tự đại diện * để truy cập toàn tổ chức

    • datasources:* - Truy cập tất cả nguồn dữ liệu
    • dashboards:* - Truy cập tất cả bảng điều khiển
    • folders:* - Truy cập tất cả thư mục
    • teams:* - Truy cập tất cả nhóm

  • Truy cập hạn chế: Sử dụng UID hoặc ID cụ thể để giới hạn truy cập vào các tài nguyên riêng lẻ

    • datasources:uid:prometheus-uid - Chỉ truy cập một nguồn dữ liệu Prometheus cụ thể
    • dashboards:uid:abc123 - Chỉ truy cập bảng điều khiển có UID abc123
    • folders:uid:xyz789 - Chỉ truy cập thư mục có UID xyz789
    • teams:id:5 - Chỉ truy cập nhóm có ID 5
    • global.users:id:123 - Chỉ truy cập người dùng có ID 123

Ví dụ:

  • Truy cập máy chủ MCP đầy đủ: Cấp quyền rộng rãi cho tất cả công cụ

    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)

  • Truy cập nguồn dữ liệu hạn chế: Chỉ truy vấn các phiên bản Prometheus và Loki cụ thể

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

  • Truy cập cụ thể theo bảng điều khiển: Chỉ đọc các bảng điều khiển cụ thể

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

Công cụ

Công cụDanh mụcMô tảQuyền RBAC bắt buộcPhạm vi bắt buộc
list_teamsQuản trịLiệt kê tất cả các nhómteams:readteams:* hoặc teams:id:1
list_users_by_orgQuản trịLiệt kê tất cả người dùng trong một tổ chứcusers:readglobal.users:* hoặc global.users:id:123
list_all_rolesQuản trịLiệt kê tất cả các vai trò Grafanaroles:readroles:*
get_role_detailsQuản trịLấy chi tiết cho một vai trò Grafanaroles:readroles:uid:editor
get_role_assignmentsQuản trịLiệt kê các phân công cho một vai tròroles:readroles:uid:editor
list_user_rolesQuản trịLiệt kê các vai trò cho người dùngroles:readglobal.users:id:123
list_team_rolesQuản trịLiệt kê các vai trò cho nhómroles:readteams:id:7
get_resource_permissionsQuản trịLiệt kê các quyền cho một tài nguyênpermissions:readdashboards:uid:abcd1234
get_resource_descriptionQuản trịMô tả một loại tài nguyên Grafanapermissions:readdashboards:*
user_infoNgười dùngDanh tính hiện tại, khả năng và các tổ chức có thể truy cậpKhông có (người dùng đã đăng nhập)—
search_dashboardsTìm kiếmTìm kiếm bảng điều khiểndashboards:readdashboards:* hoặc dashboards:uid:abc123
get_dashboard_by_uidBảng điều khiểnLấy một bảng điều khiển theo uiddashboards:readdashboards:uid:abc123
update_dashboardBảng điều khiểnCập nhật hoặc tạo mới một bảng điều khiểndashboards:create, dashboards:writedashboards:*, folders:* hoặc folders:uid:xyz789
get_dashboard_panel_queriesBảng điều khiểnLấy tiêu đề bảng điều khiển, truy vấn, UID nguồn dữ liệu và loại từ một bảng điều khiểndashboards:readdashboards:uid:abc123
run_panel_queryChạyTruyVấnBảng*Thực thi một hoặc nhiều truy vấn bảng điều khiểndashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyBảng điều khiểnTrích xuất các phần cụ thể của một bảng điều khiển bằng biểu thức JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryBảng điều khiểnLấy một bản tóm tắt gọn gàng của một bảng điều khiển mà không có JSON đầy đủdashboards:readdashboards:uid:abc123
list_datasourcesNguồn dữ liệuLiệt kê các nguồn dữ liệudatasources:readdatasources:*
get_datasourceNguồn dữ liệuLấy một nguồn dữ liệu theo UID hoặc têndatasources:readdatasources:uid:prometheus-uid
get_query_examplesVí dụ*Lấy các truy vấn ví dụ cho một loại nguồn dữ liệudatasources:readdatasources:*
query_prometheusPrometheusThực thi một truy vấn đối với một nguồn dữ liệu Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusLiệt kê siêu dữ liệu chỉ sốdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusLiệt kê các tên chỉ số khả dụngdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusLiệt kê các tên nhãn khớp với một bộ chọndatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusLiệt kê các giá trị cho một nhãn cụ thểdatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusTính toán các giá trị phân vị biểu đồdatasources:querydatasources:uid:prometheus-uid
list_incidentsSự cốLiệt kê các sự cố trong Grafana Incident, tùy chọn với các giá trị trường tùy chỉnh của chúngVai trò Người xemN/A
create_incidentSự cốTạo một sự cố trong Grafana Incident, tùy chọn đặt các trường tùy chỉnhVai trò Biên tập viênN/A
add_activity_to_incidentSự cốThêm một mục hoạt động vào một sự cố trong Grafana IncidentVai trò Biên tập viênN/A
update_incidentSự cốCập nhật một sự cố trong Grafana Incident (trạng thái, mức độ nghiêm trọng, tiêu đề hoặc trường tùy chỉnh)Vai trò Biên tập viênN/A
get_incidentSự cốLấy một sự cố theo ID, bao gồm các trường tùy chỉnh của nóVai trò Người xemN/A
list_incident_custom_fieldsSự cốLiệt kê các trường tùy chỉnh được cấu hình cho sự cố, với loại và tùy chọn chọn của chúngVai trò Người xemN/A
query_loki_logsLokiTruy vấn và truy xuất nhật ký bằng LogQL (truy vấn nhật ký hoặc chỉ số)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiLiệt kê tất cả các tên nhãn khả dụng trong nhật kýdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiLiệt kê các giá trị cho một nhãn nhật ký cụ thểdatasources:querydatasources:uid:loki-uid
query_loki_statsLokiLấy thống kê về các luồng nhật kýdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiTruy vấn các mẫu nhật ký được phát hiện để xác định các cấu trúc phổ biếndatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiKiểm tra chiến lược nhãn Loki (trực tiếp hoặc tĩnh) và tùy chọn chẩn đoán hiệu suất truy vấndatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configCấu hìnhTạo một đoạn mã Alloy loki.process thực thi các nhãn được phê duyệtN/AN/A
query_influxdbInfluxDBTruy vấn InfluxDB bằng InfluxQL (v1) hoặc Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Liệt kê các bảng trong cơ sở dữ liệu ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Lấy lược đồ bảng với các kiểu cộtdatasources:querydatasources:uid:*
query_clickhouseClickHouse*Thực thi truy vấn SQL với thay thế macrodatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Liệt kê các namespace AWS CloudWatch khả dụngdatasources:querydatasources:uid:*
list_cloudwatch_metricsCloudWatch*Liệt kê các số liệu trong một namespacedatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Liệt kê các thứ nguyên cho một số liệudatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Thực thi các truy vấn số liệu CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Liệt kê các danh mục dữ liệu Athena khả dụngdatasources:querydatasources:uid:*
list_athena_databasesAthena*Liệt kê các cơ sở dữ liệu trong danh mục Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Liệt kê các bảng trong cơ sở dữ liệu Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Lấy tên các cột cho một bảng Athenadatasources:querydatasources:uid:*
query_athenaAthena*Thực thi truy vấn SQL với thay thế macrodatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Truy vấn Elasticsearch hoặc OpenSearch bằng cú pháp Lucene hoặc Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Truy vấn Quickwit bằng cú pháp Lucene hoặc Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Liệt kê các bảng trong cơ sở dữ liệu/lược đồ Snowflake qua INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Lấy lược đồ bảng (kiểu cột, khả năng null, giá trị mặc định, chú thích)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Thực thi truy vấn SQL với thay thế macro/biếndatasources:querydatasources:uid:*
alerting_manage_rulesAlertingQuản lý quy tắc cảnh báo (liệt kê, lấy, phiên bản, tạo, cập nhật, xóa)alert.rules:read + alert.rules:write cho các thay đổifolders:* hoặc folders:uid:alerts-folder
alerting_manage_routingAlertingQuản lý chính sách thông báo, điểm liên hệ và khoảng thời gianalert.notifications:readPhạm vi toàn cục
alerting_manage_silencesAlertingQuản lý các khoảng im lặng cảnh báo (liệt kê, lấy, tạo, cập nhật, hết hạn)alert.instances:read + alert.instances:write cho các thay đổiPhạm vi toàn cục
list_oncall_schedulesOnCallLiệt kê các lịch trình từ Grafana OnCallgrafana-oncall-app.schedules:readPhạm vi cụ thể của plugin
get_oncall_shiftOnCallLấy chi tiết cho một ca trực OnCall cụ thểgrafana-oncall-app.schedules:readPhạm vi cụ thể của plugin
get_current_oncall_usersOnCallLấy người dùng hiện đang trực cho một lịch trình cụ thểgrafana-oncall-app.schedules:readPhạm vi cụ thể của plugin
list_oncall_teamsOnCallLiệt kê các nhóm từ Grafana OnCallgrafana-oncall-app.user-settings:readPhạm vi cụ thể của plugin
list_oncall_usersOnCallLiệt kê người dùng từ Grafana OnCallgrafana-oncall-app.user-settings:readPhạm vi cụ thể của plugin
list_alert_groupsOnCallLiệt kê các nhóm cảnh báo từ Grafana OnCall với các tùy chọn lọcgrafana-oncall-app.alert-groups:readPhạm vi cụ thể của plugin
get_alert_groupOnCallLấy một nhóm cảnh báo cụ thể từ Grafana OnCall theo ID của nógrafana-oncall-app.alert-groups:readPhạm vi cụ thể của plugin
update_alert_groupOnCallXác nhận, hủy xác nhận, giải quyết hoặc hủy giải quyết một nhóm cảnh báografana-oncall-app.alert-groups:write (và :read)Phạm vi cụ thể của plugin
get_sift_investigationSiftTruy xuất một cuộc điều tra Sift hiện có theo UUID của nóVai trò ViewerN/A
get_sift_analysisSiftTruy xuất một phân tích cụ thể từ một cuộc điều tra SiftVai trò ViewerN/A
list_sift_investigationsSiftTruy xuất danh sách các cuộc điều tra Sift với giới hạn tùy chọnVai trò ViewerN/A
find_error_pattern_logsSiftTìm các mẫu lỗi nâng cao trong nhật ký Loki.Vai trò EditorN/A
find_slow_requestsSiftTìm các yêu cầu chậm từ các nguồn dữ liệu tempo liên quan.Vai trò EditorN/A
list_pyroscope_label_namesPyroscopeLiệt kê tên nhãn khớp với bộ chọndatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeLiệt kê giá trị nhãn khớp với bộ chọn cho một tên nhãndatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeLiệt kê các loại hồ sơ khả dụngdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeTruy vấn hồ sơ, số liệu hoặc cả hai từ Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsLấy tóm tắt khẳng định cho một thực thể nhất địnhQuyền cụ thể của pluginPhạm vi cụ thể của plugin
agento11y_manage_conversationsAgent Observability*Liệt kê, tìm kiếm và tìm nạp các cuộc hội thoại LLM từ Grafana Agent Observabilitygrafana-agento11y-app.conversations:readN/A
agento11y_manage_generationsAgent Observability*Tìm nạp chi tiết tạo LLM và điểm đánh giá từ Grafana Agent Observabilitygrafana-agento11y-app.data:readN/A
agento11y_manage_agentsAgent Observability*Đọc danh mục tác nhân: liệt kê tác nhân, lấy toàn bộ một phiên bản tác nhân, liệt kê lịch sử phiên bản và tổng hợp điểm theo phiên bảngrafana-agento11y-app.data:readN/A
agento11y_manage_evaluatorsAgent Observability*Quản lý bộ đánh giá, mẫu bộ đánh giá và danh mục giám khảo (liệt kê, lấy, upsert, fork, kiểm tra, xóa)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write cho các thay đổi và kiểm traN/A
agento11y_manage_eval_rulesAgent Observability*Quản lý quy tắc đánh giá và bộ bảo vệ (liệt kê, lấy, tạo, cập nhật, xem trước, xóa)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write cho các thay đổi và xem trướcN/A
agento11y_manage_eval_collectionsAgent Observability*Quản lý các cuộc hội thoại đã lưu và các bộ sưu tập nhóm chúng lại (liệt kê, lấy, lưu, tạo, cập nhật, xóa, thêm và xóa thành viên)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write cho các thao tác thay đổiN/A
agento11y_manage_experimentsAgent Observability*Đọc các thử nghiệm ngoại tuyến, các lần chạy thử, điểm số, siêu dữ liệu tạo phẩm và các khía cạnh lọc; cập nhật và hủy một thử nghiệmgrafana-agento11y-app.data:read + grafana-agento11y-app.eval:write cho các thao tác thay đổiN/A
agento11y_manage_test_suitesAgent Observability*Quản lý các bộ kiểm thử mà các thử nghiệm ngoại tuyến chạy trên đó, các phiên bản của chúng và các trường hợp kiểm thử (liệt kê, lấy, tạo, cập nhật, nháp, xuất bản, upsert, xóa)grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write cho các thao tác thay đổiN/A
ask_assistantAssistant*Gửi một lời nhắc đến Grafana Assistant và trả về toàn bộ văn bản trả lời (nhiều lượt qua contextId)Quyền riêng của pluginPhạm vi riêng của plugin
generate_deeplinkĐiều hướngTạo các URL liên kết sâu chính xác cho các tài nguyên GrafanaKhông có (chỉ tạo URL chỉ đọc)N/A
get_annotationsChú thíchLấy các chú thích với bộ lọcannotations:readannotations:* hoặc annotations:id:123
create_annotationChú thíchTạo một chú thích mới (định dạng chuẩn hoặc Graphite)annotations:writeannotations:*
update_annotationChú thíchCập nhật các trường cụ thể của một chú thích (cập nhật một phần)annotations:writeannotations:*
get_annotation_tagsChú thíchLiệt kê các thẻ chú thích với bộ lọc tùy chọnannotations:readannotations:*
list_snapshotsẢnh chụp nhanhLiệt kê các ảnh chụp nhanh bảng điều khiển với bộ lọc truy vấn và giới hạn tùy chọndashboards:readdashboards:* hoặc dashboards:uid:abc123
get_snapshotẢnh chụp nhanhLấy siêu dữ liệu ảnh chụp nhanh và tải trọng bảng điều khiển theo khóa ảnh chụp nhanhdashboards:readdashboards:* hoặc dashboards:uid:abc123
create_snapshotẢnh chụp nhanhTạo một ảnh chụp nhanh bảng điều khiển từ một tải trọng bảng điều khiển đầy đủdashboards:writedashboards:* hoặc dashboards:uid:abc123
delete_snapshotẢnh chụp nhanhXóa một ảnh chụp nhanh bảng điều khiển theo khóa ảnh chụp nhanhdashboards:writedashboards:* hoặc dashboards:uid:abc123
get_panel_imageKết xuấtKết xuất một bảng điều khiển hoặc bảng điều khiển con đã lưu — hoặc bản xem trước cung cấp từ một nhánh kho lưu trữ — dưới dạng hình ảnh PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesCung cấpLiệt kê các kho lưu trữ cung cấp (ví dụ: nguồn git-sync) với URL nguồn, nhánh, trạng thái đồng bộ và tình trạng của chúngprovisioning.repositories:readN/A
validate_provisioning_fileCung cấpChạy thử áp dụng một tệp từ kho lưu trữ cung cấp và báo cáo các lỗi xác thực chấp nhậnprovisioning.repositories:readN/A
search_docsTài liệuTìm kiếm tài liệu Grafana hoặc liệt kê các nhóm sản phẩm (bỏ qua truy vấn để liệt kê sản phẩm)Không có (grafana.com/docs công khai)N/A
get_docTài liệuLấy một trang tài liệu; đặt outline_only cho các tiêu đề, hoặc section cho truy xuất giới hạnKhông có (grafana.com/docs công khai)N/A
* Bị tắt theo mặc định. Thêm category vào --enabled-tools để bật.

Tham chiếu Cờ Dòng Lệnh

Binary mcp-grafana hỗ trợ nhiều cờ dòng lệnh khác nhau để cấu hình:

Tùy chọn Transport:

  • -t, --transport: Loại transport (stdio, sse, hoặc streamable-http) - mặc định: stdio
  • --address: Host và port cho máy chủ SSE/streamable-http - mặc định: localhost:8000
  • --base-path: Đường dẫn cơ sở cho máy chủ SSE/streamable-http
  • --endpoint-path: Đường dẫn endpoint cho máy chủ streamable-http - mặc định: /mcp
  • --server-name: Tên máy chủ được sử dụng trong bắt tay MCP và OTel service.name - mặc định: mcp-grafana. Ghi đè biến môi trường GRAFANA_MCP_SERVER_NAME

Bảo mật Transport HTTP (chỉ SSE / streamable-http):

Xác thực Host/Origin được thực thi trên mọi route trên listener MCP — /sse, /mcp, và /healthz / /metrics khi chúng dùng chung listener đó — vì vậy trình duyệt DNS-rebinding không thể truy cập bất kỳ route nào trong số đó. Transport stdio không bị ảnh hưởng. --healthz-address và --metrics-address khởi động một listener riêng biệt không được bọc.

  • --allowed-hosts: Danh sách cho phép phân tách bằng dấu phẩy các giá trị header Host. Mặc định là các biến thể loopback của --address (ví dụ: localhost:8000,127.0.0.1:8000,[::1]:8000). Một giá trị phân tích thành rỗng (không được đặt, ,, ,, v.v.) cũng sẽ quay về mặc định để lỗi chính tả không thể âm thầm vô hiệu hóa kiểm tra. Các yêu cầu có header Host nằm ngoài danh sách cho phép sẽ bị từ chối với 403. Truyền * để tắt kiểm tra — chỉ an toàn khi chạy sau một reverse proxy đáng tin cậy ghi đè Host, hoặc trong mạng cô lập. Các probe httpGet của K8s và các lần scrape /metrics bên ngoài sẽ cần hostname tường minh trong danh sách này, *, probe tcpSocket, hoặc một port riêng (--healthz-address / --metrics-address).
  • --allowed-origins: Danh sách cho phép phân tách bằng dấu phẩy các giá trị header Origin. Mặc định trống — bất kỳ yêu cầu nào mang header Origin đều bị từ chối (trình duyệt luôn gửi header này cho các yêu cầu cross-origin và không trình duyệt nào nên gọi trực tiếp máy chủ này). Đặt danh sách tường minh để cho phép client dựa trên trình duyệt, hoặc * để tắt kiểm tra.

Xác thực Người gọi (chỉ SSE / streamable-http):

Tùy chọn yêu cầu client MCP xác thực với máy chủ. Điều này tách biệt với thông tin xác thực mà máy chủ sử dụng để truy cập Grafana. Stdio không bị ảnh hưởng.

  • --server-auth-token: Token Bearer mà người gọi phải gửi dưới dạng Authorization: Bearer <token>. Dự phòng sang biến môi trường MCP_GRAFANA_SERVER_TOKEN. Khi được đặt, các yêu cầu không có token hợp lệ sẽ bị từ chối với 401 trước khi bất kỳ công cụ nào chạy. Ưu tiên biến môi trường để bí mật không hiển thị trong các đối số tiến trình.

Xác thực người gọi chỉ được thực thi khi --server-auth-token được đặt. Khi không được đặt và máy chủ liên kết một địa chỉ không phải loopback, máy chủ khởi động nhưng ghi log lỗi bảo mật — được phát ra ở mức log error để không bị ẩn bởi --log-level (loopback và stdio không bị ảnh hưởng); một bản phát hành chính trong tương lai sẽ biến điều đó thành lỗi khởi động. Sử dụng TLS (hoặc kết thúc TLS) bất cứ khi nào xác thực người gọi được bật trên địa chỉ không phải loopback. Khi xác thực người gọi được bật, header Authorization đã xác thực sẽ bị loại bỏ trước khi yêu cầu đến Grafana; kết hợp --server-auth-token với GRAFANA_FORWARD_HEADERS=Authorization sẽ bị từ chối khi khởi động.

Gỡ lỗi và Ghi log:

  • --debug: Bật chế độ gỡ lỗi để ghi log chi tiết yêu cầu/phản hồi HTTP
  • --log-level: Mức log (debug, info, warn, error) - mặc định: info

Tùy chọn Client Grafana:

  • --grafana-timeout: Giới hạn thời gian cho các yêu cầu do client Grafana thực hiện. Chấp nhận chuỗi thời lượng Go (ví dụ: 10s, 500ms) - mặc định: 10s
  • --include-args-in-spans: Bao gồm các đối số gọi công cụ trong các span OpenTelemetry. Chỉ bật trong môi trường không phải sản xuất hoặc khi các đối số được biết là không chứa PII - mặc định: false

Khả năng quan sát:

  • --metrics: Bật endpoint metrics Prometheus tại /metrics
  • --metrics-address: Địa chỉ riêng cho máy chủ metrics (ví dụ: :9090). Nếu trống, metrics được phục vụ trên máy chủ chính
  • --healthz-address: Địa chỉ riêng cho /healthz (ví dụ: :8080). Nếu trống, /healthz được phục vụ trên máy chủ chính. Dùng chung listener với --metrics-address khi hai địa chỉ khớp nhau. Các listener phụ bỏ qua xác thực Host/Origin.
  • --slow-request-threshold: Ghi log một sự kiện khi bất kỳ yêu cầu MCP nào (gọi công cụ, danh sách, đọc tài nguyên, v.v.) mất nhiều thời gian hơn thời lượng này. Chấp nhận chuỗi thời lượng Go (ví dụ: 500ms, 5s). Mặc định 0 tắt ghi log yêu cầu chậm. Xem phần Ghi log yêu cầu chậm.
  • --slow-request-log-level: Mức log cho các sự kiện yêu cầu chậm (info hoặc warn) - mặc định: warn.

Quản lý Phiên:

  • --session-idle-timeout-minutes: Thời gian chờ phiên không hoạt động tính bằng phút. Các phiên không có hoạt động trong khoảng thời gian này sẽ tự động bị thu hồi - mặc định: 30. Đặt thành 0 để tắt thu hồi phiên. Chỉ áp dụng cho transport SSE và streamable-http.

Cấu hình Công cụ:

  • --enabled-tools: Danh sách phân tách bằng dấu phẩy các category được bật - mặc định: tất cả category trừ admin, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, và snowflake. Để bật các category bị tắt, hãy thêm chúng vào danh sách (ví dụ: "search,datasource,...,snowflake")
  • --max-loki-log-limit: Số dòng log tối đa được trả về cho mỗi lần gọi query_loki_logs - mặc định: 100. Lưu ý: Đặt giá trị này ít nhất là 1 dưới max_entries_limit_per_query phía máy chủ của Loki để cho phép phát hiện cắt ngắn (công cụ yêu cầu limit+1 nội bộ để phát hiện xem có thêm dữ liệu hay không).
  • --loki-guardrail-mode: Rào cản chi phí truy vấn Loki cho query_loki_logs - mặc định: off. Loki không thực thi max_query_bytes_read trên các truy vấn log không có bộ lọc dòng, vì vậy một bộ chọn rộng trên phạm vi lớn có thể quét hàng terabyte; rào cản yêu cầu một bộ chọn luồng chọn lọc, giới hạn phạm vi thời gian hiệu quả (bao gồm cả thời lượng range-vector như [30d]) và kiểm tra trước ước tính byte index/stats của Loki trước khi chạy truy vấn. shadow ghi log các truy vấn sẽ bị chặn nhưng vẫn cho chạy (vẫn trả chi phí khứ hồi index/stats); enforce từ chối chúng với hướng dẫn viết lại mà LLM có thể hành động. Trên VictoriaLogs, rào cản chỉ áp dụng cho các truy vấn dạng bộ chọn ({...}) — khi không có bộ chọn nào phân tích được (dạng LogsQL không có dấu ngoặc nhọn thông thường), truy vấn đi qua hoàn toàn và kiểm tra ngân sách byte không bao giờ được áp dụng (không có ước tính index rẻ). Dự phòng env: GRAFANA_LOKI_GUARDRAIL_MODE.
  • --loki-guardrail-max-bytes: Số byte tối đa mà một lần gọi query_loki_logs có thể quét, được ước tính qua API index/stats của Loki - mặc định: 107374182400 (100 GiB). 0 tắt kiểm tra ngân sách byte. Dự phòng env: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
  • --loki-guardrail-max-range: Phạm vi thời gian hiệu quả tối đa cho một lần gọi query_loki_logs, bao gồm cả thời lượng range-vector - mặc định: 24h. Chấp nhận chuỗi thời lượng Go. 0 tắt kiểm tra phạm vi. Dự phòng env: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
  • --disable-search: Tắt các công cụ tìm kiếm
  • --disable-datasource: Tắt các công cụ datasource
  • --disable-incident: Tắt các công cụ incident
  • --disable-prometheus: Tắt các công cụ prometheus
  • --disable-write: Tắt các công cụ ghi (các thao tác tạo/cập nhật)
  • --disable-query: Tắt các công cụ truy vấn (các công cụ thực thi truy vấn đối với datasource); các công cụ metadata và discovery vẫn khả dụng
  • --enable-query: Giữ các công cụ truy vấn SQL thô (query_clickhouse, query_snowflake, query_athena, query_influxdb) được đăng ký ngay cả dưới --disable-write
  • --disable-loki: Tắt các công cụ loki
  • --disable-elasticsearch: Tắt các công cụ elasticsearch và opensearch
  • --disable-quickwit: Tắt các công cụ quickwit
  • --disable-influxdb: Tắt các công cụ InfluxDB
  • --disable-alerting: Tắt các công cụ alerting
  • --disable-dashboard: Tắt các công cụ dashboard
  • --disable-oncall: Tắt các công cụ oncall
  • --disable-asserts: Tắt các công cụ asserts
  • --disable-sift: Tắt các công cụ sift
  • --disable-admin: Tắt các công cụ admin
  • --disable-pyroscope: Tắt các công cụ pyroscope
  • --disable-navigation: Tắt các công cụ điều hướng
  • --disable-rendering: Tắt các công cụ rendering (xuất ảnh panel/dashboard)
  • --disable-snapshot: Tắt các công cụ snapshot
  • --disable-cloudwatch: Tắt các công cụ CloudWatch
  • --disable-examples: Tắt các công cụ ví dụ truy vấn
  • --disable-clickhouse: Tắt các công cụ ClickHouse
  • --disable-snowflake: Tắt các công cụ Snowflake
  • --disable-runpanelquery: Tắt các công cụ chạy truy vấn panel
  • --disable-graphite: Tắt các công cụ Graphite
  • --disable-athena: Tắt các công cụ Athena
  • --disable-provisioning: Tắt các công cụ provisioning
  • --disable-agento11y: Tắt các công cụ Agent Observability
  • --disable-assistant: Tắt các công cụ Grafana Assistant
  • --disable-docs: Tắt các công cụ tài liệu

Chế độ Chỉ Đọc

Cờ --disable-write cung cấp một cách để chạy máy chủ MCP ở chế độ chỉ đọc, ngăn chặn mọi thao tác ghi vào instance Grafana của bạn. Điều này hữu ích cho các tình huống bạn muốn cung cấp quyền truy cập chỉ đọc an toàn như:

  • Sử dụng service account với quyền chỉ đọc hạn chế
  • Cung cấp cho trợ lý AI dữ liệu quan sát mà không có khả năng sửa đổi
  • Chạy trong môi trường sản xuất nơi quyền ghi nên bị hạn chế
  • Các tình huống kiểm thử và phát triển nơi bạn muốn ngăn chặn các sửa đổi vô tình

Khi --disable-write được bật, các thao tác ghi sau bị vô hiệu hóa:

Công cụ Dashboard:

  • update_dashboard

Công cụ Thư mục:

  • create_folder

Công cụ Incident:

  • create_incident
  • add_activity_to_incident
  • update_incident

Công cụ Alerting:

  • alerting_manage_rules (các thao tác tạo, cập nhật, xóa)
  • alerting_manage_silences (các thao tác tạo, cập nhật, xóa)

Công cụ OnCall:

  • update_alert_group

Công cụ Chú thích:

  • create_annotation
  • update_annotation

Công cụ Sift:

  • find_error_pattern_logs (tạo investigation)
  • find_slow_requests (tạo investigation)

Công cụ Snapshot:

  • create_snapshot
  • delete_snapshot

Công cụ Truy vấn SQL Thô:

Các công cụ này thực thi bất kỳ truy vấn nào bạn đưa cho chúng mà không kiểm tra, vì vậy chúng có thể ghi khi thông tin xác thực datasource cho phép — query_clickhouse sẽ chạy DROP TABLE, query_influxdb sẽ chạy DELETE. Do đó, chế độ chỉ đọc sẽ loại bỏ chúng. Truyền --enable-query để giữ chúng khi thông tin xác thực datasource được biết là chỉ đọc.

  • query_clickhouse
  • query_snowflake
  • query_athena
  • query_influxdb

Công cụ Agent Observability:

  • agento11y_manage_evaluators (các thao tác upsert, xóa, fork, kiểm tra evaluator)
  • agento11y_manage_eval_rules (các thao tác tạo, cập nhật, xóa, xem trước rule và guard)
  • agento11y_manage_eval_collections (lưu và xóa các cuộc trò chuyện đã lưu; tạo, cập nhật, xóa collection; thêm và xóa thành viên collection)
  • agento11y_manage_experiments (các thao tác cập nhật và hủy experiment)
  • agento11y_manage_test_suites (tạo và cập nhật test suite; tạo và xuất bản version; upsert và xóa test case)

Tất cả các thao tác đọc vẫn khả dụng, cho phép bạn truy vấn dashboard, chạy truy vấn PromQL/LogQL, liệt kê tài nguyên và truy xuất dữ liệu. Các ngôn ngữ truy vấn không thể biểu thị thao tác ghi — PromQL, LogQL, TraceQL, Elasticsearch DSL, Graphite, CloudWatch — vẫn giữ các công cụ truy vấn của chúng ở chế độ chỉ đọc; chỉ các công cụ SQL thô được liệt kê ở trên bị loại bỏ.

Chế độ Không Truy vấn

Cờ --disable-query loại bỏ mọi công cụ thực thi truy vấn đối với một nguồn dữ liệu, đồng thời giữ nguyên các công cụ siêu dữ liệu và khám phá. Điều này hữu ích khi bạn muốn một trợ lý có thể khám phá những gì tồn tại — nguồn dữ liệu, bảng điều khiển, tên số liệu, nhãn, lược đồ bảng — mà không chạy các truy vấn có thể tốn kém hoặc tiết lộ dữ liệu, ví dụ khi tài khoản dịch vụ có datasources:read nhưng không có datasources:query.

Đây là thiết lập mạnh nhất trong ba thiết lập truy vấn và nó thắng --enable-query:

CờCông cụ truy vấn an toàn (query_prometheus, query_loki_logs, run_panel_query, …)Công cụ truy vấn SQL thô (query_clickhouse, query_snowflake, query_athena, query_influxdb)
(không có)đã đăng kýđã đăng ký
--disable-writeđã đăng kýchưa đăng ký
--disable-write --enable-queryđã đăng kýđã đăng ký
--disable-querychưa đăng kýchưa đăng ký
--disable-query --enable-querychưa đăng kýchưa đăng ký

Khi --disable-query được bật, các công cụ sau không được đăng ký:

Công cụ Prometheus:

  • query_prometheus
  • query_prometheus_histogram

Công cụ Loki:

  • query_loki_logs
  • query_loki_patterns

query_loki_stats và analyze_loki_labels vẫn được đăng ký: cả hai đều gửi một bộ chọn đến nguồn dữ liệu, nhưng chúng đọc chỉ mục và trả về số lượng luồng, khối và byte thay vì nội dung nhật ký.

Công cụ Elasticsearch/OpenSearch và Quickwit:

  • query_elasticsearch
  • query_quickwit

Công cụ InfluxDB (cũng bị loại bỏ bởi --disable-write, xem ở trên):

  • query_influxdb

Công cụ nguồn dữ liệu SQL (cũng bị loại bỏ bởi --disable-write, xem ở trên):

  • query_clickhouse
  • query_snowflake
  • query_athena

Công cụ Graphite:

  • query_graphite
  • query_graphite_density

Công cụ CloudWatch:

  • query_cloudwatch

Công cụ Pyroscope:

  • query_pyroscope

Công cụ truy vấn bảng điều khiển:

  • run_panel_query

Các danh mục elasticsearch, quickwit, influxdb và runpanelquery không chứa gì khác, vì vậy chúng không đăng ký công cụ nào khi truy vấn bị vô hiệu hóa. Các công cụ liên quan trong mọi danh mục khác — list_prometheus_metric_names, list_loki_label_values, describe_clickhouse_table, list_cloudwatch_metrics, v.v. — vẫn khả dụng.

Lưu ý rằng --disable-query kiểm soát các công cụ truy vấn và đường dẫn POST đến grafana_api_request đến /api/ds/query, nhưng không kiểm soát mọi tuyến đường đến nguồn dữ liệu. Trong chế độ chỉ đọc, grafana_api_request cho phép POST đến /api/ds/query chỉ khi các công cụ truy vấn được bật (cùng cổng kiểm soát như các công cụ SQL thô — bị chặn bởi --disable-write trừ khi --enable-query ghi đè). get_panel_image, công cụ kết xuất bảng điều khiển phía máy chủ, không bị ảnh hưởng.

Cấu hình TLS máy khách (cho kết nối Grafana):

  • --tls-cert-file: Đường dẫn đến tệp chứng chỉ TLS để xác thực máy khách
  • --tls-key-file: Đường dẫn đến tệp khóa riêng TLS để xác thực máy khách
  • --tls-ca-file: Đường dẫn đến tệp chứng chỉ CA TLS để xác minh máy chủ
  • --tls-skip-verify: Bỏ qua xác minh chứng chỉ TLS (không an toàn)

Cấu hình TLS máy chủ (chỉ vận chuyển streamable-http):

  • --server.tls-cert-file: Đường dẫn đến tệp chứng chỉ TLS cho HTTPS máy chủ
  • --server.tls-key-file: Đường dẫn đến tệp khóa riêng TLS cho HTTPS máy chủ

Cách sử dụng

Máy chủ MCP này hoạt động với cả phiên bản Grafana cục bộ và Grafana Cloud. Đối với Grafana Cloud, hãy sử dụng URL phiên bản của bạn (ví dụ: https://myinstance.grafana.net) thay vì http://localhost:3000 trong các ví dụ cấu hình bên dưới.

  1. Nếu sử dụng xác thực bằng mã thông báo tài khoản dịch vụ, hãy tạo một tài khoản dịch vụ trong Grafana với đủ quyền để sử dụng các công cụ bạn muốn, tạo mã thông báo tài khoản dịch vụ và sao chép nó vào bộ nhớ tạm để sử dụng trong tệp cấu hình. Làm theo tài liệu tài khoản dịch vụ Grafana để biết chi tiết về cách tạo mã thông báo tài khoản dịch vụ. Mẹo: Nếu bạn không thoải mái khi cấu hình phạm vi RBAC chi tiết, một tùy chọn đơn giản hơn (nhưng ít hạn chế hơn) là gán vai trò tích hợp Editor cho tài khoản dịch vụ. Điều này cấp quyền đọc/ghi rộng rãi bao phủ hầu hết các hoạt động của máy chủ MCP — hãy sử dụng nó khi sự tiện lợi quan trọng hơn yêu cầu đặc quyền tối thiểu nghiêm ngặt.

    Lưu ý: Biến môi trường GRAFANA_API_KEY đã không được dùng nữa và sẽ bị xóa trong phiên bản tương lai. Vui lòng di chuyển sang sử dụng GRAFANA_SERVICE_ACCOUNT_TOKEN thay thế. Tên biến cũ sẽ tiếp tục hoạt động để tương thích ngược nhưng sẽ hiển thị cảnh báo không dùng nữa.

Đọc mã thông báo tài khoản dịch vụ từ tệp

Thay vì truyền mã thông báo trực tiếp qua GRAFANA_SERVICE_ACCOUNT_TOKEN, bạn có thể trỏ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE đến một đường dẫn tệp chứa mã thông báo. Tệp được đọc mới cho mỗi yêu cầu, vì vậy các mã thông báo đã xoay vòng được tự động nhận mà không cần khởi động lại máy chủ.

Điều này đặc biệt hữu ích trong Kubernetes, nơi một Secret được gắn làm ổ đĩa được cập nhật tại chỗ khi Secret cơ bản thay đổi (thường trong khoảng ~1 phút). Kết hợp với bộ nhớ đệm máy khách theo yêu cầu — được khóa theo giá trị mã thông báo — một mã thông báo đã xoay vòng sẽ minh bạch tạo ra một máy khách mới mà không cần khởi động lại pod và không có thời gian chết:

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

Khoảng trắng xung quanh (bao gồm cả dòng mới ở cuối) được cắt bớt khỏi nội dung tệp. Nếu cả GRAFANA_SERVICE_ACCOUNT_TOKEN và GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE được đặt, mã thông báo trực tiếp sẽ được ưu tiên.

Hỗ trợ nhiều tổ chức

Bạn có thể chỉ định tổ chức mà bạn muốn tương tác bằng cách sử dụng:

  • Biến môi trường: Đặt GRAFANA_ORG_ID thành ID tổ chức dạng số
  • Tiêu đề HTTP: Đặt X-Grafana-Org-Id khi sử dụng vận chuyển SSE hoặc streamable HTTP (tiêu đề được ưu tiên hơn biến môi trường — nghĩa là bạn có thể đặt một tổ chức mặc định).

Khi ID tổ chức được cung cấp, máy chủ MCP sẽ đặt tiêu đề X-Grafana-Org-Id trên tất cả các yêu cầu đến Grafana, đảm bảo rằng các hoạt động được thực hiện trong ngữ cảnh tổ chức được chỉ định.

Chọn tổ chức động (theo từng lệnh gọi)

Các tùy chọn trên cố định tổ chức cho toàn bộ kết nối. Để cho phép một kết nối duy nhất nhắm mục tiêu các tổ chức khác nhau cho mỗi lệnh gọi công cụ, hãy khởi động máy chủ với cờ --dynamic-multi-org. Tùy chọn này tắt theo mặc định.

Khi được bật, mọi công cụ chấp nhận một đối số orgId tùy chọn ghi đè tổ chức của kết nối cho lệnh gọi đó (điều khiển cả tiêu đề X-Grafana-Org-Id và, đối với API nền tảng ứng dụng, không gian tên Kubernetes đã phân giải). Các công cụ nguồn dữ liệu được ủy quyền cũng được khám phá trên mọi tổ chức mà thông tin xác thực có thể truy cập. Các lệnh gọi bỏ qua orgId sử dụng tổ chức mặc định của kết nối.

Điều này chỉ hoạt động với thông tin xác thực thuộc về nhiều hơn một tổ chức (ví dụ: danh tính người dùng hoặc thay mặt); mã thông báo tài khoản dịch vụ vẫn bị ràng buộc với tổ chức duy nhất của nó. Sử dụng công cụ user_info để khám phá giá trị orgId nào hợp lệ.

Ví dụ với ID tổ chức:

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

Tiêu đề HTTP tùy chỉnh

Bạn có thể thêm các tiêu đề HTTP tùy ý vào tất cả các yêu cầu API Grafana bằng biến môi trường GRAFANA_EXTRA_HEADERS. Giá trị phải là một đối tượng JSON ánh xạ tên tiêu đề đến giá trị.

Ví dụ với tiêu đề tùy chỉnh:

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

Proxy SOCKS5

Bạn có thể định tuyến tất cả các yêu cầu mà máy chủ này thực hiện đến Grafana thông qua proxy SOCKS5 bằng biến môi trường GRAFANA_SOCKS5_PROXY. Proxy được giới hạn trong lưu lượng Grafana của máy chủ này: nó không sửa đổi các biến toàn cục HTTP_PROXY/HTTPS_PROXY và khi được đặt, nó ghi đè lựa chọn proxy của chúng chỉ cho vận chuyển Grafana, mà không ảnh hưởng đến các máy chủ MCP khác hoặc phiên shell của bạn. Khi không được đặt, hành vi không thay đổi.

URL phải sử dụng lược đồ socks5:// hoặc socks5h:// (Go xử lý chúng giống hệt nhau: phân giải tên máy chủ được ủy quyền cho proxy) và có thể bao gồm thông tin xác thực, ví dụ: socks5://user:pass@127.0.0.1:1080.

Ví dụ:

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

Một URL proxy không hợp lệ là lỗi khởi động và nếu việc xây dựng kết nối được ủy quyền thất bại tại thời điểm chạy, máy chủ sẽ đóng an toàn thay vì âm thầm gửi lưu lượng Grafana trực tiếp.

Chuyển tiếp tiêu đề từ máy khách (Chỉ SSE/Streamable-HTTP)

Khi máy chủ MCP chạy phía sau một cổng hoặc proxy ngược xử lý SSO (ví dụ: AWS ALB với OIDC), cookie phiên của mỗi người dùng phải đến được Grafana để nó có thể liên kết yêu cầu với người dùng đã xác thực. Biến môi trường GRAFANA_FORWARD_HEADERS cho phép điều này bằng cách chỉ định danh sách cho phép phân tách bằng dấu phẩy các tên tiêu đề để sao chép từ yêu cầu HTTP đến đến mọi yêu cầu API Grafana gửi đi.

Điều này chỉ áp dụng khi sử dụng vận chuyển SSE (-t sse) hoặc streamable-http (-t streamable-http). Nó không có hiệu lực trong chế độ stdio.

Ví dụ: chuyển tiếp cookie phiên

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

Bạn có thể chuyển tiếp nhiều tiêu đề bằng cách phân tách chúng bằng dấu phẩy:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Các tiêu đề được chuyển tiếp được hợp nhất với bất kỳ tiêu đề nào được xác định trong GRAFANA_EXTRA_HEADERS. Nếu một tên tiêu đề xuất hiện trong cả hai, giá trị từ yêu cầu đến sẽ được ưu tiên cho yêu cầu đó.

Các tiêu đề ngữ cảnh theo dõi (traceparent, tracestate, baggage) là ngoại lệ: máy chủ tự truyền bá ngữ cảnh theo dõi, vì vậy một giá trị được chuyển tiếp không bao giờ ghi đè giá trị mà nó chèn. Xem khả năng quan sát.

  1. Bạn có một số tùy chọn để cài đặt mcp-grafana:

    • uvx (khuyến nghị): Nếu bạn đã cài đặt uv, không cần thiết lập thêm — uvx sẽ tự động tải xuống và chạy máy chủ:

      uvx mcp-grafana

    • Hình ảnh Docker: Sử dụng hình ảnh Docker được xây dựng sẵn từ Docker Hub.

      Quan trọng: Điểm vào của hình ảnh Docker được cấu hình để chạy máy chủ MCP ở chế độ SSE theo mặc định, nhưng hầu hết người dùng sẽ muốn sử dụng chế độ STDIO để tích hợp trực tiếp với các trợ lý AI như Claude Desktop:

      1. Chế độ STDIO: Đối với chế độ stdio, bạn phải ghi đè mặc định một cách rõ ràng bằng -t stdio và bao gồm cờ -i để giữ stdin mở:
      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

      Lưu ý — bảo mật các chế độ mạng: Trong các chế độ SSE và streamable-http, vùng chứa liên kết một địa chỉ không phải loopback (0.0.0.0:8000). Nếu không có mã thông báo người gọi, máy chủ khởi động nhưng ghi nhật ký lỗi bảo mật (ở mức nhật ký error, vì vậy nó không bị ẩn bởi --log-level; và nó sẽ từ chối khởi động trong bản phát hành chính trong tương lai). Đặt MCP_GRAFANA_SERVER_TOKEN để yêu cầu Authorization: Bearer <token> từ máy khách (khuyến nghị). Chế độ STDIO không bị ảnh hưởng. Xem Xác thực người gọi.

      1. Chế độ SSE: Trong chế độ này, máy chủ chạy như một máy chủ HTTP mà máy khách kết nối đến. Bạn phải mở cổng 8000 bằng cờ -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. Chế độ Streamable HTTP: Trong chế độ này, máy chủ hoạt động như một quy trình độc lập có thể xử lý nhiều kết nối máy khách. Bạn phải mở cổng 8000 bằng cờ -p: Đối với chế độ này, bạn phải ghi đè mặc định một cách rõ ràng bằng -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

      Đối với chế độ streamable HTTP HTTPS với chứng chỉ TLS máy chủ:

      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

    • Tải xuống tệp nhị phân: Tải xuống bản phát hành mới nhất của mcp-grafana từ trang phát hành và đặt nó vào $PATH của bạn.

    • Xây dựng từ mã nguồn: Nếu bạn đã cài đặt bộ công cụ Go, bạn cũng có thể xây dựng và cài đặt từ mã nguồn, sử dụng biến môi trường GOBIN để chỉ định thư mục nơi tệp nhị phân sẽ được cài đặt. Thư mục này cũng phải nằm trong $PATH của bạn.

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

    • Triển khai lên Kubernetes bằng Helm: sử dụng biểu đồ Helm từ kho lưu trữ helm-charts của 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. Thêm cấu hình máy chủ vào tệp cấu hình máy khách của bạn. Ví dụ: đối với Claude Desktop:

    Nếu sử dụng uvx:

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

    Nếu sử dụng tệp nhị phân:

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

Lưu ý: nếu bạn thấy Error: spawn mcp-grafana ENOENT trong Claude Desktop, bạn cần chỉ định đường dẫn đầy đủ đến mcp-grafana.

Nếu sử dụng 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"
      }
    }
  }
}

Lưu ý: Đối số -t stdio là cần thiết ở đây vì nó ghi đè chế độ SSE mặc định trong hình ảnh Docker.

Sử dụng VSCode với máy chủ MCP từ xa Nếu bạn đang sử dụng VSCode và chạy máy chủ MCP ở chế độ SSE (chế độ mặc định khi sử dụng Docker image mà không ghi đè transport), hãy đảm bảo .vscode/settings.json của bạn bao gồm những điều sau:

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

Đối với chế độ HTTPS streamable HTTP với chứng chỉ TLS máy chủ:

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

Chế độ gỡ lỗi

Bạn có thể bật chế độ gỡ lỗi cho transport Grafana bằng cách thêm cờ -debug vào lệnh. Điều này sẽ cung cấp nhật ký chi tiết về các yêu cầu và phản hồi HTTP giữa máy chủ MCP và API Grafana, hữu ích cho việc khắc phục sự cố.

Để sử dụng chế độ gỡ lỗi với cấu hình Claude Desktop, hãy cập nhật cấu hình của bạn như sau:

Nếu sử dụng binary:

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

Nếu sử dụng 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>"
      }
    }
  }
}

Lưu ý: Giống như cấu hình tiêu chuẩn, đối số -t stdio là bắt buộc để ghi đè chế độ SSE mặc định trong Docker image.

Cấu hình TLS

Nếu phiên bản Grafana của bạn nằm sau mTLS hoặc yêu cầu chứng chỉ TLS tùy chỉnh, bạn có thể cấu hình máy chủ MCP để sử dụng chứng chỉ tùy chỉnh. Máy chủ hỗ trợ các tùy chọn cấu hình TLS sau:

  • --tls-cert-file: Đường dẫn đến tệp chứng chỉ TLS để xác thực máy khách
  • --tls-key-file: Đường dẫn đến tệp khóa riêng TLS để xác thực máy khách
  • --tls-ca-file: Đường dẫn đến tệp chứng chỉ CA TLS để xác minh máy chủ
  • --tls-skip-verify: Bỏ qua xác minh chứng chỉ TLS (không an toàn, chỉ dùng để kiểm tra)

Ví dụ với xác thực chứng chỉ máy khách:

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

Ví dụ với 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>"
      }
    }
  }
}

Cấu hình TLS được áp dụng cho tất cả các máy khách HTTP được sử dụng bởi máy chủ MCP, bao gồm:

  • Máy khách OpenAPI Grafana chính
  • Máy khách datasource Prometheus
  • Máy khách datasource Loki
  • Máy khách quản lý sự cố
  • Máy khách điều tra Sift
  • Máy khách cảnh báo
  • Máy khách Asserts

Ví dụ sử dụng CLI trực tiếp:

Để kiểm tra với chứng chỉ tự ký:

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

Với xác thực chứng chỉ máy khách:

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

Chỉ với chứng chỉ CA tùy chỉnh:

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

Sử dụng theo chương trình:

Nếu bạn đang sử dụng thư viện này theo chương trình, bạn cũng có thể tạo các hàm ngữ cảnh hỗ trợ 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)

Xác thực URL:

Khi gọi NewGrafanaClient trực tiếp (stdio hoặc xây dựng theo chương trình), hãy xác thực trước các URL để tránh panic có thể xảy ra:

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

Cấu hình TLS máy chủ (Chỉ dành cho Streamable HTTP Transport)

Khi sử dụng streamable HTTP transport (-t streamable-http), bạn có thể cấu hình máy chủ MCP để phục vụ HTTPS thay vì HTTP. Điều này hữu ích khi bạn cần bảo mật kết nối giữa máy khách MCP và chính máy chủ.

Máy chủ hỗ trợ các tùy chọn cấu hình TLS sau cho streamable HTTP transport:

  • --server.tls-cert-file: Đường dẫn đến tệp chứng chỉ TLS cho HTTPS máy chủ (bắt buộc cho TLS)
  • --server.tls-key-file: Đường dẫn đến tệp khóa riêng TLS cho HTTPS máy chủ (bắt buộc cho TLS)

Lưu ý: Các cờ này hoàn toàn tách biệt với các cờ TLS máy khách được mô tả ở trên. Các cờ TLS máy khách cấu hình cách máy chủ MCP kết nối với Grafana, trong khi các cờ TLS máy chủ này cấu hình cách máy khách kết nối với máy chủ MCP khi sử dụng streamable HTTP transport.

Ví dụ với máy chủ HTTPS streamable HTTP:

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

Điều này sẽ khởi động máy chủ MCP trên cổng HTTPS 8443. Máy khách sau đó sẽ kết nối với https://localhost:8443/ thay vì http://localhost:8000/.

Ví dụ Docker với TLS máy chủ:

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

Điểm cuối kiểm tra sức khỏe

Khi sử dụng transport SSE (-t sse) hoặc streamable HTTP (-t streamable-http), máy chủ MCP hiển thị điểm cuối kiểm tra sức khỏe tại /healthz. Điểm cuối này có thể được sử dụng bởi bộ cân bằng tải, hệ thống giám sát hoặc nền tảng điều phối để xác minh rằng máy chủ đang chạy và chấp nhận kết nối.

Điểm cuối: GET /healthz

Phản hồi:

  • Mã trạng thái: 200 OK
  • Nội dung: ok

Ví dụ sử dụng:

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

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

Lưu ý: Điểm cuối kiểm tra sức khỏe chỉ khả dụng khi sử dụng transport SSE hoặc streamable HTTP. Không khả dụng khi sử dụng transport stdio (-t stdio), vì stdio không hiển thị máy chủ HTTP.

Khả năng quan sát

Máy chủ MCP hỗ trợ số liệu Prometheus, theo dõi phân tán OpenTelemetry và xuất nhật ký OpenTelemetry, tuân theo quy ước ngữ nghĩa OTel MCP. Theo dõi và xuất nhật ký được cấu hình qua các biến môi trường OTEL_* tiêu chuẩn và hoạt động với mọi transport.

Lưu ý: mcp-grafana hiện chỉ hỗ trợ transport OTLP/gRPC cho cả theo dõi và nhật ký. OTEL_EXPORTER_OTLP_PROTOCOL (và các biến thể _TRACES_PROTOCOL / _LOGS_PROTOCOL) không được tôn trọng — gRPC luôn được sử dụng.

Số liệu

Khi sử dụng transport SSE hoặc streamable HTTP, hãy bật số liệu Prometheus bằng cờ --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

Số liệu khả dụng:

Số liệuLoạiMô tả
mcp_server_operation_duration_secondsHistogramThời lượng của các thao tác MCP (nhãn: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramThời lượng của các phiên máy khách MCP (nhãn: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramThời lượng của các yêu cầu máy chủ HTTP (từ otelhttp)

Lưu ý: Số liệu chỉ khả dụng khi sử dụng transport SSE hoặc streamable HTTP. Không khả dụng với transport stdio.

Khi Loki cost guardrail (--loki-guardrail-mode) được bật, bốn bộ đếm nữa ghi lại các quyết định của nó:

Số liệuLoạiMô tả
mcp_loki_guardrail_admitted_totalCounterCác truy vấn đã vượt qua mọi kiểm tra được bật (nhãn: backend)
mcp_loki_guardrail_would_block_totalCounterCác truy vấn không vượt qua kiểm tra ở chế độ shadow và vẫn chạy (nhãn: backend, reason)
mcp_loki_guardrail_blocked_totalCounterCác truy vấn bị từ chối ở chế độ enforce (nhãn: backend, reason)
mcp_loki_guardrail_fail_open_totalCounterCác truy vấn guardrail không thể đánh giá và đã chấp nhận (nhãn: backend, cause)

reason là một trong selector, range, bytes; cause là một trong unparseable, estimate_failed; backend là một trong loki, victorialogs, unknown. Một truy vấn vấp phải nhiều kiểm tra được đếm một lần, được gắn nhãn với kiểm tra chạy đầu tiên (selector, sau đó range, sau đó bytes), vì vậy bốn bộ đếm phân vùng dân số được bảo vệ. Xem Khả năng quan sát để biết cách đọc chúng trong quá trình triển khai shadow → enforce.

Các nhà nhúng thư viện nên đặt GrafanaConfig.MeterProvider (đối tác số liệu của GrafanaConfig.Logger): guardrail chạy bên trong trình xử lý công cụ, vì vậy nó không có tùy chọn hàm tạo và một quy trình cài đặt MeterProvider toàn cục noop sẽ bỏ mọi bản ghi.

Ghi nhật ký yêu cầu chậm

Cờ --slow-request-threshold phát ra một sự kiện nhật ký có cấu trúc bất cứ khi nào một yêu cầu MCP (gọi công cụ, danh sách, đọc tài nguyên, v.v.) vượt quá thời lượng nhất định. Nó hữu ích để chẩn đoán các truy vấn và lệnh gọi công cụ chậm mà không bị ngập trong nhật ký gỡ lỗi đầy đủ.

# 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

Sự kiện nhật ký mang các thuộc tính có cấu trúc sau:

Thuộc tínhMô tả
mcp.methodPhương thức MCP (ví dụ: tools/call, tools/list, resources/read)
durationThời lượng yêu cầu quan sát được
thresholdNgưỡng đã cấu hình
toolTên công cụ (chỉ hiện diện cho các phương thức tools/call)
errorGiá trị lỗi, khi yêu cầu thất bại (ngữ cảnh nỗ lực tốt nhất; nội dung được kiểm soát bởi việc bọc lỗi ngược dòng)
error.typePhân loại lỗi có độ phân giải giới hạn (_OTHER cho các lỗi không có kiểu)

Ghi nhật ký yêu cầu chậm hoạt động trên mọi transport (bao gồm cả stdio) và không yêu cầu --metrics. Ngưỡng mặc định 0 vô hiệu hóa hoàn toàn. Các công cụ được ủy quyền chảy qua tools/call và được bao phủ tự động.

Theo dõi

Theo dõi phân tán được cấu hình qua các biến môi trường OTEL_* tiêu chuẩn và hoạt động độc lập với cờ --metrics. Khi OTEL_EXPORTER_OTLP_ENDPOINT (hoặc OTEL_EXPORTER_OTLP_TRACES_ENDPOINT dành riêng cho tín hiệu) được đặt, máy chủ xuất các dấu vết qua 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

Các khoảng thời gian gọi công cụ tuân theo đặt tên semconv (tools/call <tool_name>) và bao gồm các thuộc tính như gen_ai.tool.name, mcp.method.name và mcp.session.id. Máy chủ cũng hỗ trợ truyền ngữ cảnh dấu vết W3C từ trường _meta của các yêu cầu gọi công cụ.

Nhật ký

Khi OTEL_EXPORTER_OTLP_ENDPOINT (hoặc OTEL_EXPORTER_OTLP_LOGS_ENDPOINT dành riêng cho tín hiệu) được đặt, máy chủ cũng xuất nhật ký có cấu trúc qua OTLP/gRPC ngoài đầu ra stderr văn bản thuần hiện có. Cầu nối otelslog tự động đính kèm trace_id và span_id từ khoảng thời gian hoạt động, vì vậy các bản ghi nhật ký tương quan với các dấu vết mà máy chủ đã phát ra.

Dấu vết và nhật ký giải quyết các điểm cuối của chúng một cách độc lập, vì vậy hai tín hiệu có thể được bật riêng biệt: chỉ đặt OTEL_EXPORTER_OTLP_TRACES_ENDPOINT bật theo dõi mà không xuất nhật ký, chỉ đặt OTEL_EXPORTER_OTLP_LOGS_ENDPOINT bật xuất nhật ký mà không theo dõi và OTEL_EXPORTER_OTLP_ENDPOINT chung bật cả hai.

Nếu bạn sử dụng OTEL_EXPORTER_OTLP_ENDPOINT chung nhưng muốn tắt xuất nhật ký (ví dụ: backend của bạn không hỗ trợ LogsService), hãy đặt:

OTEL_LOGS_EXPORTER=none

Điều này ngăn máy chủ tạo trình xuất nhật ký OTLP bất kể cấu hình điểm cuối, tránh các lỗi như unknown service opentelemetry.proto.collector.logs.v1.LogsService.

Ghi nhật ký stderr không thay đổi khi ghi nhật ký OTLP được bật; bạn có thể tiếp tục dựa vào nhật ký container hoặc chuyển stderr sang /dev/null nếu bạn thích.

# 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

Transport là OTLP/gRPC (cổng mặc định 4317). Nhật ký có thể được gửi trực tiếp đến bất kỳ backend được quản lý nào chấp nhận OTLP/gRPC — ví dụ: Grafana Cloud — bằng cách trỏ OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (hoặc OTEL_EXPORTER_OTLP_ENDPOINT chung) đến điểm cuối gRPC từ xa và cung cấp xác thực qua OTEL_EXPORTER_OTLP_LOGS_HEADERS (hoặc OTEL_EXPORTER_OTLP_HEADERS), phản ánh ví dụ theo dõi ở trên. Bộ thu OTel cục bộ là tùy chọn — hữu ích cho fan-out, xử lý theo lô hoặc định tuyến đa backend, nhưng không bắt buộc.

Các biến thể dành riêng cho tín hiệu 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 và OTEL_EXPORTER_OTLP_LOGS_COMPRESSION được tôn trọng và ghi đè các đối tác OTEL_EXPORTER_OTLP_* chung của chúng — xem đặc tả trình xuất OTel để biết danh sách đầy đủ và quy tắc ưu tiên.

Nếu bộ thu đã cấu hình không thể truy cập, các bản ghi nhật ký được lưu trong bộ nhớ (hàng đợi mặc định: 2048) và các bản ghi cũ nhất bị loại bỏ khi hàng đợi đầy. Quy trình tiếp tục mà không chặn dịch vụ. Cấu hình bộ thu OTel cục bộ nếu bạn cần lưu trữ không mất dữ liệu trong thời gian mất kết nối.

Nhật ký cũng được xuất dưới transport stdio, giúp dễ dàng tập trung nhật ký từ các phiên bản mcp-grafana cục bộ được gọi bởi máy khách IDE.

Ví dụ Docker với số liệu, theo dõi và nhật ký:

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

Khắc phục sự cố

Tương thích phiên bản Grafana

Nếu bạn gặp lỗi sau khi sử dụng các công cụ liên quan đến datasource:

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

Điều này thường cho thấy bạn đang sử dụng phiên bản Grafana cũ hơn 9.0. Điểm cuối API /datasources/uid/{uid} được giới thiệu trong Grafana 9.0 và các thao tác datasource sẽ thất bại trên các phiên bản cũ hơn.

Giải pháp: Nâng cấp phiên bản Grafana của bạn lên 9.0 trở lên để giải quyết vấn đề này.

Phát triển

Đóng góp được hoan nghênh! Vui lòng đọc CONTRIBUTING.md trước — nó bao gồm những gì thuộc về máy chủ này và cách đề xuất nó. Nếu bạn đang thêm một công cụ mới, vui lòng mở một đề xuất công cụ trước khi viết mã. Mọi công cụ bật mặc định đều được gửi đến mô hình trong mỗi yêu cầu của mọi người dùng, vì vậy chúng tôi muốn thảo luận về ý tưởng hơn là từ chối một pull request đã hoàn thành. Sửa lỗi, tài liệu, bài kiểm tra và tham số mới trên các công cụ hiện có không cần đề xuất — chỉ cần gửi một PR.

Dự án này được viết bằng Go. Cài đặt Go theo hướng dẫn cho nền tảng của bạn.

Để chạy máy chủ cục bộ ở chế độ STDIO (đây là chế độ mặc định cho phát triển cục bộ), sử dụng:

make run

Để chạy máy chủ cục bộ ở chế độ SSE, sử dụng:

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

Bạn cũng có thể chạy máy chủ bằng cách sử dụng giao thức truyền tải SSE bên trong một hình ảnh Docker được xây dựng tùy chỉnh. Giống như hình ảnh Docker đã xuất bản, điểm vào của hình ảnh tùy chỉnh này mặc định ở chế độ SSE. Để xây dựng hình ảnh, sử dụng:

make build-image

Và để chạy hình ảnh ở chế độ SSE (mặc định), sử dụng:

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

Nếu bạn cần chạy nó ở chế độ STDIO thay vào đó, hãy ghi đè cài đặt truyền tải:

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

Kiểm thử

Có ba loại bài kiểm tra:

  1. Bài kiểm tra đơn vị (không yêu cầu phụ thuộc bên ngoài):
make test-unit

Bạn cũng có thể chạy bài kiểm tra đơn vị với:

make test
  1. Bài kiểm tra tích hợp (yêu cầu các container docker đang chạy):
make test-integration
  1. Bài kiểm tra đám mây (yêu cầu phiên bản Grafana đám mây và thông tin xác thực):
make test-cloud

Lưu ý: Các bài kiểm tra đám mây được cấu hình tự động trong CI. Đối với phát triển cục bộ, bạn sẽ cần thiết lập phiên bản Grafana Cloud và thông tin xác thực của riêng mình.

Các bài kiểm tra tích hợp toàn diện hơn sẽ yêu cầu một phiên bản Grafana đang chạy cục bộ trên cổng 3000; bạn có thể khởi động một phiên bản bằng Docker Compose:

docker-compose up -d

Các bài kiểm tra tích hợp có thể được chạy với:

make test-all

Nếu bạn đang thêm nhiều công cụ hơn, vui lòng thêm bài kiểm tra tích hợp cho chúng. Các bài kiểm tra hiện có nên là điểm khởi đầu tốt.

Kiểm tra mã nguồn

Để kiểm tra mã nguồn, chạy:

make lint

Điều này bao gồm một trình kiểm tra tùy chỉnh kiểm tra các dấu phẩy chưa được thoát trong các thẻ struct jsonschema. Các dấu phẩy trong các trường description phải được thoát bằng \\, để tránh cắt ngắn âm thầm. Bạn có thể chạy chỉ riêng trình kiểm tra này với:

make lint-jsonschema

Xem Tài liệu trình kiểm tra JSONSchema để biết thêm chi tiết.

Giấy phép

Dự án này được cấp phép theo Giấy phép Apache, Phiên bản 2.0.