Skip to main content
Glama
Zabbix MCP Server

Zabbix MCP Server

by TemplarFan

Zabbix MCP Server

English | 中文文档

License: GPL-3.0 Python 3.10+

A Model Context Protocol (MCP) server for Zabbix integration using FastMCP and python-zabbix-utils. It ships 21 focused tools for querying hosts, items, triggers, problems and monitoring data, plus daily/weekly/monthly operations report generators — designed for AI-assisted operations (AIOps) agents.

Features

🏠 Host Management

  • host_get - Query hosts with filtering, group/template selection and inventory

  • host_update - Update a host's visible name and host groups

  • get_host_by_ip - Look up a host precisely by its IP address

  • hostgroup_get - Query host groups

  • hostgroup_get_hosts - List hosts inside one or more host groups

  • host_software_inventory_get - Query a single host's software inventory

📊 Monitoring Data

  • item_get - Query items with semantic search and key-metric filtering

  • trigger_get - Query triggers, optionally filtered by severity

  • history_get - Get raw item history data

  • trend_get - Get hourly-aggregated trend data

  • trend_summary - Sample-weighted trend summary over a time window

🚨 Problems & Events

  • event_get - Query raw historical events with cursor pagination

  • get_problem_summary - Unified classification summary of current problems

  • get_problem_fact_detail - Real recovery, manual handling and current monitoring status per problem event

  • quick_status - Overall status: hosts, classified problems and last-24h events

  • check_host_health - Per-host interface availability, problem classification and key metrics

  • host_alert_history - Fully paired alert/recovery history per host and trigger

📈 Operations Reports

  • event_daily_report - Generate a daily operations report in Markdown

  • event_weekly_report - Generate a weekly (Mon–Sun) operations report

  • event_monthly_report - Generate a monthly operations report

ℹ️ System

  • apiinfo_version - Get the Zabbix API version

Related MCP server: Zabbix MCP Server

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/TemplarFan/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

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)

  • ZABBIX_TEST_NETWORKS - Comma-separated test network CIDRs (e.g., 192.168.100.0/24,192.168.101.0/24) excluded by report tools when production_only=true; leave empty to disable

  • ZABBIX_MAX_RESPONSE_CHARS - Max characters per tool response (default: 50000); oversized list results are truncated per entry (JSON stays valid) with an envelope and narrowing advice

  • ZABBIX_DENY_TOOLS - Comma-separated tool names removed at registration (invisible to models, e.g., host_update); leave empty to enable all tools

  • ZABBIX_ALLOWED_IPS - Comma-separated source IPs/CIDRs allowed on the HTTP transport (e.g., 127.0.0.1,192.168.0.0/16); unmatched sources get 403; leave empty to allow all (stdio is unaffected)

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):

uv run python scripts/start_server.py

Direct execution:

uv run python -m src.main

Transport Options

The server supports two transport methods:

STDIO Transport (Default)

Standard input/output transport for MCP clients like Claude Desktop:

# Set in .env or environment
ZABBIX_MCP_TRANSPORT=stdio

HTTP Transport

HTTP-based transport for web integrations:

# 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:

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:

host_get()

Get hosts in specific group:

host_get(groupids=["1"])

Summarize current problems needing attention:

get_problem_summary(view="actionable")

Get history data:

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

Check a host's health:

check_host_health(host_identifier="web-server-01")

Generate yesterday's operations report:

event_daily_report(date="yesterday", production_only=true)

MCP Integration

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

Development

Project Structure

zabbix-mcp-server/
├── src/                        # MCP server implementation
│   ├── main.py                 # Server entrypoint and tool registration
│   ├── client.py               # Zabbix API client
│   ├── config.py               # Configurable parameters
│   ├── tools/                  # MCP tool definitions
│   ├── reporting/              # Daily/weekly/monthly report generators
│   ├── services/               # Business logic services
│   └── utils/                  # Helpers
├── 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
│   └── workflow_prompt.md      # Alarm analysis workflow prompt
├── .env.example                # Environment configuration template
├── pyproject.toml              # Python project configuration
├── requirements.txt            # Dependencies
├── uv.lock                     # Lockfile for reproducible installs
├── README.md                   # This file
├── README.zh-CN.md             # Chinese documentation
├── MCP_SETUP.md                # MCP integration guide
└── LICENSE                     # GPL-3.0 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

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

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Project Origin

Based on mpeirone/zabbix-mcp-server (GPL-3.0). This project has been substantially rewritten and extended with:

  • Operations report generators (daily / weekly / monthly) with unified problem classification

  • Problem fact-checking service (true recovery and manual handling status)

  • Production-only filtering driven by environment configuration

  • Alarm-analysis prompt template for n8n workflows

  • A fully documented 21-tool MCP toolset aligned with the actual implementation

Acknowledgments


Made with ❤️ for the Zabbix and MCP communities

Available Tools

21 tools
apiinfo_versionA

获取Zabbix API版本信息

Inputs: no named parameters. Returns: result

check_host_healthA

按主机查询接口可用性、统一当前问题分类和关键指标。

Inputs: host_identifier (required), time_range, trend_hours, include_oracle, +1 more. Returns: result

event_daily_reportA

