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.3k

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

  • Tìm kiếm và kiểm tra dashboard — Tìm dashboard theo tiêu đề bằng search_dashboards, lấy bản tóm tắt gọn nhẹ qua get_dashboard_summary, hoặc trích xuất các trường cụ thể bằng get_dashboard_property với JSONPath.
  • Truy vấn các nguồn dữ liệu quan sát — Chạy truy vấn PromQL với query_prometheus, tìm kiếm log với query_loki_logs, và truy vấn các nguồn dữ liệu CloudWatch, Elasticsearch, ClickHouse, Athena, hoặc Snowflake.
  • Quản lý cảnh báo và sự cố — Liệt kê, tạo, cập nhật và xóa các quy tắc cảnh báo; tìm kiếm và quản lý sự cố trong Grafana Incident; xem lịch trực OnCall và các nhóm cảnh báo.
  • Kết xuất bảng điều khiển dashboard thành hình ảnh — Tạo ảnh PNG của các bảng điều khiển hoặc dashboard với khung thời gian tùy chỉnh, chủ đề và tỷ lệ thông qua công cụ kết xuất.
  • Tạo các liên kết sâu chính xác — Tạo URL trực tiếp đến dashboard, bảng điều khiển cụ thể hoặc chế độ xem Explore với các nguồn dữ liệu và khung thời gian được cấu hình sẵn.
  • Quản trị tài nguyên Grafana — Liệt kê nhóm, người dùng và vai trò; kiểm tra phân công vai trò và quyền tài nguyên bằng các công cụ quản trị.

Tài liệu

Máy chủ Grafana MCP

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, thay thế 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

  • Cần phiên bản Grafana 9.0 trở lên để 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 điểm cuối API.

Tính năng

Các tính năng sau hiện đang 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 hay cam kết về các tính năng trong tương lai.

Trang tổng quan

  • Tìm kiếm trang tổng quan: Tìm trang tổng quan theo tiêu đề hoặc siêu dữ liệu khác
  • Lấy trang tổng quan theo UID: Truy xuất chi tiết đầy đủ của trang tổng quan bằng mã định danh duy nhất của nó. Cảnh báo: Các trang tổng quan lớn có thể tiêu tốn đáng kể không gian cửa sổ ngữ cảnh.
  • Lấy tóm tắt trang tổng quan: Nhận tổng quan ngắn gọn về một trang tổng quan bao gồm tiêu đề, số lượng bảng điều khiển, loại bảng điều khiển, 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 trang tổng quan: Trích xuất các phần cụ thể của trang tổng quan 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 tiêu thụ cửa sổ ngữ cảnh
  • Cập nhật hoặc tạo trang tổng quan: Sửa đổi các trang tổng quan hiện có hoặc tạo mới. Cảnh báo: Yêu cầu JSON đầy đủ của trang tổng quan, có thể tiêu tốn lượng lớn không gian cửa sổ ngữ cảnh.
  • Vá trang tổng quan: Áp dụng các thay đổi cụ thể cho trang tổng quan mà không yêu cầu 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 điều khiển 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 điều khiển trong một trang tổng quan

Chạy truy vấn bảng điều khiển

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

  • Chạy truy vấn bảng điều khiển: Thực thi truy vấn của bảng điều khiển trang tổng quan 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ụ trang tổng quan 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 để có tổng quan về trang tổng quan 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 trang tổng quan
  • Tránh get_dashboard_by_uid trừ khi bạn thực sự cần JSON đầy đủ của trang tổng quan

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, 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 metric tức thời và theo phạm vi) đối với 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 metric, tên metric, tên nhãn và giá trị nhãn từ các nguồn dữ liệu Prometheus.
  • Truy vấn phân vị histogram: Tính toán các giá trị phân vị histogram (p50, p90, p95, p99) bằng cách sử dụng histogram_quantile.

Truy vấn Loki

  • Truy vấn nhật ký và metric Loki: Chạy cả truy vấn nhật ký và truy vấn metric bằng LogQL đối với 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à 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, thêm influxdb vào cờ --enabled-tools của bạn.

  • Truy vấn InfluxDB: Thực thi các truy vấn đối với 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 thô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, 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ố lượng hàng và kích thước.
  • Mô tả lược đồ bảng: Lấy tên cột, kiểu dữ liệu 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ế macro và biến của Grafana.

Truy vấn CloudWatch

