Zabbix MCP

Zabbix MCP Server は、Zabbix の監視データや管理機能に対して、高度でプログラム可能なアクセスを提供するために設計された、Python ベースの Model Context Protocol（MCP）サーバーです。ホスト、テンプレート、トリガー、アイテム、問題、イベント、ユーザー、プロキシ、メンテナンス期間などの Zabbix リソースを照会、自動化、統合するための最新の API を提供します。このサーバーは読み取りと書き込みの両方の操作に対応し、堅牢なセキュリティ機能を備えており、AI アシスタント、自動化ツール、ダッシュボード、カスタム監視ワークフローとの統合に適しています。

✨ 特長

主な機能

• Zabbix のホスト、テンプレート、アイテム、トリガー、ホストグループを柔軟なフィルタリングで照会
• 深刻度で絞り込んで、問題、イベント、アラートを取得
• 監視対象アイテムの履歴データとトレンドデータにアクセス
• トリガーの状態と問題の深刻度を監視
• メンテナンス期間と計画済みのダウンタイムを管理
• ユーザーマクロと設定データを取得
• SLA とサービス情報を取得

管理操作

• ホスト、テンプレート、ホストグループを作成、更新、削除（有効な場合）
• トリガー、アイテム、ディスカバリルールを管理
• メンテナンス期間とユーザーマクロを設定
• 監視対象ホストでスクリプトを実行
• イベントを確認し、問題をクローズ
• ユーザーとプロキシを作成・管理
• ホストとテンプレートの一括操作に対応

高度な機能

• レート制限と API セキュリティ機能
• 安全な監視のため、すべての書き込み操作を制限する読み取り専用モード
• 大規模なツールカタログ向けのオプションのツール検索変換
• HTTP トランスポートでのベアラートークン認証
• 包括的なログ記録と監査証跡
• SSL/TLS 対応とタイムアウトの設定
• 複数のトランスポート方式（STDIO、SSE、HTTP）
• エラー追跡用のオプションの Sentry 統合

🚀 インストール

前提条件

• Python 3.11～3.15
• Zabbix サーバーへのアクセス。6.0～7.4 のバージョンに対応しています。この範囲は zabbix-utils クライアントが受け付けるバージョンであり、ZABBIX_SKIP_VERSION_CHECK=true を設定しない限り、この範囲外のバージョンへの接続は拒否されます
• 適切な権限を持つ、有効な Zabbix API トークンまたはユーザー認証情報

PyPI からのクイックインストール

最も簡単に使い始めるには、PyPI からインストールします。

# Using UV (recommended)
uvx zabbix-mcp

# Or using pip
pip install zabbix-mcp

サーバーを実行する前に、Zabbix インスタンスの環境変数を設定してください。

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

ソースからインストール

1. リポジトリをクローンします。

git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp

2. 依存関係をインストールします。

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 環境変数を設定します。

cp .env.example .env
# Edit .env with your Zabbix URL and credentials

4. サーバーを実行します。

# Using UV (recommended)
uv run zabbix-mcp

# Or using the installed command directly
zabbix-mcp

Docker の使用

GitHub Packages で Docker イメージを提供しており、簡単にデプロイできます。HTTP Streamable トランスポートをポート 8000（/mcp）で実行します。

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

Open WebUI

Open WebUI 0.6.31 以降では、イメージに直接接続できます。別個の MCPO イメージ（ghcr.io/mhajder/zabbix-mcpo）は公開されなくなりました。Open WebUI で、Admin Settings > Integrations > External Tool Servers に移動し、URL を http://<host>:8000/mcp に設定して、接続タイプ MCP (Streamable HTTP) を追加します。Bearer 認証には MCP_HTTP_BEARER_TOKEN を設定します。

開発環境のセットアップ

追加のツールを使用した開発の場合：

# 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

🔧 設定

環境変数

# 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://[email protected]/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=

🧰 利用可能なツール

API 情報

• api_version：Zabbix API のバージョン情報を取得します

ホスト管理

• host_get：グループ、テンプレート、プロキシ、検索条件で任意に絞り込んでホストを一覧表示します
• host_create：インターフェースとテンプレートのリンクを設定して新しいホストを作成します
• host_update：ホストのプロパティ（名前、ステータス、説明）を更新します
• host_delete：ID を指定してホストを削除します

