JinDaGe - prometheus-mcp MCP Details

article

README

🚀 Prometheus MCP Server

Prometheus MCP Server 是一个模型上下文协议（MCP）服务器，它能让 AI 助手与 Prometheus 实现无缝集成，支持通过自然语言与监控基础设施进行交互。借助该服务器，你可以通过 Visual Studio Code、Cursor、Windsurf、Claude Desktop 等 MCP 客户端轻松查询、发现和分析指标。

🚀 快速开始

首先，将 Prometheus MCP 服务器与你的客户端进行安装。典型的配置如下：

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["prometheus-mcp@latest", "stdio"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

在 VS Code 中安装

# 对于 VS Code
code --add-mcp '{"name":"prometheus","command":"npx","args":["prometheus-mcp@latest","stdio"],"env":{"PROMETHEUS_URL":"http://localhost:9090"}}'

# 对于 VS Code Insiders
code-insiders --add-mcp '{"name":"prometheus","command":"npx","args":["prometheus-mcp@latest","stdio"],"env":{"PROMETHEUS_URL":"http://localhost:9090"}}'

安装完成后，Prometheus MCP 服务器即可在 VS Code 中与你的 GitHub Copilot 代理一起使用。

在 Cursor 中安装

前往 Cursor Settings → MCP → Add new MCP Server。你可以自行命名，使用 command 类型并输入命令 npx prometheus-mcp。也可以通过点击 Edit 来验证配置或添加命令参数。

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["prometheus-mcp@latest", "stdio"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

在 Windsurf 中安装

遵循 Windsurf MCP 文档进行操作，使用以下配置：

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["prometheus-mcp@latest", "stdio"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

在 Claude Desktop 中安装

Claude Desktop 支持两种安装方法：

选项 1：DXT 扩展

最简单的安装方式是使用预构建的 DXT 扩展：

从发布页面下载最新的 .dxt 文件。
双击下载的文件进行自动安装。
在扩展设置中配置你的 Prometheus URL。

选项 2：开发者设置

对于高级用户或需要自定义配置的情况，可以手动配置 MCP 服务器：

打开 Claude Desktop 设置。
导航到 Developer 部分。
添加以下 MCP 服务器配置：

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["prometheus-mcp@latest", "stdio"],
      "env": {
        "PROMETHEUS_URL": "http://localhost:9090"
      }
    }
  }
}

✨ 主要特性

快速轻量：与 Prometheus 直接进行 API 集成，无需复杂解析。
对大语言模型友好：结构化的 JSON 响应经过优化，便于 AI 助手使用。
可配置功能：可根据安全和运营需求启用或禁用工具类别。
双传输支持：支持 stdio 和 HTTP 两种传输方式，具备最大兼容性。

📦 安装指南

系统要求

Node.js 20.19.0 或更高版本
能够访问 Prometheus 服务器
需安装 VS Code、Cursor、Windsurf、Claude Desktop 或其他 MCP 客户端

安装命令

具体安装命令可参考快速开始部分的不同客户端安装步骤。

📚 详细文档

配置

Prometheus MCP 服务器支持以下参数，可在上述 JSON 配置的 "args" 列表中提供：

> npx prometheus-mcp@latest --help

Commands:
  stdio  Start Prometheus MCP server using stdio transport
  http   Start Prometheus MCP server using HTTP transport

Options:
  --help     Show help                          [boolean]
  --version  Show version number                [boolean]

环境变量

你还可以使用环境变量来配置服务器：

PROMETHEUS_URL - Prometheus 服务器的 URL
ENABLE_DISCOVERY_TOOLS - 设置为 "false" 可禁用发现工具（默认值：true）
ENABLE_INFO_TOOLS - 设置为 "false" 可禁用信息工具（默认值：true）
ENABLE_QUERY_TOOLS - 设置为 "false" 可禁用查询工具（默认值：true）

独立 MCP 服务器

当在服务器环境中运行或需要使用 HTTP 传输时，可使用 http 命令启动 MCP 服务器：

npx prometheus-mcp@latest http --port 3000

然后在你的 MCP 客户端配置中，将 url 设置为 HTTP 端点：

