📊 Zabbix Dashboard Automation - Proxmox Monitoring

Un servidor MCP (Model Context Protocol) para automatización de dashboards de Zabbix con monitoreo completo de Proxmox.

🎯 Estado del Proyecto

✅ Dashboard Proxmox Completamente Funcional
✅ 6 Widgets Operativos
✅ 384 Items Monitoreados
✅ Sin Errores de Permisos
✅ Autenticación Moderna (Zabbix 7.4+)

🔗 Integración MCP Completada ✅

Servidor MCP: Funcional con herramientas especializadas
Herramientas Proxmox: 4 nuevas herramientas integradas
Modo: Read-only para seguridad
Estado: Ejecutándose correctamente

🚀 Archivos Principales

Scripts de Automatización

crear-dashboard-stdlib.py - Script principal para crear dashboard inicial
crear-dashboard-dual-proxmox.py - Script para dashboards duales
mejorar-dashboard.py - Script para mejorar dashboard existente
agregar-widgets-proxmox.py - Script para agregar widgets completos
auto-configurar-svg-widgets.py - ⭐ NUEVO: Auto-configurador de widgets SVG
test-mcp-proxmox.py - Script de prueba para funcionalidades MCP

Documentación

DASHBOARD-PROXMOX-COMPLETO.md - Guía completa de implementación
GUIA-AUTOMATIZACION-DASHBOARDS.md - Guía técnica de automatización
LOGICA-CONFIGURACION-SVG-WIDGETS.md - ⭐ NUEVO: Lógica para resolver errores SVG
WIDGET-CONFIGURATION-GUIDE.md - Guía de configuración de widgets

🔧 Configuración del Servidor

Servidor Zabbix: 137.184.54.73
Versión: Zabbix 7.4.1
API: http://137.184.54.73/api_jsonrpc.php
Usuario: Admin
Contraseña: zabbix

📊 Dashboard Implementado

Widgets Funcionales

📋 Problemas del Sistema - Alertas activas
🔌 Estado de API - Monitoreo del servicio
🏢 Estado del Cluster - Información del cluster
📊 Información del Sistema - Estadísticas generales
📈 Gráfico de CPU - Uso en tiempo real
💾 Gráfico de Memoria - Uso en tiempo real

Acceso al Dashboard

🌐 URL: http://137.184.54.73
📊 Ruta: Monitoring → Dashboards → Proxmox Monitoring

🚀 Uso Rápido

Crear Dashboard Completo

python3 crear-dashboard-stdlib.py

Mejorar Dashboard Existente

python3 mejorar-dashboard.py

Agregar Widgets Adicionales

python3 agregar-widgets-proxmox.py

⭐ Auto-Configurar Widgets SVG (NUEVO)

# Resolver automáticamente errores de configuración SVG
python3 auto-configurar-svg-widgets.py http://localhost/zabbix Admin zabbix 404

Errores resueltos:

❌ "Invalid parameter 'Data set1/hosts': cannot be empty"
❌ "Invalid parameter 'Data set1/items': cannot be empty"
✅ Configuración automática de host patterns e item patterns

📋 Items Monitoreados

Total: 384 items
├── CPU: 34 items
├── Memoria: 60 items
├── Disco: 146 items
├── API: 1 item
├── Cluster: 3 items
├── LXC: 115 items
└── VMs: 25 items

🔍 Resolución de Problemas

Problemas de Permisos

✅ Resuelto: Error "No permissions to referred object"
✅ Implementado: Autenticación moderna con Authorization: Bearer
✅ Validado: Verificación de items antes de crear widgets

Autenticación

✅ Zabbix 7.4+: Usar Authorization: Bearer header
✅ Fallback: Soporte para método legacy si es necesario
✅ Seguridad: Logout automático al finalizar

🎉 Resultado Final

El dashboard de Proxmox Monitoring está 100% operativo con:

Monitoreo en tiempo real de CPU y memoria
Estado del cluster y API
Problemas activos del sistema
Información detallada del sistema

📚 Documentación Adicional

Para información técnica detallada, consulta:

DASHBOARD-PROXMOX-COMPLETO.md - Implementación completa
GUIA-AUTOMATIZACION-DASHBOARDS.md - Guía técnica

Proyecto completado exitosamente - Dashboard Proxmox v1.0

Features

🏠 Host Management

host_get - Retrieve hosts with advanced filtering
host_create - Create new hosts with interfaces and templates
host_update - Update existing host configurations
host_delete - Remove hosts from monitoring

