Metadata-Version: 2.4
Name: prom-mcp-server
Version: 0.1.0
Summary: MCP Server for Prometheus monitoring - query metrics, alerts, targets via natural language
Project-URL: Homepage, https://github.com/ives22/mcp-tools
Project-URL: Repository, https://github.com/ives22/mcp-tools
Project-URL: Documentation, https://github.com/ives22/mcp-tools/tree/main/servers/prometheus-mcp-server#readme
Project-URL: Issues, https://github.com/ives22/mcp-tools/issues
Author: Jalen
License: MIT
Keywords: ai-agent,mcp,metrics,monitoring,prometheus
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: starlette>=0.27.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# Prometheus MCP Server

一个独立的 MCP Server，提供 Prometheus 监控指标的查询能力，支持通过自然语言与 AI 助手交互。

## ✨ 功能特性

- 📊 **即时查询** - 查询当前指标值（`/api/v1/query`）
- 📈 **范围查询** - 查询历史数据趋势（`/api/v1/query_range`）
- 🔍 **序列发现** - 查找匹配的时间序列，无需计算值（`/api/v1/series`）
- 🚨 **告警管理** - 查看告警规则和当前活动告警
- 📡 **Alertmanager** - 查看 Alertmanager 实例及连接状态
- 🎯 **目标状态** - 查看 scrape targets 的健康状态
- 📖 **指标元数据** - 了解指标类型、帮助文本和单位
- 🏷️ **标签查询** - 发现标签的可能值
- ⚙️ **运行时配置** - 查看 Prometheus 运行时 YAML 配置
- 🚩 **启动参数** - 查看 Prometheus 命令行启动参数
- 💻 **运行时信息** - 查看 goroutine、GOMAXPROCS、内存分配等内部状态
- 🗄️ **TSDB 统计** - 查看 head series、WAL、compaction 等存储状态
- 🎯 **目标元数据** - 查看特定 target 暴露的指标信息
- 🔐 **多环境支持** - 同时管理多个 Prometheus 实例
- 🔒 **认证兼容** - 支持无认证、Basic Auth、Bearer Token

## 🏗️ 架构

### stdio 模式（推荐）

```
┌─────────────┐     stdio (stdin/stdout)     ┌─────────────────────┐
│  Hermes     │ ◄──────────────────────────► │  Prometheus         │
│  Agent      │                              │  MCP Server (子进程)  │
│             │                              └────────┬────────────┘
└─────────────┘                                       │
                                            ┌─────────┴─────────┐
                                            │  Config File       │
                                            │  (~/.prometheus-   │
                                            │   mcp/config.yaml) │
                                            └────────────────────┘
```

### HTTP 模式（独立服务）

```
┌─────────────┐    HTTP/StreamableHTTP     ┌─────────────────────┐
│  Hermes     │ ◄────────────────────────► │  Prometheus         │
│  Agent      │   MCP Protocol             │  MCP Server (独立服务)│
└─────────────┘                            └────────┬────────────┘
                                                    │
                                          ┌─────────┴─────────┐
                                          │  Config File       │
                                          │  (~/.prometheus-   │
                                          │   mcp/config.yaml) │
                                          └────────────────────┘
```

## 🚀 快速开始

### 1. 安装

#### 从 Git 仓库安装

```bash
pip install git+https://github.com/ives22/mcp-tools.git#subdirectory=servers/prometheus-mcp-server
```

#### 从源码安装

```bash
git clone https://github.com/ives22/mcp-tools.git
cd mcp-tools/servers/prometheus-mcp-server
pip install .
```

#### 使用 uvx 免安装运行

```bash
# 首次运行会自动下载，无需手动 pip install
uvx prometheus-mcp-server --transport stdio
```

#### 使用 Docker（HTTP 模式，无需 Python 环境）