Lưu ý: Các công cụ CloudWatch bị tắt theo mặc định. Để bật chúng, 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 khả dụng.
  • Liệt kê metric CloudWatch: Liệt kê các metric 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 truy vấn metric.
  • Truy vấn CloudWatch: Thực thi các truy vấn metric 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, 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 đối với nguồn dữ liệu Graphite.
  • Liệt kê metric Graphite: Duyệt và khám phá các đường dẫn metric Graphite.
  • Liệt kê thẻ Graphite: Liệt kê các thẻ Graphite khả dụng và giá trị thẻ.
  • Truy vấn mật độ Graphite: Truy vấn mật độ metric 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, 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 khả dụng (ví dụ: AwsDataCatalog, trình 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 đối với Amazon Athena thông qua Grafana với hỗ trợ thay thế macro, thực thi giới hạn và 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, 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 — máy chủ MCP không bao giờ thấy thông tin xác thực. Đâ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ố lượng hàng và kích thước) thông 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, kiểu dữ liệu, khả năng null, giá trị mặc định và chú thích 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ế macro và biến. 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, 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 đối với 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ý, metric 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.

Truy vấn Quickwit

Lưu ý: Các công cụ Quickwit bị tắt theo mặc định. Để bật chúng, 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 đối với nguồn dữ liệu Quickwit bằng cú pháp truy vấn Lucene hoặc Query DSL tương thích một phần với 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.

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 và thêm hoạt động vào sự cố.

Đ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ể bằng 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 gia tăng 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 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ộ nhận 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ực: Xem và quản lý lịch trực 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 đang trực hiện tại: Xem những người dùng nào hiện đang trực cho một lịch.
  • Liệt kê nhóm và người dùng: Xem tất cả cá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ể bằng ID của nó.

Quản trị

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

  • Liệt kê nhóm: Xem tất cả cá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ả cá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ê 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 gán cho một vai trò.
  • Liệt kê vai trò cho người dùng: Liệt kê tất cả các vai trò được gán 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ả các vai trò được gán 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ả các quyền được xác định cho một tài nguyên cụ thể (trang tổng quan, nguồn dữ liệu, thư mục, v.v.).
  • Mô tả tài nguyên Grafana: Liệt kê các quyền khả dụng và khả năng phân công cho một loại tài nguyên.

Đ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 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 sử dụng định dạng Graphite (what, when, tags, data).
  • Cập nhật Chú thích: Thay thế tất cả các trường của chú thích hiện có (cập nhật toàn bộ).
  • Vá Chú thích: Chỉ cập nhật các trường cụ thể của 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 bằng 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 bằng 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 hoặc toàn bộ bảng điều khiển Grafana dưới dạng ả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 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ừ nhánh kho lưu trữ cung cấp (ví dụ: bản xem trước PR đồng bộ git) thông qua tham số tùy chọn provisioningPreview.

Cung cấp

  • Liệt kê kho lưu trữ cung cấp: Liệt kê các kho lưu trữ cung cấp được cấu hình cho phiên bản Grafana này (ví dụ: nguồn đồng bộ git), 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 hoạt động.
  • Xác thực tệp cung cấp: Áp dụng thử một tệp từ kho lưu trữ cung cấp tại một nhánh hoặc commit 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 đích và bất kỳ lỗi xác thực có cấu trúc nào — cùng bề mặt tiếp nhận mà trình bình luận PR của Grafana sử dụng.

