# How to connect Grafana to Hermes Agent (service account token, 11 tools)

> Connect Grafana to Hermes Agent with ClawLink: paste a service account token once and 11 tools work from chat, covering health checks, Loki and Mimir ring status, OTLP log ingestion, and public dashboard queries.

Web version: https://claw-link.dev/hermes/grafana

Most guides for giving Hermes Agent Grafana access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Grafana setup: pair once in the browser and your always-on Hermes agent can act on Grafana for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Grafana.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Grafana** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect grafana  # connect Grafana (browser OAuth)
npx -y @useclawlink/cli actions grafana  # list available actions
npx -y @useclawlink/cli run grafana <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin    # prints an approval link — open it and approve
hermes clawlink finish   # after approving in the browser
hermes clawlink test
```

Then connect Grafana in the [ClawLink dashboard](https://claw-link.dev/dashboard) — enter your Grafana account details once.

Verify the connection by asking Hermes:

> Call grafana_get_health and tell me whether the server is up and can reach its database. If it reports anything other than ok, quote the exact response.

### Using a different agent?

The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Grafana is connected in the dashboard, that agent calls the same 11 Grafana tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/connect-apps-to-any-ai-agent).

## Grafana MCP for Hermes

Looking for a Grafana MCP server for Hermes Agent? ClawLink connects Grafana to Hermes Agent and exposes 11 Grafana tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Grafana integration](https://claw-link.dev/openclaw/grafana) works the same way.

This integration is narrower than most on ClawLink and it is worth knowing that before you connect it. Grafana has no OAuth flow for API access, so the connection takes a service account token that you create in Grafana and paste once, and ClawLink stores it server-side rather than in an environment file next to your agent. The 11 tools are operational rather than analytical: server health, license status, Loki and Mimir hash-ring state, OTLP log ingestion, and a reader for publicly shared dashboards. If what you want is an agent that queries your private dashboards and panels, read the limits section below first, because these tools do not do that.

## What this integration does not do

Stated plainly, because the gap between what people search for and what these tools cover is wide.

- **No private dashboard or panel queries.** There is no tool that runs a query against a dashboard panel you have not published publicly, and none that queries Prometheus, Loki, or any other datasource directly. Grafana's own `grafana/mcp-grafana` server is the reference implementation for that work.
- **No dashboard or alert management.** Nothing here creates, edits, or lists dashboards, and nothing reads or silences alert rules.
- **No user or organization administration.** The service account's role limits what it can reach, and this toolset does not include user management regardless of role.

If those are what you need, connecting this integration will not get you there, and it is better to know that now than after pasting a token.

## What the Hermes Agent Grafana integration can do

11 Grafana tools are ready for Hermes Agent once the account is connected.

### All 11 Grafana tools for Hermes

| Tool | What it does |
|---|---|
| **Create otlp v1 logs** `grafana_create_otlp_v1_logs` | Tool to create OTLP v1 logs in Grafana Loki. Use when you need to send OpenTelemetry Protocol logs to Grafana for ingestion and storage. |
| **Get distributor ha tracker** `grafana_get_distributor_ha_tracker` | Tool to retrieve distributor HA tracker status. Use when you need to check which replica has been elected as leader for each Prometheus HA cluster. |
| **Get health** `grafana_get_health` | Check Grafana server health and database connectivity. Returns 'ok' if Grafana's web server is running and can access the database. |
| **Get index gateway ring** `grafana_get_index_gateway_ring` | Tool to retrieve the index gateway hash ring status from Grafana Loki. Returns information about the state, health, and last heartbeat time of each index gateway in the ring. |
| **Get overrides exporter ring** `grafana_get_overrides_exporter_ring` | Tool to retrieve the overrides-exporter hash ring status as an HTML page. Use when you need to check the state, health, and heartbeat information of overrides-exporter instances. |
| **Get ruler ring** `grafana_get_ruler_ring` | Tool to retrieve the ruler ring status from Grafana Mimir. Use when you need to check the distributed hash ring topology and operational status of ruler instances. |
| **Get status** `grafana_get_status` | Tool to check if a valid Grafana Enterprise license is available. Use when you need to verify license status or availability. |
| **Get store gateway tenants** `grafana_get_store_gateway_tenants` | Retrieves store gateway tenants. Returns a list of tenants that have blocks stored in the store-gateway's configured storage. |
| **Post acs** `grafana_post_acs` | Tool to perform SAML Assertion Consumer Service (ACS) operation. Use when processing SAML authentication responses from an identity provider. |
| **Query public dashboard** `grafana_query_public_dashboard` | Query a panel on a public Grafana dashboard to retrieve time-series data and metrics. Use when you need to fetch visualization data from a publicly shared dashboard without authentication. |
| **Retrieve jwks** `grafana_retrieve_jwks` | Tool to retrieve JSON Web Key Set (JWKS) with all public keys for token verification. Use when you need to get the keys that can verify JWT tokens. |

## Example prompts

**Check whether Grafana is healthy**

> Call grafana_get_health and tell me whether the server is up and can reach its database. If it reports anything other than ok, quote the exact response.

**Read a public dashboard panel**

> Use grafana_query_public_dashboard for the public dashboard I link and pull the panel showing request latency over the last 24 hours. Summarize the trend and tell me the highest value and when it happened.

**Check Loki and Mimir ring state**

> Call grafana_get_index_gateway_ring and grafana_get_ruler_ring and tell me the state, health, and last heartbeat of each instance. Flag anything not in a healthy state. If either returns 404, tell me the component is probably not deployed rather than retrying.

**Write a log line into Loki**

> Use grafana_create_otlp_v1_logs to send a log entry into Loki recording that the release check finished, with severity info and a service label of hermes-agent. Confirm it was accepted.

## What the 11 Grafana tools cover

The full list, grouped, so you can see what is here before connecting.

- **Instance status**: `grafana_get_health` reports whether the web server is running and can reach its database. `grafana_get_status` checks whether a valid Grafana Enterprise licence is available.
- **Public dashboard data**: `grafana_query_public_dashboard` is the only tool that returns time-series data, and it targets dashboards shared through Grafana's public dashboard feature.
- **Loki and Mimir ring state**: `grafana_get_index_gateway_ring`, `grafana_get_ruler_ring`, `grafana_get_distributor_ha_tracker`, `grafana_get_store_gateway_tenants`, and `grafana_get_overrides_exporter_ring` report hash-ring topology, replica leadership, and per-tenant storage. They need those components deployed; the last one also needs its ring explicitly enabled.
- **Log ingestion**: `grafana_create_otlp_v1_logs` sends OpenTelemetry Protocol logs into Loki, which is the one write in the set.
- **Authentication plumbing**: `grafana_retrieve_jwks` returns the public keys for verifying JWTs, and `grafana_post_acs` handles a SAML assertion consumer service response. Both are infrastructure tools rather than anything you would use conversationally.

## ClawLink vs. building it yourself

The alternative to ClawLink is usually manual credential setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Grafana working from chat.

| | Manual | ClawLink |
|---|---|---|
| **Setup flow** | Collect and store the right Grafana credentials yourself, then keep the account mapping and request format correct. | ClawLink keeps the setup in one hosted flow so non-technical users can link Grafana without custom integration screens. |
| **Ongoing maintenance** | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Grafana. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| **Agent usability** | You still need to expose the right Grafana actions to the runtime in a format your agent can reliably use. | 11 tools for Grafana are already exposed through ClawLink, so the agent can read and act from chat immediately. |

## ClawLink vs. Composio

Composio also exposes Grafana to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Grafana in the browser, and the 11 tools above work from chat. There is no SDK and no config file, and the Grafana key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full [Composio alternatives](https://claw-link.dev/hub/composio-alternatives) comparison.

### Hermes paired but still can't use Grafana
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

### Connection succeeds but no tools appear
Reconnect Grafana from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.

### "Tool schema not loaded yet" error when calling Grafana tools
Grafana tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Grafana call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.

### Grafana returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.

### Grafana returns 401 Unauthorized or an invalid API key error while the connection shows as connected
This shape has real demand and almost no reliable answer, so here is the specific version. On a hosted connection there is no Authorization header for you to format and no local file to check, which rules out most of the standard advice about a missing space after Bearer or a malformed env variable. What is left is the token itself. Service account tokens can be given an expiry when they are created, and an expired token produces exactly this error on a connection that still looks healthy. The token can also be revoked, or the service account disabled, from Grafana's administration screens. And a token is bound to the Grafana instance that issued it, so a token from a staging instance fails against production while appearing perfectly valid. The fix in all three cases is to create a fresh service account token in the right instance and reconnect Grafana from the ClawLink dashboard.

Ask the agent to diagnose it:

```text
Call grafana_get_health and report exactly what it returns, including any error body and status code. Do not retry the other Grafana calls.
```

### Grafana returns 403 or the token works for some endpoints and not others
Service accounts carry a role, and that role bounds everything the token can do. A service account created with the Viewer role reads but cannot reach administrative endpoints, which is why several tools in this set can fail while grafana_get_health succeeds. Grafana also scopes service accounts to a single organization, so a token issued in one org returns permission errors against another org's resources rather than an obvious wrong-org error. Check the service account's role and organization in Grafana under Administration, then Service accounts. If the tools you need are administrative, the account needs a role that reaches them.

Ask the agent to diagnose it:

```text
Call grafana_get_health first and tell me if it succeeds. Then call the tool that failed and report the exact status code and body. Tell me which of the two worked.
```

### A Grafana tool returns 404, or a ring-status tool returns nothing useful
Most of the tools in this integration target Grafana's Loki and Mimir components rather than Grafana itself, and those endpoints only exist where those components are running. grafana_get_index_gateway_ring, grafana_get_ruler_ring, grafana_get_distributor_ha_tracker, and grafana_get_store_gateway_tenants all fall into that group, and against a plain Grafana instance with no Loki or Mimir behind it they have nothing to answer. grafana_get_overrides_exporter_ring goes further and is only reachable when the overrides-exporter ring is explicitly enabled in configuration. A 404 here usually means the component is not deployed rather than that the connection is broken. grafana_get_health is the tool to confirm the connection itself is fine.

Ask the agent to diagnose it:

```text
Call grafana_get_health and tell me whether the instance responds. Then list which Grafana tools you have available so I can tell you which one to use instead.
```

### The setup form accepts credentials but calls still fail
Re-enter the credentials carefully and verify the account-level permissions for Grafana. Basic and token-based integrations tend to fail on formatting mistakes or limited account roles.

### Is there a Hermes Agent Grafana integration?
Yes. ClawLink is the fastest way to connect Hermes to Grafana: link your Grafana account once in the browser and Hermes Agent can call the Grafana API through 11 ready-made tools — no custom code or token handling.

### How do I connect Grafana to Hermes with ClawLink?
Install the plugin with `hermes plugins install ClawLink-HQ/hermes-plugin --enable`, then pair once: run `hermes clawlink begin`, approve the link in your browser, and run `hermes clawlink finish`. Connect Grafana in the dashboard and Hermes can use it from the next message — no config files, and the Grafana key you paste is stored server-side instead of in your environment.

### How long does it take to connect Grafana to Hermes Agent?
About two minutes. Sign in, click Connect next to Grafana in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.

### Why use ClawLink instead of wiring Grafana up myself?
The alternative to ClawLink is usually manual credential setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Grafana working from chat.

### Do I need a Grafana API key or service account token?
Yes. Grafana does not offer an OAuth flow for API access, so this connection uses a bearer token, which in current Grafana means a service account token created under Administration, then Service accounts. Older Grafana API keys were deprecated in favour of service accounts, so a token created today is a service account token. What ClawLink changes is where it lives: you paste it once and it is stored server-side, rather than sitting in a config file or an environment variable on the machine running your agent. What it does not change is that a token exists and that you created it.

### Which Hermes is this?
Hermes Agent, the Nous Research agent runtime. Search results for Grafana and Hermes together are crowded with two unrelated products: the NASA Hermes Grafana plugin, which reads spacecraft telemetry from TimescaleDB, and Hermes from Informal Systems, the Cosmos IBC relayer whose metrics people scrape into Grafana. If you arrived here looking for either of those, neither is this. This page is about giving the Hermes Agent runtime a set of Grafana tools it can call from chat.

### Can the agent query my dashboards?
Only publicly shared ones. grafana_query_public_dashboard reads panel data from a dashboard that has been published with Grafana's public dashboard feature, and it is the only data-retrieval tool in this set. Private dashboards, ad-hoc panel queries, and direct Prometheus or Loki queries are not covered here. Grafana's own mcp-grafana server is the project aimed at that, and it is the honest recommendation if dashboard querying is the whole reason you came.

### What is this integration actually good for?
Two things. The first is operational status checks from chat: whether Grafana is up and can reach its database, whether an Enterprise licence is valid, and what state the Loki and Mimir hash rings are in, which is the kind of question you otherwise answer by opening several admin endpoints. The second is log ingestion: grafana_create_otlp_v1_logs sends OpenTelemetry logs into Loki, so an agent can write structured events into your logging stack as it works.

### Hermes paired but still can't use Grafana
Pairing is a two-step handshake: run `hermes clawlink begin`, approve the link in your browser, then run `hermes clawlink finish`. If you ran finish before approving, or the approval link expired, run `hermes clawlink begin` again to get a fresh link. Confirm the plugin was installed with `--enable`, then verify with `hermes clawlink test`.

## Related

- [SafetyCulture](https://claw-link.dev/hermes/safetyculture) — SafetyCulture (formerly iAuditor) is a workplace operations platform that enables teams to conduct digital inspections, manage audits, track issues, schedule tasks, and maintain compliance through mobile and web applications.
- [Connect LaunchDarkly](https://claw-link.dev/hermes/launch-darkly) — A feature management platform that helps teams build better software faster using feature flags.
- [Crowdin](https://claw-link.dev/hermes/crowdin) — Manage translations, localization projects, and language resources