Grafana MCP 服务器

一个用于 Grafana 的 模型上下文协议（MCP） 服务器。

它提供对您的 Grafana 实例及其周边生态系统的访问。

功能

以下功能目前可在 MCP 服务器中使用。此列表仅供参考，不代表路线图或对未来的功能承诺。

仪表板

• 搜索仪表板：通过标题或其他元数据查找仪表板
• 通过 UID 获取仪表板：使用其唯一标识符检索完整的仪表板详细信息
• 更新或创建仪表板：修改现有仪表板或创建新仪表板。注意：由于上下文窗口限制，请谨慎使用；参见问题 #101
• 获取面板查询和数据源信息：从仪表板的每个面板获取标题、查询字符串和数据源信息（包括 UID 和类型，如果可用）

数据源

• 列出和获取数据源信息：查看所有配置的数据源并检索每个数据源的详细信息。
  • 支持的数据源类型：Prometheus、Loki.

Prometheus 查询

• 查询 Prometheus：对 Prometheus 数据源执行 PromQL 查询（支持瞬时和范围指标查询）
• 查询 Prometheus 元数据：从 Prometheus 数据源检索指标元数据、指标名称、标签名称和标签值

Loki 查询

• 查询 Loki 日志和指标：使用 LogQL 对 Loki 数据源运行日志查询和指标查询
• 查询 Loki 元数据：从 Loki 数据源检索标签名称、标签值和流统计信息

事件

• 搜索、创建、更新和关闭事件：管理 Grafana 事件中的事件，包括搜索、创建、更新和解决事件

Sift 调查

• 创建 Sift 调查：开始一个新的 Sift 调查，用于分析日志或跟踪
• 列出 Sift 调查：检索 Sift 调查列表，支持 limit 参数
• 获取 Sift 调查：通过其 UUID 检索特定 Sift 调查的详细信息
• 获取 Sift 分析：从 Sift 调查中检索特定分析
• 在日志中查找错误模式：使用 Sift 检测 Loki 日志中的错误模式
• 查找慢请求：使用 Sift（Tempo）检测慢请求

告警

• 列出和获取告警规则信息：查看 Grafana 中的告警规则及其状态（触发/正常/错误等）
• 列出联系点：查看 Grafana 中配置的告警联系点

Grafana OnCall

• 列出和管理计划：查看和管理 Grafana OnCall 中的计划
• 获取班次详细信息：检索特定 OnCall 班次的详细信息
• 获取当前 OnCall 用户：查看哪些用户当前正在某个计划中值班
• 列出团队和用户：查看所有 OnCall 团队和用户

管理

• 列出团队：查看 Grafana 中所有配置的团队
• 列出用户：查看组织中 Grafana 中的所有用户

工具列表是可配置的，因此您可以选择要向 MCP 客户端提供的工具。 如果您不使用某些功能或不想占用太多上下文窗口，这很有用。 要禁用某个工具类别，请在启动服务器时使用 --disable-<category> 标志。例如，要禁用 OnCall 工具，请使用 --disable-oncall。

工具

使用方法

1. 在 Grafana 中创建一个具有足够权限的服务账户，以使用您想要使用的工具，生成一个服务账户令牌，并将其复制到剪贴板以用于配置文件。有关详细信息，请参阅 Grafana 文档。

2. 您有几种选项可以安装 mcp-grafana：

   • Docker 镜像：使用 Docker Hub 中的预构建 Docker 镜像。

     重要：Docker 镜像的入口点是默认配置为在 SSE 模式下运行 MCP 服务器，但大多数用户希望使用 STDIO 模式以直接与 Claude Desktop 等 AI 助手集成：

     1. STDIO 模式：对于 stdio 模式，您必须显式覆盖默认值，使用 -t stdio 并包含 -i 标志以保持 stdin 打开：

     docker pull mcp/grafana
     docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana -t stdio
     

     2. SSE 模式：在此模式下，服务器作为 HTTP 服务器运行，客户端连接到此服务器。您必须使用 -p 标志暴露端口 8000：

     docker pull mcp/grafana
     docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana
     

     3. 流式 HTTP 模式：在此模式下，服务器作为独立进程运行，可以处理多个客户端连接。您必须使用 -p 标志暴露端口 8000：对于此模式，您必须显式覆盖默认值，使用 -t streamable-http

     docker pull mcp/grafana
     docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana -t streamable-http
     

   • 下载二进制文件：从 发布页面 下载 mcp-grafana 的最新版本，并将其放置在您的 $PATH 中。

   • 从源代码构建：如果您安装了 Go 工具链，也可以从源代码构建和安装它，使用 GOBIN 环境变量指定二进制文件应安装的目录。这也应在您的 PATH 中。

     GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
     

3. 将服务器配置添加到您的客户端配置文件中。例如，对于 Claude Desktop：

   如果使用二进制文件：

   {
     "mcpServers": {
       "grafana": {
         "command": "mcp-grafana",
         "args": [],
         "env": {
           "GRAFANA_URL": "http://localhost:3000",
           "GRAFANA_API_KEY": "<your service account token>"
         }
       }
     }
   }
   