```bash
# 构建镜像
git clone https://github.com/ives22/mcp-tools.git
cd mcp-tools/servers/prometheus-mcp-server
docker build -t prometheus-mcp-server .

# 运行（挂载配置文件）
docker run -d --name prometheus-mcp \
  -p 8000:8000 \
  -v ~/.prometheus-mcp/config.yaml:/root/.prometheus-mcp/config.yaml \
  prometheus-mcp-server

# 或使用 docker-compose（见下方 docker-compose 章节）
```

### 2. 配置

```bash
# 创建配置目录
mkdir -p ~/.prometheus-mcp

# 复制配置模板
cp config/config.yaml.example ~/.prometheus-mcp/config.yaml

# 编辑配置，填入你的 Prometheus 地址和认证信息
vim ~/.prometheus-mcp/config.yaml
```

### 3. 启动服务

#### 方式一：uvx 直接运行（推荐，免安装）

```bash
# stdio 模式（用于 AI Agent 本地集成，推荐）
uvx prometheus-mcp-server --transport stdio

# HTTP 模式（独立服务，用于远程或多客户端共享）
uvx prometheus-mcp-server --host 0.0.0.0 --port 8000
```

#### 方式二：本地安装后运行

```bash
# HTTP 模式（默认，独立服务）
prometheus-mcp-server --host 0.0.0.0 --port 8000

# stdio 模式（本地集成）
prometheus-mcp-server --transport stdio

# 详细日志
prometheus-mcp-server -v
```

#### 方式三：Docker 运行

```bash
# HTTP 模式（默认）
docker run -d -p 8000:8000 \
  -v ~/.prometheus-mcp/config.yaml:/root/.prometheus-mcp/config.yaml \
  prometheus-mcp-server

# 自定义端口
docker run -d -p 9000:9000 \
  -v ~/.prometheus-mcp/config.yaml:/root/.prometheus-mcp/config.yaml \
  prometheus-mcp-server --port 9000

# stdio 模式（用于 Docker + MCP 客户端集成）
docker run -i --rm \
  -v ~/.prometheus-mcp/config.yaml:/root/.prometheus-mcp/config.yaml \
  prometheus-mcp-server --transport stdio
```

### 4. 配置 MCP 客户端

本 MCP Server 兼容所有支持 MCP 协议的客户端（Hermes Agent、Claude Desktop、Cursor、Continue 等）。

#### stdio 模式（推荐，无需启动独立服务）

**Hermes Agent** (`~/.hermes/config.yaml`)：

```yaml
mcp_servers:
  prometheus:
    command: "uvx"
    args: ["prometheus-mcp-server", "--transport", "stdio"]
    timeout: 60
    connect_timeout: 30
```

**Claude Desktop** (`claude_desktop_config.json`)：

```json
{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp-server", "--transport", "stdio"]
    }
  }
}
```

#### HTTP 模式（独立服务）

先启动 HTTP 服务，然后在客户端配置中添加：

```yaml
mcp_servers:
  prometheus:
    url: "http://localhost:8000/mcp"
    timeout: 60
    connect_timeout: 30
```

### 5. Docker Compose（可选）

适合长期运行的 HTTP 服务模式：

```yaml
# docker-compose.yml
services:
  prometheus-mcp:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./config.yaml:/root/.prometheus-mcp/config.yaml:ro
    restart: unless-stopped
    environment:
      - LOG_LEVEL=INFO
```

```bash
# 启动
docker-compose up -d

# 查看日志
docker-compose logs -f
```

## 📋 可用工具