{
  "mcpServers": {
    "prometheus": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Docker 部署

使用 Docker 运行 Prometheus MCP 服务器：

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "--pull=always",
        "-e",
        "PROMETHEUS_URL=http://host.docker.internal:9090",
        "ghcr.io/idanfishman/prometheus-mcp",
        "stdio"
      ]
    }
  }
}

工具

Prometheus MCP 服务器提供了 10 个工具，分为三个可配置的类别：

发现

用于探索 Prometheus 基础设施的工具：

prometheus_list_metrics
- 描述：列出所有可用的 Prometheus 指标
- 参数：无
- 只读：true
prometheus_metric_metadata
- 描述：获取特定 Prometheus 指标的元数据
- 参数：
  - metric (字符串)：要获取元数据的指标名称
- 只读：true
prometheus_list_labels
- 描述：列出所有可用的 Prometheus 标签
- 参数：无
- 只读：true
prometheus_label_values
- 描述：获取特定 Prometheus 标签的所有值
- 参数：
  - label (字符串)：要获取值的标签名称
- 只读：true
prometheus_list_targets
- 描述：列出所有 Prometheus 抓取目标
- 参数：无
- 只读：true
prometheus_scrape_pool_targets
- 描述：获取特定抓取池的目标
- 参数：
  - scrapePool (字符串)：抓取池名称
- 只读：true

信息

用于访问 Prometheus 服务器信息的工具：

prometheus_runtime_info
- 描述：获取 Prometheus 运行时信息
- 参数：无
- 只读：true
prometheus_build_info
- 描述：获取 Prometheus 构建信息
- 参数：无
- 只读：true

查询

用于执行 Prometheus 查询的工具：

prometheus_query
- 描述：执行即时 Prometheus 查询
- 参数：
  - query (字符串)：Prometheus 查询表达式
  - time (字符串，可选)：查询的时间参数（RFC3339 格式）
- 只读：true
prometheus_query_range
- 描述：执行 Prometheus 范围查询
- 参数：
  - query (字符串)：Prometheus 查询表达式
  - start (字符串)：开始时间戳（RFC3339 或 Unix 时间戳）
  - end (字符串)：结束时间戳（RFC3339 或 Unix 时间戳）
  - step (字符串)：查询分辨率步长
- 只读：true

示例用法

以下是一些你可以与 AI 助手进行交互的示例：

基本查询

"Show me all available metrics in Prometheus"（显示 Prometheus 中所有可用的指标）
"What's the current CPU usage across all instances?"（所有实例的当前 CPU 使用率是多少？）
"Get the memory usage for the last hour"（获取过去一小时的内存使用情况）

发现和探索

"List all scrape targets and their status"（列出所有抓取目标及其状态）
"What labels are available for the http_requests_total metric?"（http_requests_total 指标有哪些可用的标签？）
"Show me all metrics related to 'cpu'"（显示所有与 "cpu" 相关的指标）

高级分析

"Compare CPU usage between production and staging environments"（比较生产环境和暂存环境的 CPU 使用率）
"Show me the top 10 services by memory consumption"（显示内存消耗排名前十的服务）
"What's the error rate trend for the API service over the last 24 hours?"（API 服务在过去 24 小时内的错误率趋势如何？）

安全考虑

网络访问：服务器需要网络访问你的 Prometheus 实例。
资源使用：范围查询可能会消耗大量资源，请监控你的 Prometheus 服务器负载。

故障排除

连接问题

验证你的 Prometheus 服务器在配置的 URL 上是否可访问。
检查防火墙设置和网络连接。
确保 Prometheus API 已启用（默认端口为 9090）。

权限错误

验证 MCP 服务器是否有网络访问 Prometheus 的权限。
检查你的 Prometheus 设置是否需要身份验证。

工具可用性

如果某些工具缺失，请检查是否通过配置禁用了它们。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

支持

GitHub 问题：报告错误或请求功能
文档：模型上下文协议文档
Prometheus：Prometheus 文档

本项目是为 Prometheus 和 MCP 社区精心打造的 ❤️

prometheus-mcp