Grafana MCP服务器

分叉自 Grafana MCP服务器

此存储库是原始Grafana MCP服务器的分支。
它包括下面列出的自定义修改。

上游变化

• 添加了对新工具的支持： QuestDB
  • 引入 questdb 启用/禁用标志
  • 添加 tools/questdb.go 实现QuestDB查询逻辑
• 添加了对新工具的支持： 雅典娜
  • 引入 athena 启用/禁用标志
  • 添加 tools/athena.go 实现Athena查询逻辑
• 扩展运输选项以提供支持 streamable-http
• 添加依赖关系： github.com/DataDog/zstd

Grafana MCP服务器

A. 模型上下文协议 Grafana的MCP服务器。

这提供了对Grafana实例和周围生态系统的访问。

特性

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

仪表盘

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

数据源

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

普罗米修斯查询

• 查询普罗米修斯： 对Prometheus数据源执行PromQL查询（支持即时和范围度量查询）。
• 查询Prometheus元数据： 从Prometheus数据源检索度量元数据、度量名称、标签名称和标签值。

洛基查询

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

事件

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

筛选调查

• 创建筛选调查： 开始新的筛选调查，以分析日志或痕迹。
• 列出筛选调查： 检索支持限制参数的筛选调查列表。
• 获取筛选调查： 通过UUID检索特定Sift调查的详细信息。
• 获取筛选分析： 从Sift调查中检索特定分析。
• 在日志中查找错误模式： 使用Sift检测Loki日志中升高的错误模式。
• 查找慢速请求： 使用Sift（Tempo）检测慢速请求。

告警

• 列出并获取警报规则信息： 在Grafana中查看警报规则及其状态（触发/正常/错误等）。
• 列出联系点： 查看Grafana中配置的通知联系人。

Grafana OnCall

• 列出并管理时间表： 在Grafana OnCall中查看和管理随叫随到时间表。
• 获取班次详细信息： 检索有关特定随叫随到轮班的详细信息。
• 获取当前随叫随到的用户： 查看哪些用户当前处于待命状态以获取日程安排。
• 列出团队和用户： 查看所有OnCall团队和用户。

管理员

• 列出团队： 查看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 标志：
     复制

     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 flag：对于此模式，您必须使用以下命令显式覆盖默认值 -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>"
         }
       }
     }
   }
   

注意：如果你看到 Error: spawn mcp-grafana ENOENT 在Claude Desktop中，您需要指定以下内容的完整路径 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模式。

在远程MCP服务器上使用VSCode

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

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

调试模式

您可以通过添加以下命令为Grafana传输启用调试模式 -debug 标志到命令。这将提供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模式。

发展

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

这个项目是用Go编写的。按照您平台的说明安装Go。

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

make run

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

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

您还可以在自定义构建的Docker映像中使用SSE传输来运行服务器。与已发布的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

这包括一个自定义的linter，用于检查中的未转义逗号 jsonschema 结构标签。逗号在 description 字段必须用转义符 \\, 以防止无声截断。您可以使用以下命令运行此linter：

make lint-jsonschema

请参阅 JSONSchema Linter文档 了解更多详情。

许可证

该项目根据 Apache许可证，版本2.0.