Danh sách 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 một số 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. Để vô hiệu hóa 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ụ: để vô hiệu hóa các công cụ OnCall, hãy sử dụng --disable-oncall, hoặc để vô hiệu hóa 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 những công cụ bạn dự định sử dụng. Các quyền được liệt kê là các hành động tối thiểu cần thiết - 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 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 đọ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 được á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 đặc quyền 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: Yêu cầu cho các hoạt động chỉ đọc (liệt kê sự cố, lấy điều tra)
  • Vai trò Người chỉnh sửa: Yêu cầu cho các hoạt động ghi (tạo sự cố, sửa đổi đ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 vào tất cả các nguồn dữ liệu
    • dashboards:* - Truy cập vào tất cả các bảng điều khiển
    • folders:* - Truy cập vào tất cả các thư mục
    • teams:* - Truy cập vào tất cả các nhóm

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

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

Ví dụ:

  • Truy cập đầy đủ máy chủ MCP: Cấp quyền rộng cho tất cả cá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ể 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 yêu cầuPhạm vi yêu cầu
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ê vai trò cho người dùngroles:readglobal.users:id:123
list_team_rolesQuản trịLiệt kê vai trò cho nhómroles:readteams:id:7
get_resource_permissionsQuản trịLiệt kê 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:*
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 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 bảng điều khiển mớidashboards:create, dashboards:writedashboards:*, folders:* hoặc folders:uid:xyz789
get_dashboard_panel_queriesBảng điều khiểnLấy tiêu đề bảng, truy vấn, UID nguồn dữ liệu và loại từ bảng điều khiểndashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*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 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 tóm tắt gọn của bảng điều khiển không có JSON đầy đủdashboards:readdashboards:uid:abc123
list_datasourcesNguồn dữ liệuLiệt kê nguồn dữ liệudatasources:readdatasources:*
get_datasourceNguồn dữ liệuLấy nguồn dữ liệu theo UID hoặc têndatasources:readdatasources:uid:prometheus-uid
get_query_examplesVí dụ*Lấy truy vấn ví dụ cho một loại nguồn dữ liệudatasources:readdatasources:*
query_prometheusPrometheusThực thi truy vấn đối với nguồn dữ liệu Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusLiệt kê siêu dữ liệu metricdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusLiệt kê tên metric khả dụngdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusLiệt kê tên nhãn khớp với bộ chọndatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusLiệt kê giá trị cho một nhãn cụ thểdatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusTính toán giá trị phân vị histogramdatasources:querydatasources:uid:prometheus-uid
list_incidentsSự cốLiệt kê sự cố trong Grafana IncidentVai trò Người xemN/A
create_incidentSự cốTạo sự cố trong Grafana IncidentVai trò Người chỉnh sửaN/A
add_activity_to_incidentSự cốThêm mục hoạt động vào sự cố trong Grafana IncidentVai trò Người chỉnh sửaN/A
get_incidentSự cốLấy một sự cố theo IDVai 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 metric)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiLiệt kê tất cả tên nhãn khả dụng trong nhật kýdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiLiệt kê 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ề luồng nhật kýdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiTruy vấn mẫu nhật ký được phát hiện để xác định cấu trúc chungdatasources: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 đoạn mã loki.process Alloy 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ê bảng trong cơ sở dữ liệu ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Lấy lược đồ bảng với các loại 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ê không gian tên AWS CloudWatch khả dụngdatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Liệt kê các dimension cho một metricdatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Thực thi truy vấn metric CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Liệt kê các data catalog Athena khả dụngdatasources:querydatasources:uid:*
list_athena_databasesAthena*Liệt kê các database trong một catalog Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Liệt kê các bảng trong một database Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Lấy tên 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 sử dụng cú pháp Lucene hoặc Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Truy vấn Quickwit sử dụng cú pháp Lucene hoặc Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Liệt kê các bảng trong một database/schema Snowflake qua INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Lấy schema 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 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
list_oncall_schedulesOnCallLiệt kê lịch từ Grafana OnCallgrafana-oncall-app.schedules:readPhạm vi dành riêng cho plugin
get_oncall_shiftOnCallLấy chi tiết cho một ca trực OnCall cụ thểgrafana-oncall-app.schedules:readPhạm vi dành riêng cho plugin
get_current_oncall_usersOnCallLấy người dùng hiện đang trực cho một lịch cụ thểgrafana-oncall-app.schedules:readPhạm vi dành riêng cho plugin
list_oncall_teamsOnCallLiệt kê các nhóm từ Grafana OnCallgrafana-oncall-app.user-settings:readPhạm vi dành riêng cho plugin
list_oncall_usersOnCallLiệt kê người dùng từ Grafana OnCallgrafana-oncall-app.user-settings:readPhạm vi dành riêng cho plugin
list_alert_groupsOnCallLiệt kê nhóm cảnh báo từ Grafana OnCall với tùy chọn lọcgrafana-oncall-app.alert-groups:readPhạm vi dành riêng cho 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 dành riêng cho plugin
get_sift_investigationSiftTruy xuất một cuộc điều tra Sift hiện có theo UUID của nóVai trò Người xemN/A
get_sift_analysisSiftTruy xuất một phân tích cụ thể từ một cuộc điều tra SiftVai trò Người xemN/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ò Người xemN/A
find_error_pattern_logsSiftTìm các mẫu lỗi gia tăng trong nhật ký Loki.Vai trò Người chỉnh sửaN/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ò Người chỉnh sửaN/A
list_pyroscope_label_namesPyroscopeLiệt kê tên nhãn khớp với một bộ chọndatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeLiệt kê giá trị nhãn khớp với một bộ chọn cho một tên nhãndatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeLiệt kê các loại profile khả dụngdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeTruy vấn profile, metric hoặc cả hai từ Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsLấy tóm tắt assertion cho một thực thể nhất địnhQuyền dành riêng cho pluginPhạm vi dành riêng cho plugin
generate_deeplinkNavigationTạo URL deeplink chính xác cho các tài nguyên GrafanaKhông (tạo URL chỉ đọc)N/A
get_annotationsAnnotationsLấy chú thích với bộ lọcannotations:readannotations:* hoặc annotations:id:123
create_annotationAnnotationsTạo chú thích mới (định dạng chuẩn hoặc Graphite)annotations:writeannotations:*
update_annotationAnnotationsCập nhật các trường cụ thể của chú thích (cập nhật một phần)annotations:writeannotations:*
get_annotation_tagsAnnotationsLiệt kê thẻ chú thích với lọc tùy chọnannotations:readannotations:*
list_snapshotsSnapshotLiệt kê snapshot dashboard với truy vấn và bộ lọc giới hạn tùy chọndashboards:readdashboards:* hoặc dashboards:uid:abc123
get_snapshotSnapshotLấy metadata snapshot và payload dashboard theo khóa snapshotdashboards:readdashboards:* hoặc dashboards:uid:abc123
create_snapshotSnapshotTạo snapshot dashboard từ payload dashboard đầy đủdashboards:writedashboards:* hoặc dashboards:uid:abc123
delete_snapshotSnapshotXóa snapshot dashboard theo khóa snapshotdashboards:writedashboards:* hoặc dashboards:uid:abc123
get_panel_imageRenderingKết xuất dashboard hoặc panel đã lưu — hoặc bản xem trước provisioning từ nhánh repository — dưới dạng ảnh PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesProvisioningLiệt kê repository provisioning (ví dụ: nguồn git-sync) với URL nguồn, nhánh, trạng thái đồng bộ và tình trạngprovisioning.repositories:readN/A
validate_provisioning_fileCấp phépChạy thử áp dụng một tệp từ kho cấp phép và báo cáo lỗi xác thực đầu vàoprovisioning.repositories:readKhông áp dụng
* Bị tắt theo mặc định. Thêm danh mục vào --enabled-tools để bật.

