Skip to main content
Glama
Observium MCP Server

Observium MCP Server

by kdesch5000

Observium MCP Server

A Model Context Protocol (MCP) server that exposes Observium CE network monitoring data to LLMs like Claude, enabling natural language queries about device status, network traffic, sensor readings, alerts, and historical trends.

Features

  • Device Management: List and query monitored devices with status, uptime, and hardware info

  • Network Ports: View interface status, traffic rates, and utilization

  • Sensors: Access temperature, voltage, frequency, and other sensor data

  • Alerts: Query active and historical alerts with summaries

  • Trends: Retrieve historical metrics from RRD data (load, CPU, memory)

  • ✨ NEW (0.2.0) — HTTP service mode: run the server on the Observium host as a systemd service speaking MCP streamable HTTP, so clients connect by URL. No SSH tunnel, no exposed database port, RRD files read from local disk. Bearer-token auth plus an open /health endpoint.

Related MCP server: OpManager MCP Server

How it fits together

MCP client (Claude Code, any machine on your tailnet/LAN)
   │  MCP streamable HTTP  +  Authorization: Bearer <token>
   ▼
Observium host
   ├─ tailscale serve :8765  ──►  observium-mcp on 127.0.0.1:18765  (systemd)
   ├─ MariaDB via unix socket, read-only account (SELECT on observium.*)
   └─ /opt/observium/rrd read locally with the rrdtool CLI

The server also still speaks stdio for local use (a client on the Observium host itself, or development).

Requirements

  • Observium CE with MySQL/MariaDB

  • rrdtool CLI on the Observium host (apt install rrdtool)

  • For the service install: Linux with systemd, tailscale, curl, openssl, rsync

  • Python 3.10+ (the installer fetches its own pinned, uv-managed Python 3.13 — the OS Python is not used)

  • mcp SDK 1.x (>=1.26,<2). 2.x removed the low-level decorator API this server uses.

On the Observium host:

git clone https://github.com/kdesch5000/observium-mcp.git
cd observium-mcp
sudo ./deploy/install.sh

deploy/install.sh is idempotent (re-run it to upgrade). It:

  1. creates a observium-mcp system user (no shell, no home);

  2. installs a pinned, checksum-verified uv and a uv-managed Python under /opt/observium-mcp — so an OS release upgrade that replaces /usr/bin/python3 can't break the venv;

  3. copies the app to /opt/observium-mcp/app and builds /opt/observium-mcp/venv;

  4. on first run, writes /etc/observium-mcp/observium-mcp.env (mode 0640) with a random bearer token and DB password, and creates the read-only MariaDB account observium_mcp@localhost;

  5. installs and starts observium-mcp.service (sandboxed: ProtectSystem=strict, no capabilities, loopback + unix socket only) and checks /health;

  6. runs tailscale serve --bg --http=8765 http://127.0.0.1:18765, publishing it to the tailnet only.

Overrides: OBSERVIUM_MCP_PORT, OBSERVIUM_MCP_TS_PORT, OBSERVIUM_DB_SOCKET, OBSERVIUM_RRD_PATH in the environment of install.sh.

Traffic between tailnet nodes is WireGuard-encrypted, so plain HTTP inside the tailnet is fine. If you enable HTTPS certificates for your tailnet you can use tailscale serve --https=443 instead.

Register the client (Claude Code)

TOKEN=$(ssh observium-host "sudo sed -n 's/^OBSERVIUM_MCP_TOKEN=//p' /etc/observium-mcp/observium-mcp.env")
claude mcp add --scope user --transport http observium \
  http://observium-host.your-tailnet.ts.net:8765/mcp \
  --header "Authorization: Bearer $TOKEN"
unset TOKEN
claude mcp list   # observium: ... (HTTP) - ✔ Connected

Operating it

systemctl status observium-mcp
journalctl -u observium-mcp -f
curl http://127.0.0.1:18765/health        # {"status":"ok","database":true}; 503 if DB unreachable
sudo tailscale serve status

Rotate the token: edit OBSERVIUM_MCP_TOKEN in the env file, systemctl restart observium-mcp, re-run claude mcp add on each client.

Configuration reference

Variable

Default

Purpose

OBSERVIUM_MCP_TRANSPORT

stdio

stdio or http (also --transport)

OBSERVIUM_MCP_HOST

127.0.0.1

HTTP bind address (also --host)

OBSERVIUM_MCP_PORT

18765

HTTP port (also --port)

OBSERVIUM_MCP_TOKEN

—

Required for http, ≥32 chars (openssl rand -hex 32)

OBSERVIUM_MCP_ALLOWED_HOSTS

(off)

Comma list of accepted Host headers on /mcp (DNS-rebinding protection); host:* wildcards ports

OBSERVIUM_DB_SOCKET

