Skip to main content

Zabbix MCP Server

Let AI agents query and manage Zabbix monitoring through the Model Context Protocol

PyPI Python License

Pre-commit Checks Docker MCP Registry

Installation · Tools · Configuration · Security

Zabbix MCP Server is a Python-based Model Context Protocol (MCP) server designed to provide advanced, programmable access to Zabbix monitoring data and management features. It exposes a modern API for querying, automating, and integrating Zabbix resources such as hosts, templates, triggers, items, problems, events, users, proxies, maintenance periods, and more. The server supports both read and write operations, robust security features, and is suitable for integration with AI assistants, automation tools, dashboards, and custom monitoring workflows.

✨ Features

Core Features

  • Query Zabbix hosts, templates, items, triggers, and host groups with flexible filtering
  • Retrieve problems, events, and alerts with severity filtering
  • Access history and trend data for monitored items
  • Monitor trigger states and problem severity
  • Manage maintenance periods and scheduled downtimes
  • Retrieve user macros and configuration data
  • Get SLA and service information

Management Operations

  • Create, update, and delete hosts, templates, and host groups (if enabled)
  • Manage triggers, items, and discovery rules
  • Configure maintenance periods and user macros
  • Execute scripts on monitored hosts
  • Acknowledge events and close problems
  • Create and manage users and proxies
  • Support for bulk operations on hosts and templates

Advanced Capabilities

  • Rate limiting and API security features
  • Read-only mode to restrict all write operations for safe monitoring
  • Optional tool-search transform for large tool catalogs
  • Bearer token authentication for HTTP transport
  • Comprehensive logging and audit trails
  • SSL/TLS support and configurable timeouts
  • Multiple transport options (STDIO, SSE, HTTP)
  • Optional Sentry integration for error tracking

🚀 Installation

Prerequisites

  • Python 3.11 to 3.15
  • Access to a Zabbix server. Versions 6.0 to 7.4 are supported - that is the range the zabbix-utils client accepts, and it refuses to connect outside it unless ZABBIX_SKIP_VERSION_CHECK=true is set
  • Valid Zabbix API token or user credentials with appropriate permissions

Quick Install from PyPI

The easiest way to get started is to install from PyPI:

# Using UV (recommended)
uvx zabbix-mcp

# Or using pip
pip install zabbix-mcp

Remember to configure the environment variables for your Zabbix instance before running the server:

# Create environment configuration
export ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php
export ZABBIX_TOKEN=your-zabbix-api-token

Install from Source

  1. Clone the repository:
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
  1. Install dependencies:
# Using UV (recommended)
uv sync

# Or using pip
pip install -e .
  1. Configure environment variables:
cp .env.example .env
# Edit .env with your Zabbix URL and credentials
  1. Run the server:
# Using UV (recommended)
uv run zabbix-mcp

# Or using the installed command directly
zabbix-mcp

Using Docker

A Docker image is available on GitHub Packages for easy deployment. It runs the HTTP Streamable transport on port 8000 (/mcp).

docker pull ghcr.io/mhajder/zabbix-mcp:latest

Open WebUI

Open WebUI 0.6.31 and later connect to the image directly; the separate MCPO image (ghcr.io/mhajder/zabbix-mcpo) is no longer published. In Open WebUI, go to Admin Settings > Integrations > External Tool Servers, add a connection of type MCP (Streamable HTTP) with the URL http://<host>:8000/mcp, and set Bearer authentication to your MCP_HTTP_BEARER_TOKEN.

Development Setup

For development with additional tools:

# Clone and install with development dependencies
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

🔧 Configuration

Environment Variables

# Zabbix Connection Details
ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php

# Authentication - use EITHER token OR user/password
# API Token (preferred over user/password)
ZABBIX_TOKEN=your-api-token
# OR Username/Password (for older versions)
# ZABBIX_USER=Admin
# ZABBIX_PASSWORD=zabbix

# SSL Configuration
ZABBIX_VERIFY_SSL=true
ZABBIX_TIMEOUT=30
ZABBIX_SKIP_VERSION_CHECK=false