Tham chiếu Cờ CLI

Tệp nhị phân mcp-grafana hỗ trợ nhiều cờ dòng lệnh để cấu hình:

Tùy chọn Vận chuyển:

  • -t, --transport: Loại vận chuyển (stdio, sse, hoặc streamable-http) - mặc định: stdio
  • --address: Máy chủ và cổng 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 điểm cuối cho máy chủ streamable-http - mặc định: /

Bảo mật Vận chuyển HTTP (chỉ SSE / streamable-http):

Xác thực Host/Origin được thực thi trên mọi tuyến đường trên bộ lắng nghe — /sse, /mcp, /healthz, và /metrics — để trình duyệt tái gán DNS không thể truy cập bất kỳ tuyến nào trong số đó. Vận chuyển Stdio không bị ảnh hưởng.

  • --allowed-hosts: Danh sách cho phép phân tách bằng dấu phẩy của các giá trị tiêu đề 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 (chưa đặt, ,, ,, v.v.) cũng quay về mặc định để lỗi đánh máy không thể âm thầm vô hiệu hóa kiểm tra. Các yêu cầu có tiêu đề Host nằm ngoài danh sách cho phép bị từ chối với 403. Truyền * để vô hiệu hóa kiểm tra — chỉ an toàn khi chạy sau proxy ngược đáng tin cậy ghi lại Host, hoặc trong mạng cô lập. Các đầu dò httpGet của K8s và các lần thu thập /metrics bên ngoài sẽ cần tên máy chủ rõ ràng trong danh sách này, *, hoặc đầu dò tcpSocket / cổng metrics riêng (--metrics-address).
  • --allowed-origins: Danh sách cho phép phân tách bằng dấu phẩy của các giá trị tiêu đề Origin. Mặc định trống — bất kỳ yêu cầu nào mang tiêu đề Origin đều bị từ chối (trình duyệt luôn gửi một tiêu đề 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 thành danh sách rõ ràng để cho phép các máy khách dựa trên trình duyệt, hoặc * để vô hiệu hóa kiểm tra.

Gỡ lỗi và Ghi nhật ký:

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

Khả năng quan sát:

  • --metrics: Bật điểm cuối 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
  • --slow-request-threshold: Ghi nhật ký 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 khoảng thời gian này. Chấp nhận chuỗi thời lượng Go (ví dụ: 500ms, 5s). Mặc định 0 vô hiệu hóa ghi nhật ký yêu cầu chậm. Xem phần Ghi nhật ký yêu cầu chậm.
  • --slow-request-log-level: Mức ghi nhật ký 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ờ nhàn rỗi phiên 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 để vô hiệu hóa thu hồi phiên. Chỉ liên quan đến vận chuyển 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 danh mục được bật - mặc định: tất cả danh mục ngoại trừ admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery, và snowflake. Để bật các danh mục bị tắt, thêm chúng vào danh sách (ví dụ: "search,datasource,...,snowflake")
  • --max-loki-log-limit: Số dòng nhật ký tối đa trả về mỗi lần gọi query_loki_logs - mặc định: 100. Lưu ý: Đặt giá trị này ít nhất nhỏ hơn 1 so vớ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 nếu có thêm dữ liệu).
  • --disable-search: Tắt công cụ tìm kiếm
  • --disable-datasource: Tắt công cụ nguồn dữ liệu
  • --disable-incident: Tắt công cụ sự cố
  • --disable-prometheus: Tắt công cụ prometheus
  • --disable-write: Tắt công cụ ghi (thao tác tạo/cập nhật)
  • --disable-loki: Tắt công cụ loki
  • --disable-elasticsearch: Tắt công cụ elasticsearch và opensearch
  • --disable-quickwit: Tắt công cụ quickwit
  • --disable-influxdb: Tắt công cụ InfluxDB
  • --disable-alerting: Tắt công cụ cảnh báo
  • --disable-dashboard: Tắt công cụ bảng điều khiển
  • --disable-oncall: Tắt công cụ oncall
  • --disable-asserts: Tắt công cụ asserts
  • --disable-sift: Tắt công cụ sift
  • --disable-admin: Tắt công cụ quản trị
  • --disable-pyroscope: Tắt công cụ pyroscope
  • --disable-navigation: Tắt công cụ điều hướng
  • --disable-rendering: Tắt công cụ kết xuất (xuất hình ảnh bảng điều khiển/bảng)
  • --disable-snapshot: Tắt công cụ snapshot
  • --disable-cloudwatch: Tắt công cụ CloudWatch
  • --disable-examples: Tắt công cụ ví dụ truy vấn
  • --disable-clickhouse: Tắt công cụ ClickHouse
  • --disable-snowflake: Tắt công cụ Snowflake
  • --disable-runpanelquery: Tắt công cụ chạy truy vấn bảng điều khiển
  • --disable-graphite: Tắt công cụ Graphite
  • --disable-athena: Tắt công cụ Athena
  • --disable-provisioning: Tắt công cụ cấp phép