—

MariaDB unix socket; when set, host/port are ignored

OBSERVIUM_DB_HOST / _PORT

localhost / 3306

TCP connection (if no socket)

OBSERVIUM_DB_NAME / _USER / _PASS

observium / observium / —

Credentials

OBSERVIUM_DB_CONNECT_TIMEOUT

5

Seconds

OBSERVIUM_RRD_PATH

/opt/observium/rrd

RRD tree (local disk)

For stdio/dev use, values can also come from a .env in the project root (see config.example.env). Real environment variables win over .env.

Local / development use (stdio)

uv venv --python 3.13 .venv
uv pip install --python .venv -e '.[dev]'
cp config.example.env .env      # edit
.venv/bin/observium-mcp          # stdio
.venv/bin/observium-mcp --transport http --port 18765   # needs OBSERVIUM_MCP_TOKEN

Testing

uv pip install --python .venv -e '.[dev]'    # or: pip install -r requirements-dev.txt
.venv/bin/pytest tests/

No database, network, or rrdtool needed: the DB layer and subprocess are mocked.

  • tests/test_unit.py — DB config (socket vs TCP), health check, RRD parsing, local-only rrdtool invocation, token validation, bearer auth (missing / wrong / wrong scheme / prefix-match), /health 200/503, CLI/env transport selection.

  • tests/test_e2e.py — a real uvicorn server on a random loopback port driven by the real MCP streamable-HTTP client (initialize → list_tools → call_tool with mocked rows), 401 without a token, /health over a socket, and the stdio transport as a subprocess (tool errors cleanly when the DB is unreachable).

Available Tools

Tool

Description

get_observium_capabilities

Summary of what's monitored

list_devices

List all monitored devices with status

get_device

Get detailed info for a specific device

list_ports

List network interfaces for a device

get_port_traffic

Get traffic stats for a specific port

list_sensors

List sensor readings (temp, voltage, etc.)

list_alerts

List active or historical alerts

get_alert_summary

Get alert count summary

get_trends

Get historical metric data

list_available_metrics

List available RRD metrics for a device

See docs/TOOLS.md for parameters.

Example Queries

  • "What devices are currently down?"

  • "Show me the temperature sensors on the main switch"

  • "What's the CPU load trend for the firewall over the past week?"

  • "Are there any active alerts?"

  • "Which ports on the core switch have errors?"

Security Considerations

  • The database is never exposed on the network; the service uses the local unix socket.

  • Dedicated read-only DB account (SELECT on observium.* only), password generated at install.

  • /mcp requires a bearer token (constant-time comparison); only /health is open, and it reveals only whether the DB is reachable.

  • The service binds to loopback; tailscale serve is the only path in, limited to tailnet devices.

  • RRD access is read-only rrdtool fetch/info with argument lists (no shell).

  • Secrets live in /etc/observium-mcp/observium-mcp.env (root:observium-mcp 0640) and the client's MCP config; .env is gitignored.

Troubleshooting

  • claude mcp list shows "Failed to connect": curl http://<host>:8765/health from the client. No answer → check tailscale serve status and that the client is on the tailnet. 401 on /mcp → token mismatch. 503 from /health → MariaDB down or the DB account/password is out of sync (re-run install.sh, which re-syncs the password from the env file).

  • 421 Misdirected Request / invalid Host: the client's hostname isn't in OBSERVIUM_MCP_ALLOWED_HOSTS.

  • Trend tools fail: check OBSERVIUM_RRD_PATH and that rrdtool is installed on the host.

  • AttributeError: 'Server' object has no attribute 'list_tools': mcp 2.x got installed; pin mcp<2.

Upgrading from 0.1.x

0.1.x ran on the client and reached Observium through an SSH tunnel (start-tunnel.sh) plus per-query SSH for RRD files. Both are gone: OBSERVIUM_RRD_SSH_* settings are ignored, and start-tunnel.sh is deleted. Install the service on the Observium host and re-register clients with --transport http.

License

MIT License - see LICENSE for details.

Available Tools

10 tools
get_alert_summaryA

Get a summary of current alert status.

Returns aggregated alert counts by type, entity, and device. Use for quick health overview before drilling into specific alerts.

RETURNS:

  • total_active: Count of currently active alerts

  • total_recovered: Count of recovered alerts (last 7 days)

  • by_entity_type: Breakdown by device/port/sensor

  • by_device: Top devices with most alerts

  • recent_alerts: Last few alerts raised

EXAMPLE QUESTIONS:

  • "How many active alerts are there?"

  • "Which device has the most alerts?"

  • "Give me an alert overview"

  • "What's the current alert situation?"

NEXT STEPS: Use list_alerts for details on specific alerts

Inputs: no named parameters.

get_deviceA