注意：如果在 Claude Desktop 中看到 Error: spawn mcp-grafana ENOENT，您需要指定 mcp-grafana 的完整路径。

如果使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

注意：这里的 -t stdio 参数至关重要，因为它覆盖了 Docker 镜像中的默认 SSE 模式。

使用 VSCode 与远程 MCP 服务器

如果您使用 VSCode 并在 SSE 模式下运行 MCP 服务器（使用 Docker 镜像而不覆盖传输时是默认模式），请确保您的 .vscode/settings.json 包含以下内容：

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

调试模式

您可以通过向命令添加 -debug 标志来启用 Grafana 传输的调试模式。这将提供 MCP 服务器与 Grafana API 之间 HTTP 请求和响应的详细日志，这对于故障排除非常有帮助。

要在使用 Claude Desktop 配置时使用调试模式，请按如下更新您的配置：

如果使用二进制文件：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

如果使用 Docker：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

注意：与标准配置一样，-t stdio 参数是必要的，以覆盖 Docker 镜像中的默认 SSE 模式。

TLS 配置

如果您的 Grafana 实例位于 mTLS 后或需要自定义 TLS 证书，您可以配置 MCP 服务器使用自定义证书。服务器支持以下 TLS 配置选项：

• --tls-cert-file：客户端认证的 TLS 证书文件路径
• --tls-key-file：客户端认证的 TLS 私有密钥文件路径
• --tls-ca-file：服务器验证的 TLS CA 证书文件路径
• --tls-skip-verify：跳过 TLS 证书验证（不安全，仅用于测试）

使用客户端证书认证的示例：

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file", "/path/to/client.crt",
        "--tls-key-file", "/path/to/client.key",
        "--tls-ca-file", "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

使用 Docker 的示例：

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "/path/to/certs:/certs:ro",
        "-e", "GRAFANA_URL",
        "-e", "GRAFANA_API_KEY",
        "mcp/grafana",
        "-t", "stdio",
        "--tls-cert-file", "/certs/client.crt",
        "--tls-key-file", "/certs/client.key",
        "--tls-ca-file", "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

TLS 配置应用于 MCP 服务器使用的所有 HTTP 客户端，包括：

• 主 Grafana OpenAPI 客户端
• Prometheus 数据源客户端
• Loki 数据源客户端
• 事件管理客户端
• Sift 调查客户端
• 告警客户端
• Asserts 客户端

直接 CLI 使用示例：

对于使用自签名证书进行测试：

./mcp-grafana --tls-skip-verify -debug

使用客户端证书认证：

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

仅使用自定义 CA 证书：

./mcp-grafana --tls-ca-file /path/to/ca.crt

程序化使用：

如果您正在程序化使用此库，您还可以创建支持 TLS 的上下文函数：

// 使用结构字面量
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// 或内联
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

开发

欢迎贡献！如果您有任何建议或改进，请打开一个问题或提交一个拉取请求。

此项目使用 Go 编写。按照您的平台的说明安装 Go。

要在 STDIO 模式下本地运行服务器（这是本地开发的默认模式），使用：

make run

要在 SSE 模式下本地运行服务器，使用：

go run ./cmd/mcp-grafana --transport sse

您也可以使用 SSE 传输在自定义构建的 Docker 镜像中运行服务器。与发布的 Docker 镜像一样，此自定义镜像的入口点默认为 SSE 模式。要构建镜像，使用：

make build-image

并且要在 SSE 模式下运行镜像（默认模式），使用：

docker run -it --rm -p 8000:8000 mcp-grafana:latest

如果您需要以 STDIO 模式运行，请覆盖传输设置：

docker run -it --rm mcp-grafana:latest -t stdio

测试

提供三种类型的测试：

1. 单元测试（无需外部依赖）：

make test-unit

您也可以使用以下命令运行单元测试：

make test

2. 集成测试（需要正在运行的 docker 容器）：

make test-integration

3. 云测试（需要云 Grafana 实例和凭证）：

make test-cloud

注意：云测试在 CI 中自动配置。对于本地开发，您需要设置自己的 Grafana Cloud 实例和凭证。

更全面的集成测试需要一个本地运行的 Grafana 实例，端口为 3000；您可以使用 Docker Compose 启动一个：

docker-compose up -d

集成测试可以运行：

make test-all

如果您添加了更多工具，请为它们添加集成测试。现有测试应该是一个很好的起点。

代码风格检查

要检查代码风格，运行：

make lint

这包括一个自定义代码风格检查器，用于检查 jsonschema 结构标签中的未转义逗号。description 字段中的逗号必须用 \\, 转义以防止静默截断。您可以使用以下命令仅运行此代码风格检查器：

make lint-jsonschema

有关更多详细信息，请参阅 JSONSchema 代码风格检查器文档。

许可证

本项目根据 Apache License, Version 2.0 授权。