Fetch complete dashboard JSON or compact structural summaries by URL or UID.
Query live panel data behind dashboards (PromQL, LogQL, adhoc filters, template variables).
Run bare PromQL/LogQL queries without a dashboard.
Check currently firing alerts and alert rule definitions.
Search dashboards by title and tag.
Duplicate dashboards with grafana_clone.
Update dashboards with grafana_push — every write requires explicit user approval.
Multiple named Grafana sources with per-source credentials.
Service Account tokens are stored locally and never exposed to the model.

Requirements

Component	Requirement
WorkBuddy	5.0.0 or later
Node.js	20.3 or later (WorkBuddy manages the runtime)
Grafana	Grafana 10/11 (traditional Dashboard HTTP API)

Installation

Install via WorkBuddy connector marketplace or load locally for development.

Token configuration

After connecting, configure:

Grafana URL — your Grafana instance address (e.g. https://grafana.example.com)
Service Account Token — created in Grafana → Administration → Service Accounts

Managing multiple Grafana sources

The connector supports multiple named Grafana sources. The first source is configured with the two required fields above. To add, edit, or remove additional sources, enable the optional local admin interface:

In the connection form, fill the optional local admin interface port field — 1 auto-assigns a free port, or give a specific port such as 18999.
Reconnect the connector in WorkBuddy so the new setting takes effect.
Open http://127.0.0.1:<port> in your browser. The exact URL is logged to stderr on startup.
Use the web interface to add sources, set defaults, rotate tokens, and remove sources.
Token values are encrypted and never displayed back. Configuration changes persist across restarts.
- On macOS, the production entrypoint stores the encryption master key in the login Keychain; a legacy .key file is removed only after a verified migration.
- Failed credential cleanup is persisted and shown with a retry action; retry checks that no source still references the credential.
To disable the admin interface, clear the field and reconnect.

The admin interface binds to 127.0.0.1 only and is never reachable from the network. Leaving the field empty — the default — keeps it off entirely.

Tests and temporary integrations can set WORKBUDDY_GRAFANA_DATA_DIR to an isolated data directory. WORKBUDDY_GRAFANA_KEY_BACKEND=file is intended only for isolated tests or platforms whose system credential store has not been validated; it is not recommended for production use on macOS.

Grafana permissions

Tool	Permission
`grafana_get` / `grafana_search` / `grafana_status`	`dashboards:read`
`grafana_push` / `grafana_clone`	`dashboards:read` + `dashboards:write`
`grafana_panel_query` / `grafana_trend`	`dashboards:read` + `datasources:query`
`grafana_datasources`	`datasources:read`
`grafana_metric`	`datasources:read` + `datasources:query`
`grafana_alerts`	`alert.instances:read` (+ `alert.provisioning:read` for definitions)
`grafana_sources`	none (reads local config)

Tools

11 effective tools + 2 deprecated name aliases:

Tool	Behavior
`grafana_get`	Fetch complete dashboard JSON (records write snapshot) or compact summary (read-only).
`grafana_push`	Update a dashboard with approval, version check, and folder preservation.
`grafana_clone`	Duplicate a dashboard into a new one with a new UID. Requires approval.
`grafana_panel_query`	Execute panel queries via `/api/ds/query`, return bounded statistical summary.
`grafana_datasources`	List datasources with type, name, default, URL.
`grafana_metric`	Run bare PromQL/LogQL against a named datasource.
`grafana_trend`	Answer "going up or down?" with bucketized trends and sparklines.
`grafana_alerts`	List firing alerts and optionally provisioned rule definitions.
`grafana_search`	Search dashboards by title and tag (max 50 rows).
`grafana_status`	Check Grafana connectivity and credential validity.
`grafana_sources`	List configured sources. Never returns token values.

Write safety

Every write (grafana_push, grafana_clone) requires explicit user approval via MCP elicitation.
Approval is bound to the specific source, dashboard identity, and version — changing the source after approval blocks the write.
Version conflicts are detected before POST.
POST is not retried automatically.
Write results are verified (status, uid, version must all be present).
Writes are disabled by default. To enable them, fill the optional enable dashboard writes field on the connection form with true and reconnect — only after verifying that per-operation MCP elicitation works in your WorkBuddy client.
The flag only wires the approval coordinator; it does not bypass trusted snapshots, version, folder, source, or credential-generation checks.