# 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

```bash
npx @reneturcios/dashmetrics list_datasources
```

Or run the container image:

```bash
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`:

```bash
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:

```bash
npx -y @reneturcios/dashmetrics mcp
```

MCP client configuration:

```json
{
  "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

```bash
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`.