Back to Details

assistant-mcp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Grafana Cloud MCP Server Setup

Grafana Cloud MCP Server 设置

The Grafana MCP server exposes Grafana Cloud capabilities as tools that AI agents can call via the Model Context Protocol. Once connected, agents can query metrics, search dashboards, manage alerts, investigate incidents, and interact with Fleet Management - all without leaving their coding environment.
Available transports:
  • stdio
    - agent spawns the server as a subprocess (simplest, works everywhere)
  • SSE
    - server runs independently, agent connects via HTTP
Grafana MCP服务器通过Model Context Protocol将Grafana Cloud的功能以工具形式暴露，供AI代理调用。连接完成后，代理无需离开编码环境，即可查询指标、搜索仪表盘、管理告警、调查事件，并与Fleet Management交互。
可用传输方式：
  • stdio
    - 代理将服务器作为子进程启动（最简单，适用于所有环境）
  • SSE
    - 服务器独立运行，代理通过HTTP连接

Step 1: Get your Grafana Cloud credentials

步骤1：获取Grafana Cloud凭证

You need a Service Account token with appropriate scopes.
  1. Go to your Grafana Cloud instance > Administration > Service Accounts
  2. Create a service account with the 
    Viewer
    role (add 
    Editor
    if you need write operations)
  3. Generate a token for that service account
  4. Note your Grafana URL (e.g. 
    https://myorg.grafana.net
    ) and the token
For Grafana Cloud Prometheus/Loki/Tempo access you may also need:
  • Metrics username and API key (from Cloud Portal > Stack > Details)
  • Or a single Cloud Access Policy token with the required scopes
您需要一个具有适当权限范围的服务账户令牌。
  1. 进入您的Grafana Cloud实例 > Administration > Service Accounts
  2. 创建一个拥有
    Viewer
    角色的服务账户（如果需要写入操作，添加
    Editor
    角色）
  3. 为该服务账户生成令牌
  4. 记录您的Grafana URL（例如
    https://myorg.grafana.net
    ）和令牌
对于Grafana Cloud Prometheus/Loki/Tempo访问，您可能还需要：
  • Metrics用户名和API密钥（来自Cloud Portal > Stack > Details）
  • 或者一个具有所需权限范围的Cloud Access Policy令牌

Step 2: Install the Grafana MCP server

步骤2：安装Grafana MCP服务器

bash
undefined
bash
undefined

Via Go (recommended - always gets latest)

Via Go (recommended - always gets latest)

go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

Verify

Verify

mcp-grafana --version

Alternatively, download a pre-built binary from the [releases page](https://github.com/grafana/mcp-grafana/releases).

---
mcp-grafana --version

或者，从[发布页面](https://github.com/grafana/mcp-grafana/releases)下载预构建的二进制文件。

---

Step 3: Configure Claude Code

步骤3：配置Claude Code

Add the server to Claude Code's MCP configuration. The config file is at:
  • macOS/Linux: 
    ~/.claude/settings.json
    or the project's 
    .claude/settings.json
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}
Read-only mode (safer for exploration - disables all write tools):
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["--disable-write"],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}
Restart Claude Code after editing settings. Run 
/mcp
in Claude Code to verify the server appears and its tools are listed.
将服务器添加到Claude Code的MCP配置中。配置文件位于：
  • macOS/Linux：
    ~/.claude/settings.json
    或项目的 
    .claude/settings.json
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}
只读模式（探索时更安全 - 禁用所有写入工具）：
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["--disable-write"],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}
编辑设置后重启Claude Code。在Claude Code中运行
/mcp
以验证服务器是否已显示，且其工具已列出。

Step 4: Configure Cursor

步骤4：配置Cursor

In Cursor: Settings > Features > MCP Servers (or edit 
~/.cursor/mcp.json
):
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}
在Cursor中：Settings > Features > MCP Servers（或编辑
~/.cursor/mcp.json
）：
json
{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}

Step 5: Run as SSE server (for team sharing or VS Code)

步骤5：以SSE服务器运行（用于团队共享或VS Code）

Run the server as a long-lived SSE process instead of per-session stdio:
bash
GRAFANA_URL=https://myorg.grafana.net \
GRAFANA_API_KEY=glsa_xxxx \
mcp-grafana --transport sse --port 3001
Then point agents at 
http://localhost:3001/sse
.
VS Code MCP extension config (
settings.json
):
json
{
  "mcp.servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    }
  }
}
将服务器作为长期运行的SSE进程运行，而非按会话启动的stdio：
bash
GRAFANA_URL=https://myorg.grafana.net \
GRAFANA_API_KEY=glsa_xxxx \
mcp-grafana --transport sse --port 3001
然后将代理指向
http://localhost:3001/sse
。
VS Code MCP扩展配置（
settings.json
）：
json
{
  "mcp.servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    }
  }
}

Step 6: Available tools and what they do

步骤6：可用工具及其功能

Once connected, the agent can call:
Query tools:
  • query_prometheus
    - run PromQL queries against Grafana Cloud Metrics
  • query_loki
    - run LogQL queries against Grafana Cloud Logs
  • query_tempo
    - run TraceQL queries against Grafana Cloud Traces
  • list_datasources
    - enumerate configured data sources
Dashboard tools:
  • search_dashboards
    - find dashboards by name, tag, or folder
  • get_dashboard
    - retrieve full dashboard JSON
  • create_dashboard
    - create or update a dashboard (requires Editor role)