Chế độ Chỉ đọc

Cờ --disable-write cung cấp cách chạy máy chủ MCP ở chế độ chỉ đọc, ngăn chặn mọi thao tác ghi vào phiên bản 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 tài khoản dịch vụ 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 ngẫu nhiên

Khi --disable-write được bật, các thao tác ghi sau bị tắt:

Công cụ Bảng điều khiển:

  • update_dashboard

Công cụ Thư mục:

  • create_folder

Công cụ Sự cố:

  • create_incident
  • add_activity_to_incident

Công cụ Cảnh báo:

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

Công cụ Chú thích:

  • create_annotation
  • update_annotation

Công cụ Sift:

  • find_error_pattern_logs (tạo điều tra)
  • find_slow_requests (tạo điều tra)

Công cụ Snapshot:

  • create_snapshot
  • delete_snapshot

Tất cả các thao tác đọc vẫn khả dụng, cho phép bạn truy vấn bảng điều khiển, chạy truy vấn PromQL/LogQL, liệt kê tài nguyên và truy xuất dữ liệu.

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 cho xác thực máy khách
  • --tls-key-file: Đường dẫn đến tệp khóa riêng TLS cho xác thực máy khách
  • --tls-ca-file: Đường dẫn đến tệp chứng chỉ CA TLS cho 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, 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 token 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 token tài khoản dịch vụ và sao chép nó vào clipboard để 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 token 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ò Editor tích hợp sẵn cho tài khoản dịch vụ. Điều này cấp quyền đọc/ghi rộng bao phủ hầu hết các hoạt động của máy chủ MCP — sử dụng nó khi sự tiện lợi vượt trội 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 đã bị phản đối và sẽ bị xóa trong phiên bản tương lai. Vui lòng 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 phản đối.

