ADK 的 Grafana Cloud MCP 工具¶

Supported in ADKPythonTypeScript

Grafana Cloud MCP 服务器将 ADK 智能体直接连接到你的 Grafana Cloud 可观测性技术栈。你的智能体可以查询 Prometheus 指标、在 Loki 中搜索日志、使用 Tempo 追踪请求、浏览仪表板、管理告警和事件等，拥有超过 60 个可用工具。

该服务器完全托管，无需本地安装、Docker 容器或服务账户令牌。身份验证使用 OAuth 2.1，并通过 Grafana RBAC 实现用户范围的权限。

使用场景¶

调查事件：查询指标、日志和追踪以诊断生产问题。在单次对话中将 Prometheus 告警与 Loki 日志模式和 Tempo 追踪关联起来。
管理仪表板：以编程方式搜索、检查和更新 Grafana 仪表板。提取面板查询、生成深度链接以及将面板渲染为图像。
监控基础设施：列出数据源、发现可用指标、探索标签值以及交互式构建 PromQL 或 LogQL 查询。
响应告警：查看触发中的告警规则、检查值班安排、创建或更新事件以及向事件时间线添加活动记录。

前置条件¶

访问一个 Grafana Cloud 实例
管理员必须接受 Grafana Assistant 条款和条件
Assistant Cloud MCP User 角色或 grafana-assistant-app.cloud-mcp:access 权限（具有 Editor 角色或更高权限的用户默认拥有此权限）

在智能体中使用¶

PythonTypeScript

远程 MCP 服务器

from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

GRAFANA_URL = "https://<your-stack>.grafana.net"

root_agent = Agent(
    model="gemini-flash-latest",
    name="observability_agent",
    instruction="使用 Grafana Cloud 可观测性数据帮助用户调查问题",
    tools=[
        McpToolset(
            connection_params=StreamableHTTPConnectionParams(
                url="https://mcp.grafana.com/mcp",
                headers={
                    "X-Grafana-URL": GRAFANA_URL,
                },
            ),
        )
    ],
)

远程 MCP 服务器

import { LlmAgent, MCPToolset } from "@google/adk";

const GRAFANA_URL = "https://<your-stack>.grafana.net";

const rootAgent = new LlmAgent({
    model: "gemini-flash-latest",
    name: "observability_agent",
    instruction: "使用 Grafana Cloud 可观测性数据帮助用户调查问题",
    tools: [
        new MCPToolset({
            type: "StreamableHTTPConnectionParams",
            url: "https://mcp.grafana.com/mcp",
            transportOptions: {
                requestInit: {
                    headers: {
                        "X-Grafana-URL": GRAFANA_URL,
                    },
                },
            },
        }),
    ],
});

export { rootAgent };

将 <your-stack> 替换为你的 Grafana Cloud 技术栈名称。X-Grafana-URL 标头是可选的，但建议使用，因为它可在 OAuth 授权期间跳过 URL 输入步骤，直接重定向到同意页面。

Note

当智能体首次连接时，系统会提示你在浏览器中授权该连接。你的 OAuth 令牌有效期为 1 小时，并在 30 天内自动刷新。

配置¶

Grafana Cloud MCP 服务器支持读写访问范围：

读取访问：查看仪表板、告警、事件和查询数据源。始终可用。
写入访问：创建和修改仪表板、告警和事件。你可以在 OAuth 同意步骤中授予或拒绝写入访问。

如果你的智能体只需要查询数据，请在授权期间拒绝写入访问，以实现最小权限设置。

可用工具¶

工具	描述
`search_dashboards`	按查询字符串搜索仪表板
`search_folders`	按查询字符串搜索文件夹
`generate_deeplink`	为仪表板、面板和 Explore 查询生成深度链接 URL

仪表板¶

工具	描述	访问
`get_dashboard_by_uid`	按 UID 检索完整的仪表板 JSON	读取
`get_dashboard_summary`	获取仪表板的紧凑摘要	读取
`get_dashboard_property`	使用 JSONPath 提取仪表板的特定部分	读取
`get_dashboard_panel_queries`	检索带有模板变量替换的面板查询	读取
`update_dashboard`	创建或更新仪表板	写入
`create_folder`	创建 Grafana 文件夹	写入

数据源¶

工具	描述
`list_datasources`	列出所有已配置的数据源，支持可选的类型过滤
`get_datasource`	按 UID 或名称获取数据源的详细信息

Prometheus¶

工具	描述
`list_prometheus_metric_names`	发现可用指标，支持正则表达式过滤和分页
`list_prometheus_metric_metadata`	列出当前已抓取指标的元数据
`list_prometheus_label_names`	列出标签名称，支持可选的时间序列选择器和时间范围
`list_prometheus_label_values`	获取特定标签的值
`query_prometheus`	执行 PromQL 即时或范围查询
`query_prometheus_histogram`	查询直方图百分位数

Loki¶

工具	描述
`list_loki_label_names`	列出日志中可用的标签名称
`list_loki_label_values`	获取特定标签的唯一值
`query_loki_logs`	执行 LogQL 查询以获取日志条目或指标值
`query_loki_stats`	获取日志流的统计信息
`query_loki_patterns`	检测和分析常见日志模式

Tempo¶

工具	描述
`tempo_traceql-search`	使用 TraceQL 搜索追踪
`tempo_get-trace`	按 ID 检索追踪
`tempo_get-attribute-names`	发现可用的追踪属性
`tempo_get-attribute-values`	获取追踪属性的值
`tempo_traceql-metrics-instant`	运行即时 TraceQL 指标查询
`tempo_traceql-metrics-range`	运行范围 TraceQL 指标查询

Pyroscope¶

工具	描述
`list_pyroscope_label_names`	列出性能分析中可用的标签名称
`list_pyroscope_label_values`	列出特定标签的值
`list_pyroscope_profile_types`	列出可用的性能分析类型
`query_pyroscope`	从 Pyroscope 查询性能分析或指标

告警¶

工具	描述	访问
`alerting_manage_rules`	列出、过滤、创建和更新告警规则	读取 / 写入
`alerting_manage_routing`	查看通知策略、联系人和时间间隔	读取

事件¶

工具	描述	访问
`list_incidents`	列出事件，支持可选的状态过滤	读取
`get_incident`	按 ID 获取完整的事件详情	读取
`create_incident`	创建新事件	写入
`add_activity_to_incident`	向事件时间线添加记录	写入

OnCall¶

工具	描述
`list_oncall_schedules`	列出值班安排，支持可选的团队过滤
`get_oncall_shift`	获取详细的轮班信息
`get_current_oncall_users`	获取当前某安排的值班用户
`list_oncall_teams`	列出 OnCall 团队
`list_oncall_users`	列出 OnCall 用户，支持可选过滤
`list_alert_groups`	按状态、团队、时间范围和标签过滤告警组

其他工具¶

工具	描述	访问
`get_panel_image`	将仪表板面板渲染为 PNG 图像	读取
`describe_infrastructure`	检索服务组的摘要，包括拓扑和依赖关系	读取
`get_annotations`	按仪表板、时间范围或标签过滤获取注释	读取
`create_annotation`	在仪表板或面板上创建新注释	写入
`query_clickhouse`	对 ClickHouse 数据源执行 SQL 查询	读取
`query_cloudwatch`	查询 AWS CloudWatch 指标	读取
`query_elasticsearch`	对 Elasticsearch 数据源执行搜索	读取

自托管 Grafana¶

对于自托管的 Grafana 实例，请改用开源 Grafana MCP 服务器。它在本地运行，并使用服务账户令牌连接到任何 Grafana 实例。