Alerting and incident tools:
  • list_alert_rules
    - list firing and pending alerts
  • get_alert_rule
    - get details of a specific alert rule
  • list_incidents
    - list active incidents (requires IRM)
Fleet Management tools (if collector-app is installed):
  • list_collectors
    - list Alloy collectors and their health status
  • list_pipelines
    - list remote configuration pipelines
  • get_pipeline
    - get pipeline YAML content
Annotation tools:
  • list_annotations
    - search dashboard annotations by time range
  • create_annotation
    - add an annotation to a dashboard
连接完成后，代理可调用以下工具：
查询工具：
  • query_prometheus
    - 针对Grafana Cloud Metrics运行PromQL查询
  • query_loki
    - 针对Grafana Cloud Logs运行LogQL查询
  • query_tempo
    - 针对Grafana Cloud Traces运行TraceQL查询
  • list_datasources
    - 枚举已配置的数据源
仪表盘工具：
  • search_dashboards
    - 按名称、标签或文件夹查找仪表盘
  • get_dashboard
    - 获取完整的仪表盘JSON
  • create_dashboard
    - 创建或更新仪表盘（需要Editor角色）
告警与事件工具：
  • list_alert_rules
    - 列出触发中和待处理的告警
  • get_alert_rule
    - 获取特定告警规则的详情
  • list_incidents
    - 列出活跃事件（需要IRM）
Fleet Management工具（如果已安装collector-app）：
  • list_collectors
    - 列出Alloy采集器及其健康状态
  • list_pipelines
    - 列出远程配置流水线
  • get_pipeline
    - 获取流水线YAML内容
注释工具：
  • list_annotations
    - 按时间范围搜索仪表盘注释
  • create_annotation
    - 为仪表盘添加注释

Step 7: Verify the connection

步骤7：验证连接

In Claude Code, ask the agent to use a Grafana tool:
What data sources are configured in my Grafana instance?
Or:
Show me dashboards tagged with "kubernetes" in my Grafana.
If the tool call fails:
  • Check 
    GRAFANA_URL
    has no trailing slash
  • Confirm the API key has not expired
  • Try 
    mcp-grafana --debug
    to see raw request/response logs
在Claude Code中，让代理使用Grafana工具：
我的Grafana实例中配置了哪些数据源？
或者：
展示我的Grafana中标记为"kubernetes"的仪表盘。
如果工具调用失败：
  • 检查
    GRAFANA_URL
    末尾没有斜杠
  • 确认API密钥未过期
  • 尝试
    mcp-grafana --debug
    查看原始请求/响应日志

Step 8: Use with the Grafana Skills

步骤8：与Grafana Skills配合使用

If you have the 
grafana-core
skills installed, the agent already knows:
  • PromQL query patterns (from 
    grafana-core/promql
    )
  • Dashboard structure (from 
    grafana-core/dashboarding
    )
  • Fleet Management concepts (from 
    grafana-cloud/fleet-management
    )
Combined with the MCP tools, the agent can answer questions like:
  • "What is the p95 latency of the payments service over the last hour?"
  • "Create a dashboard showing CPU and memory usage for the production cluster"
  • "Which collectors are unhealthy and what errors do they have?"
  • "Show me all alert rules that fired in the last 24 hours"
如果您已安装
grafana-core
技能，代理已了解：
  • PromQL查询模式（来自
    grafana-core/promql
    ）
  • 仪表盘结构（来自
    grafana-core/dashboarding
    ）
  • Fleet Management概念（来自
    grafana-cloud/fleet-management
    ）
结合MCP工具，代理可回答以下问题：
  • "过去一小时内支付服务的p95延迟是多少？"
  • "创建一个显示生产集群CPU和内存使用率的仪表盘"
  • "哪些采集器状态异常，它们有什么错误？"
  • "展示过去24小时内触发的所有告警规则"

Grafana Assistant A2A (Agent-to-Agent)

Grafana Assistant A2A（Agent-to-Agent）

The Grafana Assistant supports the A2A protocol for agent-to-agent communication. External agents can discover available Grafana agents at:
GET https://<GRAFANA_ASSISTANT_HOST>/.well-known/agent.json
This returns an Agent Card describing the supervisor agent's capabilities. Use this for programmatic integration when building agents that need to delegate observability reasoning to the Grafana Assistant.
Grafana Assistant支持Agent-to-Agent协议，用于代理间通信。外部代理可通过以下地址发现可用的Grafana代理：
GET https://<GRAFANA_ASSISTANT_HOST>/.well-known/agent.json
该请求会返回描述主管代理功能的Agent Card。当构建需要将可观测性推理委托给Grafana Assistant的代理时，可使用此方式进行程序化集成。

Security considerations

安全注意事项

  • Store API keys in environment variables or a secrets manager - never in committed files
  • Use read-only mode (
    --disable-write
    ) for shared or CI environments
  • Scope service account permissions to the minimum required (Viewer is sufficient for queries)
  • Rotate tokens periodically via Administration > Service Accounts
  • 将API密钥存储在环境变量或密钥管理器中 - 切勿提交到代码仓库
  • 在共享或CI环境中使用只读模式（
    --disable-write
    ）
  • 将服务账户权限限制为所需的最小范围（查询仅需Viewer角色）
  • 通过Administration > Service Accounts定期轮换令牌

References

参考资料