dashmetrics

dashmetrics

dashmetrics gives an MCP client or a terminal read access to a Grafana instance: dashboard search and retrieval, datasource inspection, Prometheus range queries with metric and label discovery, Loki log queries with label discovery, and the provisioned alert rules and contact points. It is a clean-room rebuild of the documented core of Grafana's MCP tool surface, built from Grafana's public HTTP API documentation.

Point it at an instance with GRAFANA_URL (default http://localhost:3000) and authenticate with a service account token in GRAFANA_SERVICE_ACCOUNT_TOKEN, sent as a Bearer token. The legacy GRAFANA_API_KEY variable is accepted as a fallback when the primary variable is unset. When no token is set, every call fails with an error that names GRAFANA_SERVICE_ACCOUNT_TOKEN; when the instance is unreachable, the error names the base URL it tried.

Install

npx @reneturcios/dashmetrics list_datasources

Or run the container image:

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

The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.

CLI

Every MCP tool is also a CLI subcommand. Tool arguments are passed as one JSON object with --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

Results print as JSON. Exit codes: 0 on success, 1 when an API call fails (including a missing token), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/dashmetrics mcp

MCP client configuration:

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

Tools

Tool	Input (required in bold)	What it does
search_dashboards	query, limit, type	Searches dashboards/folders (/api/search).
get_dashboard_by_uid	uid	Returns one dashboard by uid.
list_datasources	—	Lists configured datasources.
get_datasource_by_uid	uid	Returns one datasource by uid.
query_prometheus	datasourceUid, expr, start, end, step	Prometheus range query via the datasource proxy.
list_prometheus_metric_names	datasourceUid, regex	Lists metric names, regex-filtered.
list_prometheus_label_names	datasourceUid, metric	Lists label names.
list_prometheus_label_values	datasourceUid, label, metric	Lists one label's values.
query_loki_logs	datasourceUid, query, start, end, limit	Loki LogQL range query via the proxy.
list_loki_label_names	datasourceUid	Lists Loki label names.
list_loki_label_values	datasourceUid, label	Lists one Loki label's values.
list_alert_rules	limit	Lists provisioned alert rules.
get_alert_rule_by_uid	uid	Returns one provisioned alert rule.
list_contact_points	limit	Lists provisioned contact points.

Prometheus and Loki calls go through Grafana's documented datasource proxy paths (/api/datasources/proxy/uid/{uid}/...). Out of scope: incident creation/update, on-call schedules, Sift/Asserts, and admin/user management — see BUILD-REPORT.md.

Development

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

License

MIT — see LICENSE.