👥 Host Group Management

hostgroup_get - Retrieve host groups
hostgroup_create - Create new host groups
hostgroup_update - Modify existing host groups
hostgroup_delete - Remove host groups

📊 Item Management

item_get - Retrieve monitoring items with filtering
item_create - Create new monitoring items
item_update - Update existing items
item_delete - Remove monitoring items

⚠️ Trigger Management

trigger_get - Retrieve triggers and alerts
trigger_create - Create new triggers
trigger_update - Modify existing triggers
trigger_delete - Remove triggers

📋 Template Management

template_get - Retrieve monitoring templates
template_create - Create new templates
template_update - Update existing templates
template_delete - Remove templates

🚨 Problem & Event Management

problem_get - Retrieve current problems and issues
event_get - Get historical events
event_acknowledge - Acknowledge events and problems

📈 Data Retrieval

history_get - Access historical monitoring data
trend_get - Retrieve trend data and statistics

👤 User Management

user_get - Retrieve user accounts
user_create - Create new users
user_update - Update user information
user_delete - Remove user accounts

🔧 Maintenance Management

maintenance_get - Retrieve maintenance periods
maintenance_create - Schedule maintenance windows
maintenance_update - Modify maintenance periods
maintenance_delete - Remove maintenance schedules

📊 Additional Features

graph_get - Retrieve graph configurations
discoveryrule_get - Get discovery rules
itemprototype_get - Retrieve item prototypes
configuration_export - Export Zabbix configurations
configuration_import - Import configurations
apiinfo_version - Get API version information

🚀 Herramientas Especializadas para Proxmox

mcp_zabbix_proxmox_hosts_analyze - Analizar hosts Proxmox y categorizar items
mcp_zabbix_proxmox_dashboard_create_single - Crear dashboard para un nodo Proxmox
mcp_zabbix_proxmox_dashboard_create_dual - Crear dashboard dual para dos nodos Proxmox
mcp_zabbix_proxmox_dashboard_add_widgets - Agregar widgets específicos a dashboards existentes

🔧 Uso de Herramientas MCP Proxmox

Analizar Hosts Proxmox

{
  "tool": "mcp_zabbix_proxmox_hosts_analyze",
  "args": {
    "categorize_items": true,
    "hostname_filter": "proxmox"
  }
}

Crear Dashboard Individual

{
  "tool": "mcp_zabbix_proxmox_dashboard_create_single", 
  "args": {
    "hostname": "proxmox",
    "dashboard_name": "Proxmox Monitor"
  }
}

Crear Dashboard Dual

{
  "tool": "mcp_zabbix_proxmox_dashboard_create_dual",
  "args": {
    "hostname1": "proxmox",
    "hostname2": "serverhome", 
    "dashboard_name": "Proxmox Dual Monitor"
  }
}

Agregar Widgets

{
  "tool": "mcp_zabbix_proxmox_dashboard_add_widgets",
  "args": {
    "dashboard_id": "402",
    "hostname": "proxmox",
    "widget_types": ["cpu_graph", "memory_graph", "disk_graph"]
  }
}

Installation

npm install -g @thelord/zabbix-mcp-server

Prerequisites

Node.js 18 or higher
npm (comes with Node.js)
Conda (recommended for environment management)
Access to a Zabbix server with API enabled

Quick Start

Clone the repository:

git clone https://github.com/mpeirone/zabbix-mcp-server.git
cd zabbix-mcp-server

Set up the environment:

# Create conda environment
conda create -n zabbix-mcp-server -c conda-forge nodejs -y

# Activate environment (or use the included script)
source activate.sh

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Configure environment variables:

cp .env.example .env
# Edit .env with your Zabbix server details

Test the installation:
```
npm test
```

Configuration

Standard MCP Server (stdio)

Create a .env file in your project directory:

ZABBIX_URL=http://your-zabbix-server/zabbix
ZABBIX_USER=your-username
ZABBIX_PASSWORD=your-password
READ_ONLY=false

SSE Server (Server-Sent Events)

For remote access and real-time communication, use the SSE server. Create a .env file:

# Zabbix API Configuration
ZABBIX_URL=http://your-zabbix-server/zabbix
ZABBIX_USER=your-username
ZABBIX_PASSWORD=your-password

# SSE Server Configuration
PORT=3000

# CORS Configuration (comma-separated origins)
ALLOWED_ORIGINS=http://localhost:3001,http://localhost:8080

