dashmetrics

dashmetrics

dashmetrics 让 MCP 客户端或终端能够以只读方式访问 Grafana 实例：搜索和获取仪表板、检查数据源、执行 Prometheus 区间查询并发现指标和标签、执行 Loki 日志 查询并发现标签，以及查看已配置的告警规则和 联系点。它基于 Grafana 的公开 HTTP API 文档，从头重建了 Grafana MCP 工具接口中有文档记录的核心部分。

通过 GRAFANA_URL 指定实例（默认值为 http://localhost:3000），并在 GRAFANA_SERVICE_ACCOUNT_TOKEN 中提供服务账号令牌进行身份验证，该令牌会作为 Bearer 令牌发送。如果未设置主变量，则会将旧版 GRAFANA_API_KEY 变量用作备用值。如果未设置令牌，所有调用都会失败，并显示包含 GRAFANA_SERVICE_ACCOUNT_TOKEN 的错误；如果无法访问实例，错误会显示尝试连接的基础 URL。

安装

npx @reneturcios/dashmetrics list_datasources

或者运行容器镜像：

docker run -i -e GRAFANA_URL -e GRAFANA_SERVICE_ACCOUNT_TOKEN ghcr.io/cloudcorprecords/dashmetrics

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

每个 MCP 工具也都对应一个 CLI 子命令。工具参数通过 --json 传入，内容为一个 JSON 对象：

export GRAFANA_URL=http://localhost:3000
export GRAFANA_SERVICE_ACCOUNT_TOKEN=<redacted>

dashmetrics search_dashboards --json '{"query": "api", "limit": 5}'
dashmetrics get_dashboard_by_uid --json '{"uid": "dash-1"}'
dashmetrics list_datasources
dashmetrics query_prometheus --json '{"datasourceUid": "prom1", "expr": "up", "start": "now-1h", "end": "now", "step": "15s"}'
dashmetrics query_loki_logs --json '{"datasourceUid": "loki1", "query": "{job=\"api\"}"}'
dashmetrics list_alert_rules

dashmetrics --version

结果以 JSON 格式输出。退出码：成功时为 0，API 调用失败（包括缺少令牌）时为 1，用法错误时为 2。

MCP 服务

一个二进制文件提供这两种用法。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/dashmetrics mcp

MCP 客户端配置：

{
  "mcpServers": {
    "dashmetrics": {
      "command": "npx",
      "args": ["-y", "@reneturcios/dashmetrics", "mcp"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "your Grafana service account token"
      }
    }
  }
}

工具

工具	输入（粗体为必填项）	功能
search_dashboards	query、limit、type	搜索仪表板/文件夹（/api/search）。
get_dashboard_by_uid	uid	返回一个仪表板。
list_datasources	—	列出已配置的数据源。
get_datasource_by_uid	uid	返回一个数据源。
query_prometheus	datasourceUid、expr、start、end、step	通过数据源代理执行 Prometheus 区间查询。
list_prometheus_metric_names	datasourceUid、regex	列出符合正则表达式筛选条件的指标名称。
list_prometheus_label_names	datasourceUid、metric	列出标签名称。
list_prometheus_label_values	datasourceUid、label、metric	列出一个标签的值。
query_loki_logs	datasourceUid、query、start、end、limit	通过代理执行 Loki LogQL 区间查询。
list_loki_label_names	datasourceUid	列出 Loki 标签名称。
list_loki_label_values	datasourceUid、label	列出一个 Loki 标签的值。
list_alert_rules	limit	列出已配置的告警规则。
get_alert_rule_by_uid	uid	返回一条已配置的告警规则。
list_contact_points	limit	列出已配置的联系点。

Prometheus 和 Loki 调用会通过 Grafana 有文档记录的数据源代理路径 （/api/datasources/proxy/uid/{uid}/...）发出。不在范围内的功能： 创建/更新事件、值班安排、Sift/Asserts，以及 管理员/用户管理——请参阅 BUILD-REPORT.md。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

许可证

MIT — 参见 LICENSE。