Zabbix MCP Server

1# Zabbix MCP Server
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
5 
6A 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.
7 
8<a href="https://glama.ai/mcp/servers/@mpeirone/zabbix-mcp-server">
9  <img width="380" height="200" src="https://glama.ai/mcp/servers/@mpeirone/zabbix-mcp-server/badge" alt="zabbix-mcp-server MCP server" />
10</a>
11 
12## Features
13 
14### 🏠 Host Management
15- `host_get` - Retrieve hosts with advanced filtering
16- `host_create` - Create new hosts with interfaces and templates
17- `host_update` - Update existing host configurations
18- `host_delete` - Remove hosts from monitoring
19 
20### 👥 Host Group Management
21- `hostgroup_get` - Retrieve host groups
22- `hostgroup_create` - Create new host groups
23- `hostgroup_update` - Modify existing host groups
24- `hostgroup_delete` - Remove host groups
25 
26### 📊 Item Management
27- `item_get` - Retrieve monitoring items with filtering
28- `item_create` - Create new monitoring items
29- `item_update` - Update existing items
30- `item_delete` - Remove monitoring items
31 
32### ⚠️ Trigger Management
33- `trigger_get` - Retrieve triggers and alerts
34- `trigger_create` - Create new triggers
35- `trigger_update` - Modify existing triggers
36- `trigger_delete` - Remove triggers
37 
38### 📋 Template Management
39- `template_get` - Retrieve monitoring templates
40- `template_create` - Create new templates
41- `template_update` - Update existing templates
42- `template_delete` - Remove templates
43 
44### 🚨 Problem & Event Management
45- `problem_get` - Retrieve current problems and issues
46- `event_get` - Get historical events
47- `event_acknowledge` - Acknowledge events and problems
48 
49### 📈 Data Retrieval
50- `history_get` - Access historical monitoring data
51- `trend_get` - Retrieve trend data and statistics
52 
53### 👤 User Management
54- `user_get` - Retrieve user accounts
55- `user_create` - Create new users
56- `user_update` - Update user information
57- `user_delete` - Remove user accounts
58 
59### 🔗 Proxy Management
60- `proxy_get` - Retrieve Zabbix proxies with filtering
61- `proxy_create` - Create new proxies
62- `proxy_update` - Update existing proxies
63- `proxy_delete` - Remove proxies
64 
65### 🔧 Maintenance Management
66- `maintenance_get` - Retrieve maintenance periods
67- `maintenance_create` - Schedule maintenance windows
68- `maintenance_update` - Modify maintenance periods
69- `maintenance_delete` - Remove maintenance schedules
70 
71### 📊 Additional Features
72- `graph_get` - Retrieve graph configurations
73- `discoveryrule_get` - Get discovery rules
74- `itemprototype_get` - Retrieve item prototypes
75- `configuration_export` - Export Zabbix configurations
76- `configuration_import` - Import configurations
77- `apiinfo_version` - Get API version information
78 
79## Installation
80 
81### Prerequisites
82 
83- Python 3.10 or higher
84- [uv](https://docs.astral.sh/uv/) package manager
85- Access to a Zabbix server with API enabled
86 
87### Quick Start
88 
891. **Clone the repository:**
90   ```bash
91   git clone https://github.com/mpeirone/zabbix-mcp-server.git
92   cd zabbix-mcp-server
93   ```
94 
952. **Install dependencies:**
96   ```bash
97   uv sync
98   ```
99 
1003. **Configure environment variables:**
101   ```bash
102   cp config/.env.example .env
103   # Edit .env with your Zabbix server details
104   ```
105 
1064. **Test the installation:**
107   ```bash
108   uv run python scripts/test_server.py
109   ```
110 
111## Configuration
112 
113### Required Environment Variables
114 
115- `ZABBIX_URL` - Your Zabbix server API endpoint (e.g., `https://zabbix.example.com`)
116 
117### Authentication (choose one method)
118 
119**Method 1: API Token (Recommended)**
120- `ZABBIX_TOKEN` - Your Zabbix API token
121 
122**Method 2: Username/Password**
123- `ZABBIX_USER` - Your Zabbix username
124- `ZABBIX_PASSWORD` - Your Zabbix password
125 
126### Optional Configuration
127 
128- `READ_ONLY` - Set to `true`, `1`, or `yes` to enable read-only mode (only GET operations allowed)
129- `VERIFY_SSL` - Enable/disable SSL certificate verification (default: `true`)
130 
131### Transport Configuration
132 
133- `ZABBIX_MCP_TRANSPORT` - Transport type: `stdio` (default) or `streamable-http`
134 
135**HTTP Transport Configuration** (only used when `ZABBIX_MCP_TRANSPORT=streamable-http`):
136- `ZABBIX_MCP_HOST` - Server host (default: `127.0.0.1`)
137- `ZABBIX_MCP_PORT` - Server port (default: `8000`)
138- `ZABBIX_MCP_STATELESS_HTTP` - Stateless mode (default: `false`)
139- `AUTH_TYPE` - Must be set to `no-auth` for streamable-http transport
140 
141## Usage
142 
143### Running the Server
144 
145**With startup script (recommended):**
146```bash
147uv run python scripts/start_server.py
148```
149 
150**Direct execution:**
151```bash
152uv run python src/zabbix_mcp_server.py
153```
154 
155### Transport Options
156 
157The server supports two transport methods:
158 
159#### STDIO Transport (Default)
160Standard input/output transport for MCP clients like Claude Desktop:
161```bash
162# Set in .env or environment
163ZABBIX_MCP_TRANSPORT=stdio
164```
165 
166#### HTTP Transport
167HTTP-based transport for web integrations:
168```bash
169# Set in .env or environment
170ZABBIX_MCP_TRANSPORT=streamable-http
171ZABBIX_MCP_HOST=127.0.0.1
172ZABBIX_MCP_PORT=8000
173ZABBIX_MCP_STATELESS_HTTP=false
174AUTH_TYPE=no-auth
175```
176 
177**Note:** When using `streamable-http` transport, `AUTH_TYPE` must be set to `no-auth`.
178 
179### Testing
180 
181**Run test suite:**
182```bash
183uv run python scripts/test_server.py
184```
185 
186### Read-Only Mode
187 
188When `READ_ONLY=true`, the server will only expose GET operations (retrieve data) and block all create, update, and delete operations. This is useful for:
189 
190- 📊 Monitoring dashboards
191- 🔍 Read-only integrations
192- 🔒 Security-conscious environments
193- 🛡️ Preventing accidental modifications
194 
195### Example Tool Calls
196 
197**Get all hosts:**
198```python
199host_get()
200```
201 
202**Get hosts in specific group:**
203```python
204host_get(groupids=["1"])
205```
206 
207**Create a new host:**
208```python
209host_create(
210    host="server-01",
211    groups=[{"groupid": "1"}],
212    interfaces=[{
213        "type": 1,
214        "main": 1,
215        "useip": 1,
216        "ip": "192.168.1.100",
217        "dns": "",
218        "port": "10050"
219    }]
220)
221```
222 
223**Get recent problems:**
224```python
225problem_get(recent=True, limit=10)
226```
227 
228**Get history data:**
229```python
230history_get(
231    itemids=["12345"],
232    time_from=1640995200,
233    limit=100
234)
235```
236 
237**Get all proxies:**
238```python
239proxy_get()
240```
241 
242**Create a new active proxy:**
243```python
244proxy_create(
245    host="proxy-01",
246    status=5,
247    description="Main datacenter proxy"
248)
249```
250 
251## MCP Integration
252 
253This server is designed to work with MCP-compatible clients like Claude Desktop. See [MCP_SETUP.md](MCP_SETUP.md) for detailed integration instructions.
254 
255## Docker Support
256 
257### Using Docker Compose
258 
2591. **Configure environment:**
260   ```bash
261   cp config/.env.example .env
262   # Edit .env with your settings
263   ```
264 
2652. **Run with Docker Compose:**
266   ```bash
267   docker compose up -d
268   ```
269 
270### Building Docker Image
271 
272```bash
273docker build -t zabbix-mcp-server .
274```
275 
276## Development
277 
278### Project Structure
279 
280```
281zabbix-mcp-server/
282├── src/
283│   └── zabbix_mcp_server.py    # Main server implementation
284├── scripts/
285│   ├── start_server.py         # Startup script with validation
286│   └── test_server.py          # Test script
287├── config/
288│   ├── .env.example           # Environment configuration template
289│   └── mcp.json               # MCP client configuration example
290├── pyproject.toml             # Python project configuration
291├── requirements.txt           # Dependencies
292├── Dockerfile                 # Docker configuration
293├── docker-compose.yml         # Docker Compose setup
294├── README.md                  # This file
295├── MCP_SETUP.md              # MCP integration guide
296├── CONTRIBUTING.md           # Contribution guidelines
297├── CHANGELOG.md              # Version history
298└── LICENSE                   # MIT license
299```
300 
301### Contributing
302 
3031. Fork the repository
3042. Create a feature branch (`git checkout -b feature/amazing-feature`)
3053. Commit your changes (`git commit -m 'Add amazing feature'`)
3064. Push to the branch (`git push origin feature/amazing-feature`)
3075. Open a Pull Request
308 
309### Running Tests
310 
311```bash
312# Test server functionality
313uv run python scripts/test_server.py
314 
315# Test with Docker
316docker-compose exec zabbix-mcp python scripts/test_server.py
317```
318 
319## Error Handling
320 
321The server includes comprehensive error handling:
322 
323- ✅ Authentication errors are clearly reported
324- 🔒 Read-only mode violations are blocked with descriptive messages
325- ✔️ Invalid parameters are validated
326- 🌐 Network and API errors are properly formatted
327- 📝 Detailed logging for troubleshooting
328 
329## Security Considerations
330 
331- 🔑 Use API tokens instead of username/password when possible
332- 🔒 Enable read-only mode for monitoring-only use cases
333- 🛡️ Secure your environment variables
334- 🔐 Use HTTPS for Zabbix server connections
335- 🔄 Regularly rotate API tokens
336- 📁 Store configuration files securely
337 
338## Troubleshooting
339 
340### Common Issues
341 
342**Connection Failed:**
343- Verify `ZABBIX_URL` is correct and accessible
344- Check authentication credentials
345- Ensure Zabbix API is enabled
346 
347**Permission Denied:**
348- Verify user has sufficient Zabbix permissions
349- Check if read-only mode is enabled when trying to modify data
350 
351**Tool Not Found:**
352- Ensure all dependencies are installed: `uv sync`
353- Verify Python version compatibility (3.10+)
354 
355### Debug Mode
356 
357Set environment variable for detailed logging:
358```bash
359export DEBUG=1
360uv run python scripts/start_server.py
361```
362 
363## Dependencies
364 
365- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
366- [python-zabbix-utils](https://github.com/zabbix/python-zabbix-utils) - Official Zabbix Python library
367 
368## License
369 
370This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
371 
372## Acknowledgments
373 
374- [Zabbix](https://www.zabbix.com/) for the monitoring platform
375- [Model Context Protocol](https://modelcontextprotocol.io/) for the integration standard
376- [FastMCP](https://github.com/jlowin/fastmcp) for the server framework
377 
378## Support
379 
380- 📖 [Documentation](README.md)
381- 🐛 [Issue Tracker](https://github.com/mpeirone/zabbix-mcp-server/issues)
382- 💬 [Discussions](https://github.com/mpeirone/zabbix-mcp-server/discussions)
383 
384---
385 
386**Made with ❤️ for the Zabbix and MCP communities**