# Security
READ_ONLY=false

Required Environment Variables

ZABBIX_URL - Your Zabbix server API endpoint (e.g., https://zabbix.example.com)

Authentication (choose one method)

Method 1: API Token (Recommended)

ZABBIX_TOKEN - Your Zabbix API token

Method 2: Username/Password

ZABBIX_USER - Your Zabbix username
ZABBIX_PASSWORD - Your Zabbix password

Optional Configuration

READ_ONLY - Set to true, 1, or yes to enable read-only mode (only GET operations allowed)

Usage

Standard MCP Server (stdio)

As a standalone server

npx @thelord/zabbix-mcp-server

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "zabbix": {
      "command": "npx",
      "args": ["@thelord/zabbix-mcp-server"]
    }
  }
}

SSE Server (Server-Sent Events)

Start the SSE server

# Development mode
npm run dev:sse

# Production mode
npm run build
npm run start:sse

Configure MCP clients for SSE

VS Code with MCP extension:

{
  "mcpServers": {
    "zabbix-sse": {
      "transport": {
        "type": "sse",
        "url": "http://localhost:3001/sse",
        "postUrl": "http://localhost:3001/message"
      }
    }
  }
}

Cursor IDE:

{
  "mcpServers": {
    "zabbix-sse": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "postUrl": "http://localhost:3001/message"
    }
  }
}

Trae AI:

{
  "mcpServers": {
    "zabbix-sse": {
      "transport": "sse",
      "url": "http://localhost:3001/sse",
      "env": {
        "ZABBIX_URL": "http://137.184.54.73/api_jsonrpc.php",
        "ZABBIX_USERNAME": "Admin",
        "ZABBIX_PASSWORD": "zabbix"
      }
    }
  }
}

Neovim with MCPHub.nvim:

require('mcphub').setup({
  servers = {
    ['zabbix-sse'] = {
      transport = 'sse',
      url = 'http://localhost:3001/sse',
      post_url = 'http://localhost:3001/message'
    }
  }
})

Running the Server

Production mode:

npm start

Development mode (with auto-reload):

npm run dev

Direct execution:

node dist/index.js

Testing

Run test suite:

npm test

Available Scripts

npm run build - Compile TypeScript to JavaScript
npm start - Run the compiled server
npm run dev - Run in development mode with auto-reload
npm test - Run tests and verify configuration

Read-Only Mode

When READ_ONLY=true, the server will only expose GET operations (retrieve data) and block all create, update, and delete operations. This is useful for:

📊 Monitoring dashboards
🔍 Read-only integrations
🔒 Security-conscious environments
🛡️ Preventing accidental modifications

Example Tool Calls

Get all hosts:

host_get()

Get hosts in specific group:

host_get(groupids=["1"])

Create a new host:

host_create(
    host="server-01",
    groups=[{"groupid": "1"}],
    interfaces=[{
        "type": 1,
        "main": 1,
        "useip": 1,
        "ip": "192.168.1.100",
        "dns": "",
        "port": "10050"
    }]
)

Get recent problems:

problem_get(recent=True, limit=10)

Get history data:

history_get(
    itemids=["12345"],
    time_from=1640995200,
    limit=100
)

MCP Integration

This server is designed to work with MCP-compatible clients like Claude Desktop. See MCP_SETUP.md for detailed integration instructions.

Docker Support

Using Docker Compose

Configure environment:

cp config/.env.example .env
# Edit .env with your settings

Run with Docker Compose:
```
docker compose up -d
```

Building Docker Image

docker build -t zabbix-mcp-server .

Development

Project Structure

zabbix-mcp-server/
├── src/
│   └── zabbix_mcp_server.py    # Main server implementation
├── scripts/
│   ├── start_server.py         # Startup script with validation
│   └── test_server.py          # Test script
├── config/
│   ├── .env.example           # Environment configuration template
│   └── mcp.json               # MCP client configuration example
├── pyproject.toml             # Python project configuration
├── requirements.txt           # Dependencies
├── Dockerfile                 # Docker configuration
├── docker-compose.yml         # Docker Compose setup
├── README.md                  # This file
├── MCP_SETUP.md              # MCP integration guide
├── CONTRIBUTING.md           # Contribution guidelines
├── CHANGELOG.md              # Version history
└── LICENSE                   # MIT license

Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Running Tests

# Test server functionality
uv run python scripts/test_server.py