ホストグループ管理

• hostgroup_get：任意の条件で絞り込んでホストグループを一覧表示します
• hostgroup_create：新しいホストグループを作成します
• hostgroup_update：既存のホストグループのプロパティ（名前）を更新します
• hostgroup_delete：ホストグループを削除します

テンプレート管理

• template_get：任意の条件で絞り込んでテンプレートを一覧表示します
• template_create：新しいテンプレートを作成します
• template_update：テンプレートのプロパティ（名前、説明）を更新します
• template_delete：テンプレートを削除します

アイテム管理

• item_get：ホスト、グループ、テンプレートで任意に絞り込んでアイテムを一覧表示します
• item_create：ホストに新しいアイテムを作成します
• item_update：アイテムのプロパティ（名前、間隔、単位、説明、ステータス）を更新します
• item_delete：アイテムを削除します

トリガー管理

• trigger_get：深刻度と状態で絞り込んでトリガーを一覧表示します
• trigger_create：式を指定して新しいトリガーを作成します
• trigger_update：トリガーのプロパティ（説明、式、優先度、ステータス、コメント）を更新します
• trigger_delete：トリガーを削除します

障害・イベント管理

• problem_get：深刻度と時間で絞り込んで現在の障害を取得します
• event_get：期間を指定してイベントを取得します
• event_acknowledge：任意のメッセージを添えてイベントを確認します

履歴・トレンド

• history_get：アイテムの履歴データを取得します
• trend_get：アイテムのトレンドデータを取得します

ユーザー管理

• user_get：任意の条件で絞り込んでユーザーを一覧表示します
• user_create：新しいユーザーを作成します
• user_update：ユーザーのプロパティ（名前、姓、パスワード、タイプ）を更新します
• user_delete：ユーザーを削除します

プロキシ管理

• proxy_get：任意の条件で絞り込んでプロキシを一覧表示します
• proxy_create：新しいプロキシを作成します
• proxy_update：プロキシのプロパティ（名前、動作モード、説明）を更新します
• proxy_delete：プロキシを削除します

メンテナンス管理

• maintenance_get：メンテナンス期間を一覧表示します
• maintenance_create：新しいメンテナンス期間を作成します
• maintenance_update：メンテナンス期間のプロパティ（名前、時間、説明）を更新します
• maintenance_delete：メンテナンス期間を削除します

アクション・メディア

• action_get：アクション（トリガー、自動登録など）を一覧表示します
• mediatype_get：メディアタイプを一覧表示します

グラフ・ディスカバリ

• graph_get：任意の条件で絞り込んでグラフを一覧表示します
• discoveryrule_get：LLD ディスカバリルールを一覧表示します
• drule_get：ネットワークディスカバリルールを一覧表示します
• itemprototype_get：ディスカバリルールからアイテムのプロトタイプを取得します

SLA・サービス

• sla_get：SLA を一覧表示します
• service_get：サービスを一覧表示します

スクリプト

• script_get：スクリプトを一覧表示します
• script_execute：ホスト上でスクリプトを実行します

ユーザーマクロ

• usermacro_get：ユーザーマクロ（ホストおよびグローバル）を一覧表示します
• usermacro_create：ホストマクロを作成します
• usermacro_delete：ホストマクロを削除します

設定管理

• configuration_export：Zabbix の設定を JSON または XML にエクスポートします
• configuration_import：JSON または XML から Zabbix の設定をインポートします

🔒 セキュリティと安全機能

読み取り専用モード

サーバーは、すべての書き込み操作を無効にして安全に監視できる読み取り専用モードをサポートしています。

READ_ONLY_MODE=true

タグベースのツールフィルタリング

無効化するタグを設定することで、特定カテゴリのツールを無効にできます。

DISABLED_TAGS=alert,bills

大規模なツールセット向けのツール検索

FastMCP のツール検索を使うと、ツールが多数あるサーバーのプロンプトサイズを削減できます。 有効にすると、list_tools は次の2つの合成ツールを返します。

• search_tools：条件に一致するツールを検索し、完全なスキーマを返します
• call_tool：名前を指定して、検出した任意のツールを実行します

次のようにして有効にします。

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

bm25 は自然言語のクエリに対応し、regex は決定論的なマッチングに pattern 入力を使用します。

ツール検索では、既存の表示制御（読み取り専用モードと無効化されたタグ）が適用されます。