# Read-Only Mode
# Set READ_ONLY_MODE true to disable all write operations (create, update, delete)
READ_ONLY_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=host,user,maintenance
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Rate Limiting
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listing with search tools
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern matching)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of matching tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops
# the server at startup.
MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# MCP_HTTP_BEARER_TOKEN=

🧰 Available Tools

API Information

  • api_version: Get Zabbix API version information

Host Management

  • host_get: List hosts with optional filtering by groups, templates, proxies, and search criteria
  • host_create: Create a new host with interfaces and template linking
  • host_update: Update host properties (name, status, description)
  • host_delete: Delete hosts by ID

Host Group Management

  • hostgroup_get: List host groups with optional filtering
  • hostgroup_create: Create a new host group
  • hostgroup_update: Update an existing host group's properties (name)
  • hostgroup_delete: Delete host groups

Template Management

  • template_get: List templates with optional filtering
  • template_create: Create a new template
  • template_update: Update template properties (name, description)
  • template_delete: Delete templates

Item Management

  • item_get: List items with optional filtering by hosts, groups, templates
  • item_create: Create a new item on a host
  • item_update: Update item properties (name, delay, units, description, status)
  • item_delete: Delete items

Trigger Management

  • trigger_get: List triggers with severity and state filtering
  • trigger_create: Create a new trigger with expression
  • trigger_update: Update trigger properties (description, expression, priority, status, comments)
  • trigger_delete: Delete triggers

Problem & Event Management

  • problem_get: Get current problems with severity and time filtering
  • event_get: Get events with time range filtering
  • event_acknowledge: Acknowledge events with optional messages
  • history_get: Get historical data for items
  • trend_get: Get trend data for items

User Management

  • user_get: List users with optional filtering
  • user_create: Create a new user
  • user_update: Update user properties (username, name, surname, password, role)
  • user_delete: Delete users

Proxy Management

  • proxy_get: List proxies with optional filtering
  • proxy_create: Create a new proxy
  • proxy_update: Update proxy properties (name, operating mode, description)
  • proxy_delete: Delete proxies

Maintenance Management

  • maintenance_get: List maintenance periods
  • maintenance_create: Create a new maintenance period
  • maintenance_update: Update maintenance period properties (name, times, description)
  • maintenance_delete: Delete maintenance periods

Action & Media

  • action_get: List actions (triggers, autoregistration, etc.)
  • mediatype_get: List media types

Graph & Discovery

  • graph_get: List graphs with optional filtering
  • discoveryrule_get: List LLD discovery rules
  • drule_get: List network discovery rules
  • itemprototype_get: Get item prototypes from discovery rules

SLA & Services

  • sla_get: List SLAs
  • service_get: List services

Scripts

  • script_get: List scripts
  • script_execute: Execute a script on a host

User Macros

  • usermacro_get: List user macros (host and global)
  • usermacro_create: Create a host macro
  • usermacro_delete: Delete host macros

Configuration Management

  • configuration_export: Export Zabbix configurations to JSON or XML
  • configuration_import: Import Zabbix configurations from JSON or XML

🔒 Security & Safety Features

Read-Only Mode

The server supports a read-only mode that disables all write operations for safe monitoring:

READ_ONLY_MODE=true

Tag-Based Tool Filtering

You can disable specific categories of tools by setting disabled tags:

DISABLED_TAGS=user,script

Tool Search for Large Toolsets

FastMCP tool search can reduce prompt size for servers with many tools. When enabled, list_tools returns two synthetic tools:

  • search_tools: Finds matching tools and returns their full schemas
  • call_tool: Executes any discovered tool by name

Enable it with:

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 supports natural language queries, while regex uses a regex pattern input for deterministic matching.

Tool search respects existing visibility controls (read-only mode and disabled tags).

Rate Limiting

The server supports rate limiting to control API usage and prevent abuse. If enabled, requests are limited per client using a sliding window algorithm.

Enable rate limiting by setting the following environment variables in your .env file:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

If RATE_LIMIT_ENABLED is set to true, the server will apply rate limiting middleware. Adjust RATE_LIMIT_MAX_REQUESTS and RATE_LIMIT_WINDOW_MINUTES as needed for your environment.

Sentry Error Tracking & Monitoring (Optional)

The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.