Get detailed information about a specific device.

Returns comprehensive device details including hardware specs, software version, location, uptime, and counts of associated ports, sensors, and alerts.

RETURNS:

  • device_id, hostname, sysName, IP address

  • os, os_version, hardware model, serial number

  • uptime (formatted), last_polled, last_rebooted

  • location, contact information

  • port_count: Number of network interfaces

  • sensor_count: Number of sensors (temp, voltage, etc.)

  • active_alert_count: Current alerts on this device

EXAMPLE QUESTIONS:

  • "Tell me about the firewall"

  • "What's the uptime of server1.example.com?"

  • "Show details for device 16"

  • "How many ports does the switch have?"

NEXT STEPS: Use list_ports, list_sensors, or list_alerts with this device

Inputs: hostname, device_id.

get_observium_capabilitiesA

Discover what data is available in this Observium instance.

CALL THIS FIRST to understand what devices, sensors, and metrics exist before making specific queries. Returns summary counts and available data types.

RETURNS:

  • device_count: Total monitored devices

  • devices_by_os: Breakdown by operating system

  • devices_by_status: Count of up/down/disabled devices

  • sensor_classes: Available sensor types (temperature, voltage, etc.)

  • alert_summary: Active and recovered alert counts

  • available_trend_metrics: What historical data can be queried

EXAMPLE QUESTIONS:

  • "What does Observium monitor?"

  • "How many devices are being tracked?"

  • "What types of sensors are available?"

Inputs: no named parameters.

get_port_trafficA

Get detailed traffic statistics for a specific network port.

Returns current bandwidth rates and historical statistics including peak and average utilization. Essential for capacity planning and troubleshooting.

RETURNS:

  • port_id, hostname, name, alias, speed

  • admin_status, oper_status

  • current:

    • in_rate_bps, out_rate_bps: Current traffic rate in bits/sec

    • in_utilization_pct, out_utilization_pct: Current % of port capacity

    • total_in_octets, total_out_octets: Lifetime byte counters

  • historical (when RRD data available):

    • period: Time range analyzed

    • statistics.in: peak_bps, peak_mbps, avg_bps, avg_mbps, peak_utilization_pct

    • statistics.out: peak_bps, peak_mbps, avg_bps, avg_mbps, peak_utilization_pct

PERIODS: 1h (hour), 6h (6 hours), 1d (day), 1w (week), 1m (month)

EXAMPLE QUESTIONS:

  • "What's the current bandwidth on port 211?"

  • "What was peak utilization on the Internet port this week?"

  • "Show traffic trends for the uplink over the past month"

  • "Is the WAN link congested?"

TIP: Use list_ports first to find the port_id, or specify device_hostname + port_name

Inputs: period, port_id, port_name, device_hostname.

list_alertsA

List alerts from Observium with status and details.

Returns active or historical alerts including device down, port down, and sensor threshold violations. Use for troubleshooting and monitoring.

RETURNS: Array of alerts with:

  • alert_id: Unique identifier

  • hostname: Affected device

  • alert_name: Type of alert

  • entity_type: What triggered it (device, port, sensor)

  • entity_name: Specific entity affected

  • status: active or recovered

  • timestamp: When alert was raised

  • duration: How long alert has been active

ALERT TYPES:

  • Device alerts: Device down, device rebooted

  • Port alerts: Port down, port errors, port utilization

  • Sensor alerts: Temperature high, voltage out of range

EXAMPLE QUESTIONS:

  • "Are there any active alerts?"

  • "What alerts fired this week?"

  • "Show me all recovered alerts"

  • "What's alerting on the switch?"

NEXT STEPS: Use get_alert_summary for overview, or investigate with get_device/list_sensors

Inputs: limit, status, hostname, device_id.

list_available_metricsA

List available metrics (RRD files) for a device.

Shows what historical trend data can be queried for a specific device. RRD files are created automatically based on what Observium discovers via SNMP.

RETURNS:

  • hostname: Device queried

  • total_rrd_files: Count of available metrics

  • categories: Metrics grouped by type

    • system: la.rrd (load), processor (cpu), mempool (memory), uptime

    • network: port-*.rrd (interface traffic)

    • sensors: sensor-*.rrd (environmental data)

    • performance: poller stats

EXAMPLE QUESTIONS:

  • "What metrics are available for the server?"

  • "Can I get CPU data for this device?"

  • "What historical data exists for the switch?"

NEXT STEPS: Use get_trends with discovered metrics, or get_port_traffic for network data

Inputs: hostname, device_id.

list_devicesA

List all devices monitored by Observium with their current status.

Returns hostname, IP, OS, hardware model, uptime, and polling status for each device. Use this to discover what devices exist before drilling down with other tools.

