# Observium MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes [Observium CE](https://www.observium.org/) 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)

## Requirements

- Python 3.10+ (required by MCP SDK)
- Observium CE installation with MySQL/MariaDB database access
- Access to Observium's RRD data directory (for trend data)
- `rrdtool` and `librrd-dev` packages (for RRD data access)

## Installation

### 1. Clone the repository

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

### 2. Create a virtual environment

```bash
python3 -m venv venv
source venv/bin/activate
```

### 3. Install dependencies

```bash
pip install -r requirements.txt
```

### 4. Configure environment

Copy the example configuration and edit with your Observium database credentials:

```bash
cp config.example.env .env
```

Edit `.env` with your settings:

```bash
# Database connection (use SSH tunnel if remote)
OBSERVIUM_DB_HOST=localhost
OBSERVIUM_DB_PORT=3306
OBSERVIUM_DB_NAME=observium
OBSERVIUM_DB_USER=observium
OBSERVIUM_DB_PASS=your_database_password

# RRD data path (on the Observium server)
OBSERVIUM_RRD_PATH=/opt/observium/rrd

# Optional: SSH configuration for remote RRD access
# If MCP server runs on a different machine than Observium,
# set these to enable SSH-based RRD file access for trend data
# OBSERVIUM_RRD_SSH_HOST=observium.example.com
# OBSERVIUM_RRD_SSH_USER=pi
# OBSERVIUM_RRD_SSH_PORT=22
```

## Usage

### With Claude Code

Add to your Claude Code MCP configuration (`~/.claude/claude_code_config.json`):

```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"
      }
    }
  }
}
```

### With Claude Desktop

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```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"
      }
    }
  }
}
```

### Standalone

```bash
cd src
python -m observium_mcp.server
```

## Available Tools

| Tool | Description |
|------|-------------|
| `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 |

## Example Queries

Once connected, you can ask Claude questions like:

- "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?"
- "What's the uptime of all my Linux servers?"

## Remote Access

If your Observium instance is on a remote server, you have several options:

### Option 1: SSH Tunnel

```bash
# Create SSH tunnel to forward MySQL port
ssh -L 3306:localhost:3306 user@observium-server

# Then configure .env with localhost
OBSERVIUM_DB_HOST=localhost
```

### Option 2: Install on Observium Server

Install the MCP server directly on the Observium host and configure Claude to connect via SSH.

### Option 3: Network Access

If MySQL is accessible on the network (not recommended for security):

```bash
OBSERVIUM_DB_HOST=observium.example.com
```

## Security Considerations

- Database credentials are stored in `.env` which is gitignored
- The server only performs SELECT queries (read-only)
- Consider using a read-only MySQL user for additional safety
- RRD access is read-only via `rrdtool fetch`

## Creating a Read-Only Database User

For additional security, create a dedicated read-only MySQL user:

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

## Troubleshooting

### Connection refused

- Verify MySQL is running and accessible
- Check database credentials in `.env`
- Ensure the MySQL user has SELECT permissions

### No RRD data / Trend tools failing

- Verify `OBSERVIUM_RRD_PATH` points to the correct directory on the Observium server
- If running MCP on a different machine, configure SSH access:
  - Set `OBSERVIUM_RRD_SSH_HOST` to the Observium server hostname
  - Set `OBSERVIUM_RRD_SSH_USER` to a user with SSH access
  - Ensure SSH key-based authentication is configured
- Ensure `rrdtool` is installed on the Observium server (for remote) or locally
- Check file permissions on the RRD directory

### Module not found

Make sure you're running from the `src` directory or have installed the package:

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

## Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Acknowledgments

- [Observium](https://www.observium.org/) - Network monitoring platform
- [Model Context Protocol](https://modelcontextprotocol.io/) - The MCP specification
- [Anthropic](https://www.anthropic.com/) - Claude and MCP development