JinDaGe - observium-mcp MCP Details

article

README

🚀 Observium MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，它将 Observium CE 网络监控数据提供给像 Claude 这样的大语言模型，支持通过自然语言查询设备状态、网络流量、传感器读数、警报和历史趋势等信息。

🚀 快速开始

本项目旨在让你能够利用大语言模型（如Claude）对Observium CE的网络监控数据进行自然语言查询。通过以下步骤，你可以快速搭建并使用此服务器。

✨ 主要特性

设备管理：列出并查询受监控设备的状态、正常运行时间和硬件信息。
网络端口：查看接口状态、流量速率和利用率。
传感器：获取温度、电压、频率及其他传感器数据。
警报：查询活动和历史警报并查看摘要。
趋势：从 RRD 数据中检索历史指标（负载、CPU、内存）。

📦 安装指南

1. 克隆仓库

git clone https://github.com/kdesch5000/observium-mcp.git
cd observium-mcp

2. 创建虚拟环境

python3 -m venv venv
source venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 配置环境

复制示例配置文件并使用你的 Observium 数据库凭证进行编辑：

cp config.example.env .env

编辑 .env 文件并设置以下内容：

# 数据库连接（如果是远程连接，请使用 SSH 隧道）
OBSERVIUM_DB_HOST=localhost
OBSERVIUM_DB_PORT=3306
OBSERVIUM_DB_NAME=observium
OBSERVIUM_DB_USER=observium
OBSERVIUM_DB_PASS=your_database_password

# RRD 数据路径（在 Observium 服务器上）
OBSERVIUM_RRD_PATH=/opt/observium/rrd

# 可选：用于远程 RRD 访问的 SSH 配置
# 如果 MCP 服务器与 Observium 运行在不同的机器上，
# 设置这些参数以启用基于 SSH 的 RRD 文件访问来获取趋势数据
# OBSERVIUM_RRD_SSH_HOST=observium.example.com
# OBSERVIUM_RRD_SSH_USER=pi
# OBSERVIUM_RRD_SSH_PORT=22

💻 使用示例

使用 Claude Code

将以下内容添加到你的 Claude Code MCP 配置文件 (~/.claude/claude_code_config.json) 中：

{
  "mcpServers": {
    "observium": {
      "command": "python",
      "args": ["-m", "observium_mcp.server"],
      "cwd": "/path/to/observium-mcp/src",
      "env": {
        "OBSERVIUM_DB_HOST": "localhost",
        "OBSERVIUM_DB_NAME": "observium",
        "OBSERVIUM_DB_USER": "observium",
        "OBSERVIUM_DB_PASS": "your_password",
        "OBSERVIUM_RRD_PATH": "/opt/observium/rrd"
      }
    }
  }
}

使用 Claude Desktop

将以下内容添加到你的 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "observium": {
      "command": "python",
      "args": ["-m", "observium_mcp.server"],
      "cwd": "/path/to/observium-mcp/src",
      "env": {
        "OBSERVIUM_DB_HOST": "your_observium_host",
        "OBSERVIUM_DB_NAME": "observium",
        "OBSERVIUM_DB_USER": "observium",
        "OBSERVIUM_DB_PASS": "your_password",
        "OBSERVIUM_RRD_PATH": "/opt/observium/rrd"
      }
    }
  }
}

独立运行

cd src
python -m observium_mcp.server

📚 详细文档

可用工具

| 工具 | 描述 | |------|-------------| | list_devices | 列出所有受监控设备及其状态 | | get_device | 获取特定设备的详细信息 | | list_ports | 列出设备的网络接口 | | get_port_traffic | 获取特定端口的流量统计信息 | | list_sensors | 列出传感器读数（温度、电压等） | | list_alerts | 列出活动或历史警报 | | get_alert_summary | 获取警报数量摘要 | | get_trends | 获取历史指标数据 | | list_available_metrics | 列出设备可用的 RRD 指标 |

示例查询

连接成功后，你可以向 Claude 提出如下问题：

"当前有哪些设备处于离线状态？"
"显示主交换机上的温度传感器信息"
"过去一周防火墙的 CPU 负载趋势如何？"
"是否有活动警报？"
"核心交换机上哪些端口有错误？"
"我所有 Linux 服务器的正常运行时间是多少？"

远程访问

如果你的 Observium 实例位于远程服务器，你有以下几种选择：

选项 1：SSH 隧道

# 创建 SSH 隧道以转发 MySQL 端口
ssh -L 3306:localhost:3306 user@observium-server

# 然后在 .env 中配置为 localhost
OBSERVIUM_DB_HOST=localhost

选项 2：在 Observium 服务器上安装

直接在 Observium 主机上安装 MCP 服务器，并配置 Claude 通过 SSH 进行连接。

选项 3：网络访问

如果 MySQL 在网络上可访问（出于安全考虑不建议）：

OBSERVIUM_DB_HOST=observium.example.com

安全考虑

数据库凭证存储在 .env 文件中，该文件已被添加到 .gitignore 中。
服务器仅执行 SELECT 查询（只读）。
为了提高安全性，考虑使用只读的 MySQL 用户。
通过 rrdtool fetch 进行的 RRD 访问是只读的。

创建只读数据库用户

为了进一步提高安全性，创建一个专用的只读 MySQL 用户：

CREATE USER 'observium_mcp'@'localhost' IDENTIFIED BY 'secure_password';
GRANT SELECT ON observium.* TO 'observium_mcp'@'localhost';
FLUSH PRIVILEGES;

故障排除

连接被拒绝

验证 MySQL 是否正在运行且可访问。
检查 .env 文件中的数据库凭证。
确保 MySQL 用户具有 SELECT 权限。

没有 RRD 数据 / 趋势工具失败

验证 OBSERVIUM_RRD_PATH 是否指向 Observium 服务器上的正确目录。
如果 MCP 在不同的机器上运行，配置 SSH 访问：
- 设置 OBSERVIUM_RRD_SSH_HOST 为 Observium 服务器的主机名。
- 设置 OBSERVIUM_RRD_SSH_USER 为具有 SSH 访问权限的用户。
- 确保已配置基于 SSH 密钥的认证。
确保 rrdtool 已安装在 Observium 服务器（远程）或本地。
检查 RRD 目录的文件权限。

模块未找到

确保你从 src 目录运行或已安装该包：

cd /path/to/observium-mcp/src
python -m observium_mcp.server

📄 许可证

本项目采用 MIT 许可证，详情请见 LICENSE。

致谢

Observium - 网络监控平台
模型上下文协议 - MCP 规范
Anthropic - Claude 和 MCP 开发

observium-mcp