レート制限

サーバーは、API の使用量を制御して不正利用を防ぐためのレート制限をサポートしています。有効にすると、スライディングウィンドウ方式を使用してクライアントごとにリクエスト数を制限します。

.env ファイルで次の環境変数を設定すると、レート制限を有効にできます。

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

RATE_LIMIT_ENABLED を true に設定すると、サーバーはレート制限ミドルウェアを適用します。環境に合わせて RATE_LIMIT_MAX_REQUESTS と RATE_LIMIT_WINDOW_MINUTES を調整してください。

Sentry によるエラー追跡とモニタリング（任意）

サーバーは、エラー追跡、パフォーマンス監視、デバッグのために Sentry を任意でサポートしています。Sentry との連携は完全に任意であり、設定されている場合にのみ初期化されます。

インストール

Sentry によるモニタリングを有効にするには、任意の依存関係をインストールします。

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

設定

.env ファイルで SENTRY_DSN 環境変数を設定すると、Sentry を有効にできます。

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/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: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

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

機能

有効にすると、Sentry は次の情報を自動的に収集します。

• 例外とエラー：コンテキスト全体を含む、処理されなかったすべての例外
• パフォーマンス指標：リクエストとレスポンスの所要時間、およびトレース
• MCP 連携：MCP サーバーの詳細なアクティビティとやり取り
• ログとブレッドクラム：デバッグ用のアプリケーションログとイベント履歴
• コンテキストデータ：環境、クライアント情報、リクエストパラメーター

Sentry DSN の取得

1. sentry.io で無料アカウントを作成します
2. 新しい Python プロジェクトを作成します
3. プロジェクト設定から DSN をコピーします
4. .env ファイルに設定します

Sentry の無効化

Sentry は完全に任意です。SENTRY_DSN を設定しなければ、サーバーは Sentry と連携せずに通常どおり動作し、モニタリングデータも収集されません。

SSL/TLS の設定

サーバーは、SSL 証明書の検証とカスタムタイムアウト設定をサポートしています。

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

トランスポートの設定

サーバーは、MCP プロトコル向けに複数のトランスポート方式をサポートしています。

STDIO トランスポート（デフォルト）

デフォルトのトランスポートでは、標準入力／出力を使用して通信します。これはローカルでの使用や、stdin/stdout 経由で通信するツールとの連携に適しています。

MCP_TRANSPORT=stdio

HTTP SSE トランスポート（サーバー送信イベント）

ネットワーク経由でデプロイする場合は、サーバー送信イベントを使用した HTTP を利用できます。これにより、リアルタイムストリーミングで HTTP 経由で MCP サーバーにアクセスできます。

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

SSE トランスポートでベアラートークンを使用する場合、クライアントはリクエストにトークンを含める必要があります。

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

HTTP ストリーム可能トランスポート

HTTP ストリーム可能トランスポートは、リクエスト／レスポンスのストリーミングを伴う HTTP ベースの通信を提供します。これは、ウェブ連携や HTTP エンドポイントを必要とするツールに適しています。

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

ストリーム可能トランスポートでベアラートークンを使用する場合：

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

注：HTTP トランスポートでは、jsonrpc フィールドと id フィールドを含む適切な JSON-RPC 形式が必要です。また、一部の操作ではサーバーセッションの初期化が必要になる場合があります。

ヘルスエンドポイント

どちらの HTTP トランスポート（sse と http）でも GET /health が利用でき、サーバーがリクエストを処理している場合は 200 ok を返します。ベアラートークンは不要で、Zabbix に接続しないため、Zabbix の障害によって MCP サーバーが異常と判定されることはありません。 Docker イメージの HEALTHCHECK では、このエンドポイントを使用します。

curl http://localhost:8000/health

FastMCP のトランスポートについて詳しくは、FastMCP のドキュメントをご覧ください。

🤝 貢献

貢献を歓迎します。開発環境のセットアップ、チェック、コミットメッセージの形式についてはCONTRIBUTING.mdをご覧ください。バグ報告や機能リクエストには、イシューテンプレートをご利用ください。

セキュリティ上の問題を見つけた場合は、SECURITY.mdの説明に従って、非公開で報告してください。

📜 ライセンス

MIT ライセンスです。詳細はLICENSEをご覧ください。