生成运维日报 Markdown,展示条数默认与定时推送日报一致,可按章节覆盖或仅统计生产口径。

Inputs: date, top_n_severe, top_n_chronic, top_n_disaster, +3 more. Returns: result

event_getA

查询原始历史事件;业务状态解释使用问题事实明细工具。

Inputs: limit, value, output, source, +9 more. Returns: result

event_monthly_reportB

生成运维月报 Markdown,展示条数默认与定时推送月报一致,可按章节覆盖或仅统计生产口径。

Inputs: month, top_n_severe, top_n_chronic, top_n_regular, +4 more. Returns: result

event_weekly_reportA

生成周一至周日运维周报 Markdown,展示条数默认与定时推送周报一致,可按章节覆盖或仅统计生产口径。

Inputs: week, top_n_severe, top_n_chronic, top_n_regular, +4 more. Returns: result

get_host_by_ipA

通过IP精确查询主机。已知IP时优先用此工具,比host_get更精准省Token

Inputs: ip (required). Returns: result

get_problem_fact_detailA

按问题事件 ID 查询真实恢复、人工处置和当前监控状态。

Inputs: eventid (required). Returns: result

get_problem_summaryA

查询统一分类后的当前问题摘要。历史事件用event_get

Inputs: view, hostids, group_by, time_range. Returns: result

history_getA

获取监控项原始历史数据。长期趋势用trend_get

Inputs: itemids (required), limit, history, sortfield, +3 more. Returns: result

host_alert_historyC

查询完整分页、精确恢复配对的主机与触发器告警历史。

Inputs: hostid (required), triggerid (required), days. Returns: host_alert_history 工具返回结果

host_getB

查询主机列表。支持ID精确查询或名称模糊匹配,已知IP时优先用get_host_by_ip

Inputs: name, limit, filter, output, +6 more. Returns: result

hostgroup_getC

查询主机群组列表

Inputs: name, limit. Returns: result

hostgroup_get_hostsA

查询群组内的主机列表。需先通过hostgroup_get获取groupid

Inputs: groupids (required), limit. Returns: result

host_software_inventory_getB

查询单台主机的软件资产信息(software/software_full/software_app_a-e)

Inputs: host_identifier (required). Returns: result

host_updateA

修改主机的可见名称和群组。群组参数为groupid(需先查询)

Inputs: hostid (required), new_name, add_groups, remove_groups. Returns: result

item_getA

查询监控项。需先通过host_get获取hostid。支持语义搜索,key_metrics_only智能筛选最佳指标

Inputs: limit, output, search, hostids, +2 more. Returns: result

quick_statusC

查看主机、统一当前问题分类及最近二十四小时事件。

Inputs: include_offline, include_disabled. Returns: result

trend_getA

获取监控项趋势数据(每小时聚合)。摘要用trend_summary

Inputs: itemids (required), limit, time_from, time_till. Returns: result

trend_summaryB

按趋势桶样本数加权汇总,并返回时间桶与样本覆盖情况。

Inputs: itemids (required), hours. Returns: result

trigger_getB

查询触发器列表。priority=3,4,5只看严重以上级别

Inputs: limit, filter, output, search, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation3/5

    Several read-oriented tools overlap around current problems, host health, quick status, and event history: get_problem_summary, get_problem_fact_detail, check_host_health, quick_status, host_alert_history, and event_get can be confused despite their descriptions. The descriptions do provide guidance, but boundaries are not always crisp.

    Naming Consistency3/5

    All names use snake_case, but verb/noun ordering is mixed: host_get, item_get, event_get, and trend_get use noun_verb, while get_problem_summary, get_host_by_ip, and check_host_health use verb_noun, and others like quick_status and apiinfo_version are noun phrases. The conventions are readable but inconsistent.

    Tool Count4/5

    21 tools is on the heavy side, but Zabbix is a broad monitoring domain covering hosts, groups, items, triggers, events, history, trends, reports, and health checks. Most tools map to distinct data needs, though a few status/problem tools could be consolidated.

    Completeness4/5

    The read surface is strong: hosts, groups, software inventory, items, triggers, events, history, trends, health checks, and daily/weekly/monthly reports are covered. Write/lifecycle coverage is thinner, with host_update but no host create/delete, problem acknowledgement, maintenance, or template/user management, which are notable but not fatal for a query/report-focused server.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      🔌 Complete MCP server for Zabbix integration - Connect AI assistants to Zabbix monitoring with 40+ tools for hosts, items, triggers, templates, problems, and more. Features read-only mode and comprehensive API coverage.
      3
      262
      GPL 3.0
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables users to monitor and query Zabbix infrastructure through natural language by providing access to current problems, active triggers, and system health status via the Zabbix API.
      -
    • A
      license
      B
      quality
      A
      maintenance
      Official initMAX MCP server exposing the Zabbix API to AI assistants for monitoring and managing hosts, problems, templates, dashboards, and multiple Zabbix instances. Includes correlated monitoring views, graphs, anomaly detection, capacity forecasts, and PDF reports, with scoped tokens, read-only modes, OAuth 2.1, and an admin portal. Supports Streamable HTTP, SSE, and stdio.
      84
      247
      AGPL 3.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Exposes Zabbix monitoring capabilities as callable tools for AI agents and MCP-compatible clients.
      -