Đọc token tài khoản dịch vụ từ tệp

Thay vì truyền token trực tiếp qua GRAFANA_SERVICE_ACCOUNT_TOKEN, bạn có thể trỏ GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE đến đường dẫn tệp chứa token. Tệp được đọc mới trên mỗi yêu cầu, vì vậy các token được xoay vòng sẽ đượ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 Secret được gắn kết dưới dạng volume được cập nhật tại chỗ khi Secret cơ bản thay đổi (thường trong vò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ị token — một token được xoay vòng sẽ tạo ra một máy khách mới một cách minh bạch 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ỏ khỏi nội dung tệp. Nếu cả GRAFANA_SERVICE_ACCOUNT_TOKEN và GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE đều được đặt, token trực tiếp được ưu tiên.

Hỗ trợ Đa Tổ chức

Bạn có thể chỉ định tổ chức nào để 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ũng có thể đặ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.

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 tiêu đề HTTP tùy ý vào tất cả các yêu cầu API Grafana bằng cách sử dụ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 đề với 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\"}"
      }
    }
  }
}

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

Khi máy chủ MCP chạy sau 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 đ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 định nghĩa trong GRAFANA_EXTRA_HEADERS. Nếu tên tiêu đề xuất hiện trong cả hai, giá trị từ yêu cầu đến được ưu tiên cho yêu cầu đó.

  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 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 đè rõ ràng mặc định 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
      1. Chế độ SSE: Trong chế độ này, máy chủ chạy như một máy chủ HTTP mà các 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> grafana/mcp-grafana

  2. Chế độ HTTP có thể truyền phát: Trong chế độ này, máy chủ hoạt động như một tiến 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 đè rõ ràng giá trị mặc định 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> grafana/mcp-grafana -t streamable-http

    Đối với chế độ HTTP có thể truyền phát qua 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> \
  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 nên 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

  3. 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 rất cần thiết ở đây vì nó ghi đè chế độ SSE mặc định trong ả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 (là mặc định khi sử dụng ảnh Docker mà không ghi đè phương thức truyền tải), 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ế độ HTTP có thể truyền phát qua HTTPS 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 phương thức truyền tải 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, có thể 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 tệp nhị phân:

{
  "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 ảnh Docker.

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ỉ sử dụng để kiểm thử)

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 máy chủ MCP sử dụng, bao gồm:

  • Máy khách OpenAPI Grafana chính
  • Máy khách nguồn dữ liệu Prometheus
  • Máy khách nguồn dữ liệu 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 thử 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 kết nối máy chủ HTTP của riêng bạn:

Khi người dùng thư viện kết nối các hàm ngữ cảnh của mcp-grafana vào http.Server của riêng họ, hãy cài đặt ValidateGrafanaURLMiddleware để từ chối các tiêu đề X-Grafana-URL không đúng định dạng với mã lỗi 400 Bad Request (khớp với hành vi của tệp nhị phân):

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

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 không đáng tin cậy để tránh lỗi 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ả hai mẫu đều chia sẻ ValidateGrafanaURL làm trình xác thực duy nhất.

Cấu hình TLS Máy chủ (Chỉ dành cho Phương thức Truyền tải HTTP Có thể Truyền phát)

