Zabbix MCP Server

🚀 Zabbix MCP Server

A comprehensive Model Context Protocol (MCP) server for Zabbix integration using FastMCP and python - zabbix - utils, providing complete access to Zabbix API functionality through MCP - compatible tools.

🚀 Quick Start

This Zabbix MCP Server is a powerful tool that enables seamless integration with Zabbix via the Model Context Protocol. It offers a wide range of features for managing various aspects of Zabbix, from hosts and items to triggers and templates.

✨ 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

📦 Installation

Prerequisites

• Python 3.10 or higher
• uv package manager
• Access to a Zabbix server with API enabled

Quick Start

1. Clone the repository:

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

2. Install dependencies:

   uv sync
   

3. Configure environment variables:

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

4. Test the installation:

   uv run python scripts/test_server.py
   

📚 Documentation

Configuration

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

Running the Server

With startup script (recommended):

uv run python scripts/start_server.py

Direct execution:

uv run python src/zabbix_mcp_server.py

Testing

Run test suite:

uv run python scripts/test_server.py

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

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

1. Configure environment:

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

2. 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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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

🔧 Technical Details

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

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the Zabbix and MCP communities