Installation

To enable Sentry monitoring, install the optional dependency:

# Using UV (recommended)
uv sync --extra sentry

Configuration

Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:

# Required: Sentry DSN for your project
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0

# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false

# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production

# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.3

# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "manual", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

# Optional: Enable log capture as breadcrumbs and events (default: true)
SENTRY_ENABLE_LOGS=true

Features

When enabled, Sentry automatically captures:

  • Exceptions & Errors: All unhandled exceptions with full context
  • Performance Metrics: Request/response times and traces
  • MCP Integration: Detailed MCP server activity and interactions
  • Logs & Breadcrumbs: Application logs and event trails for debugging
  • Context Data: Environment, client info, and request parameters

Getting a Sentry DSN

  1. Create a free account at sentry.io
  2. Create a new Python project
  3. Copy your DSN from the project settings
  4. Set it in your .env file

Disabling Sentry

Sentry is completely optional. If you don't set SENTRY_DSN, the server will run normally without any Sentry integration, and no monitoring data will be collected.

SSL/TLS Configuration

The server supports SSL certificate verification and custom timeout settings:

ZABBIX_VERIFY_SSL=true    # Enable SSL certificate verification
ZABBIX_TIMEOUT=30         # Connection timeout in seconds

Transport Configuration

The server supports multiple transport mechanisms for the MCP protocol:

STDIO Transport (Default)

The default transport uses standard input/output for communication. This is ideal for local usage and integration with tools that communicate via stdin/stdout:

MCP_TRANSPORT=stdio

HTTP SSE Transport (Server-Sent Events)

For network-based deployments, you can use HTTP with Server-Sent Events. This allows the MCP server to be accessed over HTTP with real-time streaming:

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

When using SSE transport with a bearer token, clients must include the token in their requests:

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP Streamable Transport

The HTTP Streamable transport provides HTTP-based communication with request/response streaming. This is ideal for web integrations and tools that need HTTP endpoints:

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

When using streamable transport with a bearer token:

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

Note: The HTTP transport requires proper JSON-RPC formatting with jsonrpc and id fields. The server may also require session initialization for some operations.

Health Endpoint

Both HTTP transports (sse and http) serve GET /health, which answers 200 ok when the server is handling requests. It needs no bearer token and does not contact Zabbix, so a Zabbix outage does not mark the MCP server unhealthy. The Docker image's HEALTHCHECK uses it:

curl http://localhost:8000/health

For more information on FastMCP transports, see the FastMCP documentation.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the dev setup, checks and commit message format, and use the issue templates for bugs and feature requests.

Found a security problem? Please report it privately as described in SECURITY.md.

📜 License

MIT License - see LICENSE for details.

Metadata

Release files for zabbix-mcp 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for zabbix-mcp 0.8.0
File Size Uploaded Provenance Actions
zabbix_mcp-0.8.0.tar.gz 318.2 kB With provenance Details for zabbix_mcp-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for zabbix-mcp 0.8.0
File Interpreter ABI Platform Actions
zabbix_mcp-0.8.0-py3-none-any.whl Python 3 none any Details for zabbix_mcp-0.8.0-py3-none-any.whl

Total release size: 407.6 kB

Release files / zabbix_mcp-0.8.0.tar.gz

Download URL zabbix_mcp-0.8.0.tar.gz
Size 318.2 kB
Tags Source
SHA-256 checksum
How to use checksums
699b9c6db41dc8bd894dd02c74b4d98dddcd5adf54c93a9be86cbdb36e6af83c
BLAKE2b-256 checksum
How to use checksums
b3c9898e2bd16e47bc1a20e7fe57a23191853125b36164ce7f4a9e097505bcc9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / zabbix_mcp-0.8.0-py3-none-any.whl

Download URL zabbix_mcp-0.8.0-py3-none-any.whl
Size 89.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2aa1e9688f2b88e839948294ef56cde1b08bc1bbeaacc6cf61dabf8b140771a0
BLAKE2b-256 checksum
How to use checksums
25eed0012ed22b1a9e8f2cb35cd39160b3d19b741c67d9753d12bc76014184f9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for zabbix-mcp 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for zabbix_mcp-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page