| 工具名称 | 描述 | 对应 API |
|---------|------|----------|
| `prometheus_query` | 即时 PromQL 查询（当前值） | `/api/v1/query` |
| `prometheus_query_range` | 范围查询（历史数据） | `/api/v1/query_range` |
| `prometheus_query_series` | 查找匹配的时间序列（不计算值） | `/api/v1/series` |
| `prometheus_list_rules` | 查看告警/记录规则 | `/api/v1/rules` |
| `prometheus_list_alerts` | 查看当前活动告警 | `/api/v1/alerts` |
| `prometheus_list_targets` | 查看 scrape 目标状态 | `/api/v1/targets` |
| `prometheus_get_metadata` | 获取指标元数据（类型、帮助文本） | `/api/v1/metadata` |
| `prometheus_get_label_values` | 获取标签的所有可能值 | `/api/v1/label/<name>/values` |
| `prometheus_list_metrics` | 列出所有可用指标名称 | `/api/v1/label/__name__/values` |
| `prometheus_list_labels` | 列出所有标签名称 | `/api/v1/labels` |
| `prometheus_list_environments` | 列出所有配置的环境 | — |
| `prometheus_health` | 检查 Prometheus 健康状态和版本信息 | `/api/v1/status/buildinfo` |
| `prometheus_get_config` | 获取 Prometheus 运行时配置（YAML） | `/api/v1/status/config` |
| `prometheus_get_flags` | 获取 Prometheus 启动参数 | `/api/v1/status/flags` |
| `prometheus_list_alertmanagers` | 列出 Alertmanager 实例及连接状态 | `/api/v1/alertmanagers` |
| `prometheus_get_runtime_info` | 获取 Prometheus 运行时信息（goroutine、内存等） | `/api/v1/status/runtimeinfo` |
| `prometheus_get_tsdb_stats` | 获取 TSDB 统计信息（head series、WAL、compaction） | `/api/v1/status/tsdb` |
| `prometheus_get_target_metadata` | 获取目标元数据（特定 target 暴露的指标） | `/api/v1/targets/metadata` |

## 💬 使用示例

配置完成后，可以通过自然语言向机器人提问：

```
用户: "帮我查一下 production 环境当前有多少服务是 up 的"
→ Agent 调用 mcp_prometheus_query(query="up", env="production")

用户: "过去 1 小时 production 的 CPU 使用率趋势如何？"
→ Agent 调用 mcp_prometheus_query_range(
      query="100 - (avg by(instance) (rate(node_cpu_seconds_total{mode='idle'}[5m])) * 100)",
      env="production",
      start="1h ago",
      step="5m"
    )

用户: "production 环境有哪些告警正在触发？"
→ Agent 调用 mcp_prometheus_list_alerts(env="production")

用户: "staging 环境的 node_exporter targets 状态正常吗？"
→ Agent 调用 mcp_prometheus_list_targets(env="staging")
```

## ⚙️ 配置说明

### 环境配置

```yaml
environments:
  production:
    url: "http://prometheus.prod:9090"
    auth:
      type: "none"  # none | basic | bearer
      # basic 认证:
      # type: "basic"
      # username: "admin"
      # password: "secret"
      # bearer 认证:
      # type: "bearer"
      # token: "your-token"
    timeout: 30        # 请求超时（秒）
    verify_ssl: true   # SSL 证书验证
```

### 启动参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--config` | `~/.prometheus-mcp/config.yaml` | 配置文件路径 |
| `--host` | `0.0.0.0` | HTTP 监听地址 |
| `--port` | `8000` | HTTP 监听端口 |
| `--transport` | `http` | 传输模式（http/stdio） |
| `--verbose`, `-v` | `false` | 详细日志 |

## 🔧 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码检查
ruff check src/
mypy src/
```

## 📁 项目结构

```
prometheus-mcp-server/
├── pyproject.toml                 # 项目配置
├── README.md                      # 文档
├── config/
│   └── config.yaml.example        # 配置示例
└── src/prometheus_mcp_server/
    ├── __init__.py
    ├── __main__.py                # 入口点
    ├── config.py                  # 配置模型和加载
    ├── client.py                  # Prometheus HTTP 客户端
    ├── server.py                  # MCP Server 主逻辑
    └── tools/
        └── __init__.py            # MCP 工具定义和处理
```

## 📝 License

MIT