Khi sử dụng phương thức truyền tải HTTP có thể truyền phát (-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 phương thức truyền tải HTTP có thể truyền phát:

  • --server.tls-cert-file: Đường dẫn đến tệp chứng chỉ TLS cho HTTPS máy chủ (bắt buộc đối với 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 đối với 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 ghi lại ở 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 phương thức truyền tải HTTP có thể truyền phát.

Ví dụ với máy chủ HTTP có thể truyền phát qua HTTPS:

./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. Sau đó, máy khách 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 Tình trạng

Khi sử dụng phương thức truyền tải SSE (-t sse) hoặc HTTP có thể truyền phát (-t streamable-http), máy chủ MCP hiển thị một điểm cuối kiểm tra tình trạng 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

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

Lưu ý: Điểm cuối kiểm tra tình trạng chỉ khả dụng khi sử dụng phương thức truyền tải SSE hoặc HTTP có thể truyền phát. Nó không khả dụng khi sử dụng phương thức truyền tải 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, truy vết phân tán OpenTelemetry và xuất nhật ký OpenTelemetry, tuân theo quy ước ngữ nghĩa OTel MCP. Truy vết và xuất nhật ký được cấu hình thông qua các biến môi trường OTEL_* tiêu chuẩn và hoạt động với bất kỳ phương thức truyền tải nào.

Lưu ý: mcp-grafana hiện chỉ hỗ trợ phương thức truyền tải OTLP/gRPC cho cả truy vết và nhật ký. OTEL_EXPORTER_OTLP_PROTOCOL (và các biến thể _TRACES_PROTOCOL / _LOGS_PROTOCOL của nó) không được tôn trọng — gRPC được sử dụng bất kể.

Số liệu

Khi sử dụng phương thức truyền tải SSE hoặc HTTP có thể truyền phát, 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 hoạt động 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 phương thức truyền tải SSE hoặc HTTP có thể truyền phát. Chúng không khả dụng với phương thức truyền tải stdio.

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 đã cho. 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 làm ngập 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 được quan sát
thresholdNgưỡng đã cấu hình
toolTên công cụ (chỉ có mặt đối với 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 gói lỗi ngược dòng)
error.typePhân loại lỗi có số lượng giới hạn (_OTHER cho các lỗi không định kiểu)

Ghi nhật ký yêu cầu chậm hoạt động trên tất cả các phương thức truyền tải (bao gồm stdio) và không yêu cầu --metrics. Ngưỡng mặc định của 0 sẽ 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.

Truy vết

Truy vết phân tán được cấu hình thông 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 được đặt, máy chủ xuất truy 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 nhịp gọi công cụ tuân theo quy ước đặ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 bá ngữ cảnh truy 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 — cùng một kích hoạt cho phép truy vế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 túy hiện có. Cầu nối otelslog tự động đính kèm trace_id và span_id từ nhịp đang hoạt động, do đó các bản ghi nhật ký tương quan với các truy vết mà máy chủ đã phát ra.

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

# 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

Phương thức truyền tải 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ụ truy vết ở trên. Một bộ thu thập OTel cục bộ là tùy chọn — hữu ích cho việc phân luồng, xử lý hàng loạt 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 thông số kỹ thuật trình xuất OTel để biết danh sách đầy đủ và quy tắc ưu tiên.

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

Nhật ký cũng được xuất theo phương thức truyền tải 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, truy vết 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ố

Khả năng 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 nguồn dữ liệu:

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

Điều này thường chỉ ra rằng bạn đang sử dụng phiên bản Grafana sớm hơn 9.0. Điểm cuối API /datasources/uid/{uid} được giới thiệu trong Grafana 9.0 và các hoạt động nguồn dữ liệu 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 đều được hoan nghênh! Vui lòng mở một vấn đề hoặc gửi yêu cầu kéo nếu bạn có bất kỳ đề xuất hoặc cải tiến nào.

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 (là mặc định cho phát triển cục bộ), hãy sử dụng:

make run

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

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

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

make build-image

Và để chạy ảnh ở chế độ SSE (mặc định), hãy 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 thế, hãy ghi đè cài đặt phương thức truyền tải:

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

Kiểm thử

Có ba loại kiểm thử khả dụng:

  1. Kiểm thử Đơ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 kiểm thử đơn vị bằng:

make test
  1. Kiểm thử Tích hợp (yêu cầu container docker đang chạy):
make test-integration
  1. Kiểm thử Đá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 ý: Kiểm thử đám mây được tự động cấu hình 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 kiểm thử 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 kiểm thử tích hợp có thể được chạy bằng:

make test-all

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

Kiểm tra mã nguồn

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

make lint

Lệnh này bao gồm một trình kiểm tra tùy chỉnh để kiểm tra dấu phẩy không đượ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 \\, để ngăn chặn việc cắt ngắn âm thầm. Bạn có thể chỉ chạy trình kiểm tra này bằng:

make lint-jsonschema

Xem Tài liệu JSONSchema Linter để 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.