Observium MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Observium MCP Server What devices are currently down?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
/healthendpoint.
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 CLIThe server also still speaks stdio for local use (a client on the Observium host itself, or development).
Requirements
Observium CE with MySQL/MariaDB
rrdtoolCLI on the Observium host (apt install rrdtool)For the service install: Linux with systemd,
tailscale,curl,openssl,rsyncPython 3.10+ (the installer fetches its own pinned, uv-managed Python 3.13 — the OS Python is not used)
mcpSDK 1.x (>=1.26,<2). 2.x removed the low-level decorator API this server uses.
Install as a service (recommended)
On the Observium host:
git clone https://github.com/kdesch5000/observium-mcp.git
cd observium-mcp
sudo ./deploy/install.shdeploy/install.sh is idempotent (re-run it to upgrade). It:
creates a
observium-mcpsystem user (no shell, no home);installs a pinned, checksum-verified
uvand a uv-managed Python under/opt/observium-mcp— so an OS release upgrade that replaces/usr/bin/python3can't break the venv;copies the app to
/opt/observium-mcp/appand builds/opt/observium-mcp/venv;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 accountobservium_mcp@localhost;installs and starts
observium-mcp.service(sandboxed:ProtectSystem=strict, no capabilities, loopback + unix socket only) and checks/health;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) - ✔ ConnectedOperating 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 statusRotate 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 |
|
|
|
|
| HTTP bind address (also |
|
| HTTP port (also |
| — | Required for http, ≥32 chars ( |
| (off) | Comma list of accepted |
| — | MariaDB unix socket; when set, host/port are ignored |
|
| TCP connection (if no socket) |
|
| Credentials |
|
| Seconds |
|
| 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_TOKENTesting
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),/health200/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,/healthover a socket, and the stdio transport as a subprocess (tool errors cleanly when the DB is unreachable).
Available Tools
Tool | Description |
| Summary of what's monitored |
| List all monitored devices with status |
| Get detailed info for a specific device |
| List network interfaces for a device |
| Get traffic stats for a specific port |
| List sensor readings (temp, voltage, etc.) |
| List active or historical alerts |
| Get alert count summary |
| Get historical metric data |
| 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 (
SELECTonobservium.*only), password generated at install./mcprequires a bearer token (constant-time comparison); only/healthis open, and it reveals only whether the DB is reachable.The service binds to loopback;
tailscale serveis the only path in, limited to tailnet devices.RRD access is read-only
rrdtool fetch/infowith argument lists (no shell).Secrets live in
/etc/observium-mcp/observium-mcp.env(root:observium-mcp 0640) and the client's MCP config;.envis gitignored.
Troubleshooting
claude mcp listshows "Failed to connect":curl http://<host>:8765/healthfrom the client. No answer → checktailscale serve statusand that the client is on the tailnet.401on/mcp→ token mismatch.503from/health→ MariaDB down or the DB account/password is out of sync (re-runinstall.sh, which re-syncs the password from the env file).421 Misdirected Request/ invalid Host: the client's hostname isn't inOBSERVIUM_MCP_ALLOWED_HOSTS.Trend tools fail: check
OBSERVIUM_RRD_PATHand thatrrdtoolis installed on the host.AttributeError: 'Server' object has no attribute 'list_tools':mcp2.x got installed; pinmcp<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 toolsget_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.
get_trendsA
Get historical trend data for device metrics.
Returns time-series data for CPU, memory, load, or uptime with statistics. Data comes from RRD files updated every 5 minutes by Observium polling.
RETURNS:
hostname, metric, period
datasources: What values are in the data (e.g., load1, load5, load15)
data_points: Number of samples
statistics: For each datasource - min, max, avg, current
data: Array of timestamped values (last 100 points)
METRICS:
load: System load average (load1, load5, load15)
cpu: CPU utilization percentage
memory: Memory usage percentage or bytes
uptime: System uptime in seconds
PERIODS: 1h, 6h, 1d (default), 1w, 1m
EXAMPLE QUESTIONS:
"What's the CPU trend on the server this week?"
"Show load average history for the firewall"
"What was peak memory usage this month?"
"How has uptime looked over the past week?"
TIP: Use list_available_metrics first to see what data exists for a device
Inputs: hostname (required), metric, period, device_id.
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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Manage uptime monitors and incidents and search logs, metrics and traces from an AI assistant.
Ask about your IoT sensors, devices, anomalies and automations, switch outputs and log values.
Query, explore, and manage your databases through natural conversation.
Read-only Linux server and Docker monitoring for AI assistants: CPU, memory, disk, network.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseCqualityDmaintenanceEnables 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.852MIT
- AlicenseCqualityAmaintenanceEnables complete management of CheckMK monitoring environments through natural language, including live monitoring, downtime scheduling, problem management, and configuration.11560 PyPI23GPL 3.0
- AlicenseAqualityBmaintenanceProvides 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.224 npmAGPL 3.0