zabbix-mcp-server

# Zabbix MCP Server [](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) A comprehensive Model Context Protocol (MCP) server for Zabbix integration using FastMCP and python-zabbix-utils. This server provides complete access to Zabbix API functionality through MCP-compatible tools. <a href="https://glama.ai/mcp/servers/@mpeirone/zabbix-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@mpeirone/zabbix-mcp-server/badge" alt="zabbix-mcp-server MCP server" /> </a> ## 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 ### 🔗 Proxy Management - `proxy_get` - Retrieve Zabbix proxies with filtering - `proxy_create` - Create new proxies - `proxy_update` - Update existing proxies - `proxy_delete` - Remove proxies ### 🔧 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](https://docs.astral.sh/uv/) package manager - Access to a Zabbix server with API enabled ### Quick Start 1. **Clone the repository:** ```bash git clone https://github.com/mpeirone/zabbix-mcp-server.git cd zabbix-mcp-server ``` 2. **Install dependencies:** ```bash uv sync ``` 3. **Configure environment variables:** ```bash cp config/.env.example .env # Edit .env with your Zabbix server details ``` 4. **Test the installation:** ```bash uv run python scripts/test_server.py ``` ## 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) - `VERIFY_SSL` - Enable/disable SSL certificate verification (default: `true`) ### Transport Configuration - `ZABBIX_MCP_TRANSPORT` - Transport type: `stdio` (default) or `streamable-http` **HTTP Transport Configuration** (only used when `ZABBIX_MCP_TRANSPORT=streamable-http`): - `ZABBIX_MCP_HOST` - Server host (default: `127.0.0.1`) - `ZABBIX_MCP_PORT` - Server port (default: `8000`) - `ZABBIX_MCP_STATELESS_HTTP` - Stateless mode (default: `false`) - `AUTH_TYPE` - Must be set to `no-auth` for streamable-http transport ## Usage ### Running the Server **With startup script (recommended):** ```bash uv run python scripts/start_server.py ``` **Direct execution:** ```bash uv run python src/zabbix_mcp_server.py ``` ### Transport Options The server supports two transport methods: #### STDIO Transport (Default) Standard input/output transport for MCP clients like Claude Desktop: ```bash # Set in .env or environment ZABBIX_MCP_TRANSPORT=stdio ``` #### HTTP Transport HTTP-based transport for web integrations: ```bash # Set in .env or environment ZABBIX_MCP_TRANSPORT=streamable-http ZABBIX_MCP_HOST=127.0.0.1 ZABBIX_MCP_PORT=8000 ZABBIX_MCP_STATELESS_HTTP=false AUTH_TYPE=no-auth ``` **Note:** When using `streamable-http` transport, `AUTH_TYPE` must be set to `no-auth`. ### Testing **Run test suite:** ```bash 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 ### Example Tool Calls **Get all hosts:** ```python host_get() ``` **Get hosts in specific group:** ```python host_get(groupids=["1"]) ``` **Create a new host:** ```python 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:** ```python problem_get(recent=True, limit=10) ``` **Get history data:** ```python history_get( itemids=["12345"], time_from=1640995200, limit=100 ) ``` **Get all proxies:** ```python proxy_get() ``` **Create a new active proxy:** ```python proxy_create( host="proxy-01", status=5, description="Main datacenter proxy" ) ``` ## MCP Integration This server is designed to work with MCP-compatible clients like Claude Desktop. See [MCP_SETUP.md](MCP_SETUP.md) for detailed integration instructions. ## Docker Support ### Using Docker Compose 1. **Configure environment:** ```bash cp config/.env.example .env # Edit .env with your settings ``` 2. **Run with Docker Compose:** ```bash docker compose up -d ``` ### Building Docker Image ```bash 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 ```bash # 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: ```bash export DEBUG=1 uv run python scripts/start_server.py ``` ## Dependencies - [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework - [python-zabbix-utils](https://github.com/zabbix/python-zabbix-utils) - Official Zabbix Python library ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgments - [Zabbix](https://www.zabbix.com/) for the monitoring platform - [Model Context Protocol](https://modelcontextprotocol.io/) for the integration standard - [FastMCP](https://github.com/jlowin/fastmcp) for the server framework ## Support - 📖 [Documentation](README.md) - 🐛 [Issue Tracker](https://github.com/mpeirone/zabbix-mcp-server/issues) - 💬 [Discussions](https://github.com/mpeirone/zabbix-mcp-server/discussions) --- **Made with ❤️ for the Zabbix and MCP communities**