# Grafana MCP for Cursor

**Query Grafana logs, metrics, and dashboards from Cursor.** This MCP server lets the AI in Cursor call your Grafana instance via tools—no need to leave the editor to check logs or run a PromQL query.

- **Logs** – Loki, Elasticsearch. Filter by label (e.g. `call_id`, `session_id`, `request_id`) or custom LogQL/Lucene. Results saved to a temp file so Cursor can analyze them.
- **Metrics** – Run Prometheus/PromQL (or compatible) queries.
- **Dashboards** – List and inspect dashboards by UID.
- **Alerts** – List provisioned alert rules.
- **Explore** – Build “Open in Grafana” URLs for any query.

Works with any Grafana instance and any log/metric datasource you already use. No custom log store—Grafana stays the single source of truth.

**Package:** [grafana-cursor-mcp on npm](https://www.npmjs.com/package/grafana-cursor-mcp)

---

## Quick start

**You only need the MCP config and your Grafana URL + API key.** No clone or build required if you use the npm package.

### 1. Get a Grafana API token

- In Grafana: **Administration** → **Service accounts** (or **API Keys**) → create one with **Viewer** (or least privilege). Copy the token.

### 2. Add the MCP server to Cursor

Open Cursor **Settings** → **MCP** (or edit `~/.cursor/mcp.json`). Add this (or merge the `grafana-logs` entry into your existing `mcpServers`):

```json
{
  "mcpServers": {
    "grafana-logs": {
      "command": "npx",
      "args": ["-y", "grafana-cursor-mcp"],
      "env": {
        "GRAFANA_URL": "https://your-grafana.example.com",
        "GRAFANA_API_KEY": "your-service-account-token"
      }
    }
  }
}
```

**Replace only:**
- `GRAFANA_URL` → your Grafana base URL (no trailing slash).
- `GRAFANA_API_KEY` → the token from step 1.

Optional: add `"GRAFANA_DEFAULT_DATASOURCE_UID": "your-loki-uid"` to `env` if you have one default log datasource.

### 3. Restart Cursor

The AI can now use the Grafana tools. No clone or build—[grafana-cursor-mcp](https://www.npmjs.com/package/grafana-cursor-mcp) runs via `npx`.

---

### Alternative: run from source

If you prefer to clone and build locally:

```bash
git clone https://github.com/hacktivist1512/grafana-cursor-mcp.git
cd grafana-cursor-mcp
npm install
npm run build:mcp
```

In your MCP config, use `"command": "node"` and `"args": ["/absolute/path/to/grafana-cursor-mcp/packages/mcp-server/dist/index.js"]` instead of `npx`. See **`mcp.json.example`** in the repo.

---

## Config (env)

| Variable | Required | Description |
|----------|----------|-------------|
| `GRAFANA_URL` | Yes | Grafana base URL (e.g. `https://grafana.example.com`). |
| `GRAFANA_API_KEY` | Yes | Service account or API key token. (`GRAFANA_TOKEN` is also accepted.) |
| `GRAFANA_DEFAULT_DATASOURCE_UID` | No | Default log datasource UID so log tools don’t need `datasource_uid` when there’s only one. |

**Security:** Keep the API key only in env or MCP config—never in code or docs. Use a Viewer (or minimal) role.

---

## Tools the AI can use

### Logs

| Tool | Description |
|------|-------------|
| **list_log_datasources** | List log datasources (Loki, Elasticsearch) with name and UID. Use when the user hasn’t specified which datasource to query. |
| **get_logs** | Run a custom log query (LogQL for Loki, Lucene for ES). Optional `simple_query` for an extra case‑insensitive filter. Full result is written to a temp `.log` file (path returned; files removed after 24h). Default limit 7000 lines; the AI is instructed to ask the user how many lines to fetch. |
| **get_logs_for_call** | Get logs by **label** (e.g. `call_id`, `session_id`, `request_id`, `trace_id`). Use `label_name` to choose the label and `call_id` for the value. Optional `topic` for a second filter. Same temp file and “ask for limit” behavior. Fits any correlation/session/request id in Loki. |

### Metrics

| Tool | Description |
|------|-------------|
| **query_metrics** | Run a Prometheus/PromQL (or compatible) query. Params: `datasource_uid`, `query`, `from`, `to`, optional `instant`. Returns time series or table as text. |

### Grafana context

| Tool | Description |
|------|-------------|
| **grafana_info** | Get org name and all datasources (name, UID, type). Use to check connection and pick the right datasource. |
| **get_explore_url** | Build a Grafana Explore URL for a given datasource, query, and time range (“Open in Grafana”). |

### Dashboards

| Tool | Description |
|------|-------------|
| **list_dashboards** | Search dashboards (`query`, `folder`, `limit`). Returns title, UID, folder. |
| **get_dashboard** | Get a dashboard by UID. With `summary_only=true` (default) returns a short panel summary; otherwise full JSON. |

### Alerting

| Tool | Description |
|------|-------------|
| **list_alert_rules** | List provisioned alert rules (`/api/v1/provisioning/alert-rules`). Returns name, folder, rule group, condition. |

---

## Repo structure

- **`packages/mcp-server`** – MCP server (Node/TypeScript). All tools above; stdio transport for Cursor.
- **`packages/grafana-app`** – Optional Grafana app plugin (e.g. “Cursor logs” page and MCP snippet).

---

## Publishing (maintainers)

The package is published as [grafana-cursor-mcp](https://www.npmjs.com/package/grafana-cursor-mcp). To publish a new version: `cd packages/mcp-server`, bump version in `package.json`, then `npm publish`. See [docs/GITHUB_AND_NPM.md](docs/GITHUB_AND_NPM.md) for details.

---

## License

Apache-2.0. See [LICENSE](LICENSE).