RETURNS: Array of devices with:

  • device_id: Unique identifier (use with other tools)

  • hostname: Device hostname or IP

  • os: Operating system (linux, ios, junos, etc.)

  • hardware: Hardware model

  • uptime: How long since last reboot

  • status: Current state (up, down, disabled)

  • last_polled: When Observium last collected data

EXAMPLE QUESTIONS:

  • "What devices are monitored?"

  • "Show me all Linux servers"

  • "What devices are currently down?"

  • "List all network switches"

NEXT STEPS: Use device_id or hostname with get_device, list_ports, list_sensors, get_trends

Inputs: os_filter, status_filter.

list_portsA

List network ports/interfaces for a device.

Returns all network interfaces with their operational state, speed, and basic traffic counters. Essential for finding port_ids before querying traffic details.

RETURNS: Array of ports with:

  • port_id: Unique identifier (use with get_port_traffic)

  • name: Interface name (e.g., 'GigabitEthernet0/1', 'eth0')

  • description: Interface description from device

  • alias: Configured port description/label

  • speed: Port speed (e.g., '1 Gbps', '10 Gbps')

  • admin_status: Administrative state (up/down)

  • oper_status: Operational state (up/down)

  • in_octets, out_octets: Total bytes transferred

  • in_errors, out_errors: Error counters

EXAMPLE QUESTIONS:

  • "What ports are on the switch?"

  • "Show me all active interfaces on the router"

  • "Which ports have errors?"

  • "List ports that are admin up but operationally down"

NEXT STEPS: Use port_id with get_port_traffic for detailed bandwidth analysis

Inputs: hostname, device_id, oper_status, admin_status.

list_sensorsA

List sensors (temperature, voltage, frequency, etc.) across devices.

Returns current sensor readings with status relative to configured thresholds. Sensors are auto-discovered via SNMP from devices that support environmental monitoring.

RETURNS: Array of sensors with:

  • sensor_id: Unique identifier

  • hostname: Device the sensor belongs to

  • sensor_class: Type (temperature, voltage, frequency, fanspeed, power, humidity)

  • sensor_descr: Sensor name/description

  • value: Current reading with unit

  • status: normal, warning, or critical (based on thresholds)

  • limits: Configured thresholds (critical_high, warning_high, warning_low, critical_low)

SENSOR CLASSES:

  • temperature: CPU, chassis, ambient temps (°C)

  • voltage: Power supply, rail voltages (V)

  • frequency: CPU, clock frequencies (Hz/MHz)

  • fanspeed: Cooling fan RPM

  • power: Power consumption (W)

  • humidity: Environmental humidity (%)

EXAMPLE QUESTIONS:

  • "What's the hottest sensor?"

  • "Show all temperature readings"

  • "Are any sensors in warning or critical state?"

  • "What's the CPU temperature on the server?"

TIP: Filter by sensor_class to focus on specific sensor types

Inputs: hostname, device_id, sensor_class.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool maps to a distinct resource or action: capabilities, device list/detail, port list/traffic, sensors, alerts list/summary, trends, and per-device metrics. Summary-versus-detail pairs are explicitly differentiated with examples and NEXT STEPS, so selection is clear.

    Naming Consistency5/5

    All tools use snake_case with a predictable get_/list_ verb_noun pattern, making the set easy to scan and reason about. The only minor outlier is get_observium_capabilities including the product name, but it still follows the convention.

    Tool Count5/5

    Ten tools is well-scoped for a read-only monitoring server, covering discovery, device/port/sensor/alert inspection, and historical trends. Each tool has a clear role and no obvious redundant entries.

    Completeness4/5

    The surface covers core Observium read-only workflows: discovery, devices, ports, traffic, sensors, alerts, and device-level trends. Minor gaps remain, such as list_available_metrics potentially exposing sensor RRDs while get_trends only supports load/cpu/memory/uptime, leaving sensor historical queries as a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables users to monitor and query Zabbix infrastructure through natural language by providing access to current problems, active triggers, and system health status via the Zabbix API.
      -
    • A
      license
      C
      quality
      D
      maintenance
      Enables AI assistants to interact with ManageEngine OpManager for network monitoring and IT operations management. Provides credential-less access to 85+ API endpoints for managing devices, alarms, discovery, dashboards, and reports through natural language.
      85
      2
      MIT
    • A
      license
      C
      quality
      A
      maintenance
      Enables complete management of CheckMK monitoring environments through natural language, including live monitoring, downtime scheduling, problem management, and configuration.
      115
      60 PyPI
      23
      GPL 3.0
    • A
      license
      A
      quality
      B
      maintenance
      Provides read-only access to TacticalRMM remote monitoring and management instances via the MCP protocol. It enables querying agents, clients, alerts, checks, and other RMM data through natural language.
      22
      4 npm
      AGPL 3.0