zabbix-mcp-server

Quick Start

git clone https://github.com/initMAX/zabbix-mcp-server.git
cd zabbix-mcp-server
sudo ./deploy/install.sh
sudo nano /etc/zabbix-mcp/config.toml   # fill in your Zabbix URL + API token
sudo systemctl start zabbix-mcp-server
sudo systemctl enable zabbix-mcp-server

Done. The server is running on http://127.0.0.1:8080/mcp.

Installation

Detailed guide: See INSTALL.md for step-by-step instructions for both on-prem (systemd) and Docker deployments, including uninstall, security checklist, and TLS setup.

Requirements

• Linux server with Python 3.10+
• Network access to your Zabbix server(s)
• Zabbix API token (User settings > API tokens)

Install

git clone https://github.com/initMAX/zabbix-mcp-server.git
cd zabbix-mcp-server
sudo ./deploy/install.sh

The install script will:

1. Create a dedicated system user zabbix-mcp (no login shell)
2. Create a Python virtual environment in /opt/zabbix-mcp/venv
3. Install the server and all dependencies
4. Copy the example config to /etc/zabbix-mcp/config.toml
5. Install a systemd service unit (zabbix-mcp-server)
6. Set up logrotate for /var/log/zabbix-mcp/*.log (daily, 30 days retention)
7. Verify file permissions and offer to fix any issues

User-mode install (no root, dev / laptop use)

For developers running the server locally on their own machine, an alternative installer is shipped that does not require sudo:

./deploy/install-user.sh              # install
./deploy/install-user.sh update       # git pull + pip + restart
./deploy/install-user.sh uninstall

It detects Python 3.10+, creates a virtualenv inside the repo, copies config.example.toml to config.toml (with log_file rewritten to a user-writable path), and registers a background service:

• macOS - LaunchAgent at ~/Library/LaunchAgents/com.initmax.zabbix-mcp-server.plist (auto-restart via KeepAlive)
• Linux - systemd --user unit at ~/.config/systemd/user/zabbix-mcp-server.service with loginctl enable-linger so the service survives logout

This is intended for local development. For production servers use the regular sudo ./deploy/install.sh above.

Upgrade

cd zabbix-mcp-server
sudo ./deploy/install.sh update

That's the whole procedure — no manual steps afterwards. From v1.15+ the update command handles git sync, package reinstall, systemd reload, validation, and service restart in one shot.

What update does:

1. Pulls latest code from the current branch (fast-forward; falls back to fetch + reset --hard origin/<branch> if history diverged), then re-executes itself from the updated script.
2. Reinstalls the Python package into /opt/zabbix-mcp/venv.
3. Refreshes the systemd unit and logrotate config (in case they changed between releases).
4. Checks file permissions and offers to fix any ownership issues.
5. Runs small migrations (legacy token, report templates) and validates config.toml — aborts if the config is invalid.
6. Restarts the service via systemctl restart zabbix-mcp-server and performs an HTTP health check on the configured port.

What is preserved (never overwritten):

• /etc/zabbix-mcp/config.toml — your Zabbix URL, API token, MCP tokens, scopes, TLS settings, etc.
• Admin portal users (stored in [admin.users.*] inside config.toml).
• Audit log, report templates, and any custom data.

You'll see ✓ Config preserved at /etc/zabbix-mcp/config.toml (not overwritten) during the update. Check config.example.toml afterwards for any new options added in the release.

PDF reporting during update:

By default update keeps your current reporting state — if PDF reporting was installed, it stays; if it wasn't, it is not added. To change that:

# Enable PDF reporting on an existing install that didn't have it
sudo ./deploy/install.sh update --with-reporting

# Update without PDF reporting dependencies (smaller install)
sudo ./deploy/install.sh update --without-reporting

The --with-reporting flag pulls in weasyprint, jinja2, and system libs (cairo, pango, gdk-pixbuf). See PDF Reports for what you get.

**Upgrading from very old v