# Test with Docker
docker-compose exec zabbix-mcp python scripts/test_server.py

Error Handling

The server includes comprehensive error handling:

✅ Authentication errors are clearly reported
🔒 Read-only mode violations are blocked with descriptive messages
✔️ Invalid parameters are validated
🌐 Network and API errors are properly formatted
📝 Detailed logging for troubleshooting

Security Considerations

🔑 Use API tokens instead of username/password when possible
🔒 Enable read-only mode for monitoring-only use cases
🛡️ Secure your environment variables
🔐 Use HTTPS for Zabbix server connections
🔄 Regularly rotate API tokens
📁 Store configuration files securely

Troubleshooting

Common Issues

Connection Failed:

Verify ZABBIX_URL is correct and accessible
Check authentication credentials
Ensure Zabbix API is enabled

Permission Denied:

Verify user has sufficient Zabbix permissions
Check if read-only mode is enabled when trying to modify data

Tool Not Found:

Ensure all dependencies are installed: uv sync
Verify Python version compatibility (3.10+)

Debug Mode

Set environment variable for detailed logging:

export DEBUG=1
uv run python scripts/start_server.py

Dependencies

FastMCP - MCP server framework
python-zabbix-utils - Official Zabbix Python library

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Zabbix for the monitoring platform
Model Context Protocol for the integration standard
FastMCP for the server framework

Support

Made with ❤️ for the Zabbix and MCP communities

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
examples		examples
node_modules		node_modules
src		src
.DS_Store		.DS_Store
.env.example		.env.example
.env.sse.example		.env.sse.example
.gitignore		.gitignore
.npmignore		.npmignore
CLIENT_CONNECTION_GUIDE.md		CLIENT_CONNECTION_GUIDE.md
LICENSE		LICENSE
MCP_CLIENT_CONNECTIONS.md		MCP_CLIENT_CONNECTIONS.md
README.md		README.md
SSE_FIXES_SUMMARY.md		SSE_FIXES_SUMMARY.md
SSE_SERVER_FIXED.md		SSE_SERVER_FIXED.md
TRAE_IDE_SETUP.md		TRAE_IDE_SETUP.md
package-lock.json		package-lock.json
package.json		package.json
test-client.sh		test-client.sh
test-mcp-client.js		test-mcp-client.js
test-mcp-config.json		test-mcp-config.json
test-sse-connection.js		test-sse-connection.js
tsconfig.json		tsconfig.json
uv.lock		uv.lock

License

gilberth/zabbix-mcp-server

Folders and files

Latest commit

History

Repository files navigation

📊 Zabbix Dashboard Automation - Proxmox Monitoring

🎯 Estado del Proyecto

🔗 Integración MCP Completada ✅

🚀 Archivos Principales

Scripts de Automatización

Documentación

🔧 Configuración del Servidor

📊 Dashboard Implementado

Widgets Funcionales

Acceso al Dashboard

🚀 Uso Rápido

Crear Dashboard Completo

Mejorar Dashboard Existente

Agregar Widgets Adicionales

⭐ Auto-Configurar Widgets SVG (NUEVO)

📋 Items Monitoreados

🔍 Resolución de Problemas

Problemas de Permisos

Autenticación

🎉 Resultado Final

📚 Documentación Adicional

Features

🏠 Host Management

👥 Host Group Management

📊 Item Management

⚠️ Trigger Management

📋 Template Management

🚨 Problem & Event Management

📈 Data Retrieval

👤 User Management

🔧 Maintenance Management

📊 Additional Features

🚀 Herramientas Especializadas para Proxmox

🔧 Uso de Herramientas MCP Proxmox

Analizar Hosts Proxmox

Crear Dashboard Individual

Crear Dashboard Dual

Agregar Widgets

Installation

Prerequisites

Quick Start

Configuration

Standard MCP Server (stdio)

SSE Server (Server-Sent Events)

Required Environment Variables

Authentication (choose one method)

Optional Configuration

Usage

Standard MCP Server (stdio)

As a standalone server

With Claude Desktop

SSE Server (Server-Sent Events)

Start the SSE server

Configure MCP clients for SSE

Running the Server

Testing

Available Scripts

Read-Only Mode

Example Tool Calls

MCP Integration

Docker Support

Using Docker Compose

Building Docker Image

Development

Project Structure

Contributing

Running Tests

Error Handling

Security Considerations

Troubleshooting

Common Issues

Debug Mode

Dependencies

License

Packages