Zabbix API MCP

zapi-mcp

English | 日本語

Zabbix API 用の MCP（Model Context Protocol）サーバーです。

ネットワーク運用向けに構築されています。単一の daily_brief 呼び出しで、アクティブな問題と、サイト固有のカテゴリ（DHCP プール使用率、SNAT セッション使用率、コアネットワークの問題など）を要約し、個別のツールで問題、ホスト、アイテムの値を照会できます。組織固有のタグはコードではなく設定ファイルに記述するため、サーバーを汎用的に保てます。

バージョンに適応した認証により、Zabbix 6.0 LTS（user + auth フィールド）で動作し、6.4 / 7.0（username + Authorization: Bearer）との互換性も確保しています。

ドキュメント：https://shigechika.github.io/zapi-mcp/

機能

ツール	説明
health_check	サーバーバージョン、Zabbix の接続状態と認証状態、検出された API バージョン、設定済みの daily_brief カテゴリを表示します。セッション開始時またはタイムアウト後に呼び出してください
daily_brief	朝の巡回：アクティブな問題（Warning 以上）、現在メンテナンス中のホスト、および設定済みのカテゴリごとのセクションを表示します
get_problems	深刻度とタグで絞り込んだアクティブな問題を、新しい順に経過時間とともに表示します。ヘッダーには実際の合計数が表示されます（上限に達した場合は showing N of TOTAL）。無効なトリガー、ホスト、またはアイテムに関する問題は Zabbix フロントエンドと同様に非表示になります（include_disabled=True を指定すると一覧に含まれます）。出力には eventid が含まれます
get_hosts	ロール、タグ、グループで絞り込んだホスト一覧を、IP アドレスとタグとともに表示します
get_host_items	ホストの現在のアイテム値を取得します（サーバー側でホストを絞り込みます）
acknowledge_problem	問題を確認し、メッセージを追加します（問題はクローズしません）
set_maintenance	location タグまたはホスト名の完全一致でホストを選択し、冪等な Zabbix メンテナンス期間を開始します（いずれか一方を指定）
get_maintenance_windows	メンテナンス期間（アクティブ／予定／期限切れ）を一覧表示します。別のツールのアラートを新しいインシデントとして扱う前に照合してください

セットアップ

# uv
uv pip install zapi-mcp

# pip
pip install zapi-mcp

またはソースから：

git clone https://github.com/shigechika/zapi-mcp.git
cd zapi-mcp

# uv
uv sync

# pip
pip install -e .

設定

以下の環境変数を設定します。

変数	説明	デフォルト
ZABBIX_URL	Zabbix のベース URL（例：https://zabbix.example.com）。存在しない場合は /api_jsonrpc.php が追加されます	必須
ZABBIX_API_TOKEN	Zabbix API トークン（Zabbix 5.4 以降）。ZABBIX_USER／ZABBIX_PASSWORD の代わりに使用します	いずれか一方
ZABBIX_USER	Zabbix API ユーザー	いずれか一方
ZABBIX_PASSWORD	Zabbix API パスワード	いずれか一方
ZABBIX_CATEGORIES_INI	daily_brief 用カテゴリ INI ファイルのパス（任意）	—
ZABBIX_BRIEF_RECENT_HOURS	daily_brief の「最近」の時間範囲（時間単位）。これより古い問題は件数にまとめられます	24
ZABBIX_BRIEF_PROBLEM_LIMIT	daily_brief が呼び出しごとに取得するアクティブな問題の最大数。超過分は件数にまとめられます	1000
ZABBIX_READ_ONLY	true（または 1／yes／on）にすると、acknowledge_problem と set_maintenance が登録されず、モデルから見えなくなります。false 以外の値も読み取り専用として扱われ、health_check で報告されます	未設定（書き込みツールを有効化）

API ユーザーには、照会するホストグループへの読み取り権限が必要です。また、acknowledge_problem を使用する場合は確認権限、set_maintenance を使用する場合はメンテナンス書き込み権限、get_maintenance_windows および daily_brief の「メンテナンス中」セクションを使用する場合はメンテナンス読み取り権限（通常はデフォルトで含まれます）が必要です。

認証には ZABBIX_API_TOKEN、または ZABBIX_USER + ZABBIX_PASSWORD のどちらかを使用してください。トークンが設定されている場合、残っている ZABBIX_USER は無視されます。トークンと ZABBIX_USER および ZABBIX_PASSWORD の両方が設定されている場合は、設定エラーになります。トークンではログインが不要で、クライアント設定にパスワードを含めずに済みます。また、有効期限を設定でき、Zabbix の API トークンページから個別に取り消すこともできます。

daily_brief のアクティブな問題

問題は重大度別に分類され、新しいものから順に表示され、それぞれに経過時間（例：3h ago）が付記されます。最近の期間（ZABBIX_BRIEF_RECENT_HOURS、デフォルトは24h）より古い問題は、1行の … and N older (stale; oldest …) にまとめられます。これにより、復旧が自動確認されず Zabbix がアクティブなままにしているアラート（ICMP ping down、RDP down、…）のバックログによって、直近の出来事が埋もれることはありません。セクション見出しには実際の合計件数が記載され、取得件数に上限がある場合は、黙って切り捨てるのではなく showing N of TOTAL と表示されます。

daily_brief のメンテナンスウィンドウ

Active Problems のすぐ後に、daily_brief は現在有効なメンテナンスウィンドウの対象ホストと、今日の後の時間に開始するウィンドウの対象ホストを一覧表示します。これにより、それらのホストを監視している他のものが、計画された停止を新たなインシデントと誤認するのを防げます。表示する内容がない場合（新しい情報がなければメンテナンスもありません）、## In Maintenance セクション全体が省略されます。明日以降に開始するウィンドウと、期限切れのウィンドウはここには含まれません。全体像を確認するには、get_maintenance_windows を呼び出してください（必要に応じて include_expired=True を指定できます）。

daily_brief のカテゴリ（任意）

daily_brief は常にアクティブな問題を一覧表示します。DHCP プールの枯渇、SNAT セッションの使用量、コアネットワークの問題など、サイト固有のセクションを追加するには、ZABBIX_CATEGORIES_INI に INI ファイルを指定します。各 [section] が1つのカテゴリです。

[dhcp]
name = DHCP Pool Usage
# Zabbix host tag identifying the group
tag = dhcp-pool-usage
# report current values for this exact item key
item_key = usage
# flag values >= this
threshold = 80

[snat]
name = SNAT Session Pool
tag = snat-pool-usage
# substring match (catches pool.node0.usage etc.)
item_key_search = .usage
threshold = 80

[core]
name = Core Network
tag = role
# the tag must equal this value
tag_value = main
# no item key -> report active problems instead

• tag（必須）：カテゴリを識別するホストタグです。tag_value を指定した場合、タグの値が一致する必要があります（Equal）。指定しない場合は、そのタグを持つすべてのホストが一致します（Exists）。
• item_key / item_key_search：いずれかを設定すると、このセクションは現在のアイテム値を高い順に表示します。item_key はキーと完全一致します。ID を含むキーには item_key_search を使用してください（例：.usage は pool.node0.usage に一致します）。どちらも設定しない場合は、そのタグに関連するアクティブな問題を表示します。
• threshold：任意です。この値以上の値にフラグを付けます。

categories.ini.example を参照してください。変数が未設定の場合、またはファイルが見つからない場合、daily_brief はアクティブな問題のみを報告します。

書き込み操作

状態を変更するツールは2つです。それ以外はすべて読み取り専用です。

ツール	Zabbix API 呼び出し
acknowledge_problem	event.acknowledge
set_maintenance	maintenance.create

acknowledge_problem には API ユーザーの確認権限が必要です。set_maintenance にはメンテナンス書き込み権限が必要です。どちらかの権限を付与しない場合、そのツールについてサーバーは読み取り専用のままです。呼び出しは Zabbix API で失敗しますが、他のすべてのツールは引き続き動作します。そのため、Zabbix の設定を変更する権限を与えずに、調査用として API ユーザーを AI アシスタントに渡すことができます。アシスタントを通じたアラートの確認やメンテナンスウィンドウの開始が業務に必要な場合にのみ、権限を付与してください。

書き込みツールをモデルから完全に隠すには、ZABBIX_READ_ONLY=true を設定してください。2つのツールは登録されないため、クライアントには表示されず、呼び出された場合も実行を拒否します。これにより、1つの Zabbix ユーザーを、読み取り専用と書き込み可能な MCP クライアントの両方で使用できます。すべてのツールには MCP ツールアノテーション（readOnlyHint、destructiveHint、idempotentHint）も付いているため、クライアントは読み取りツールと書き込みツールを区別できます。

使用方法

Claude Code（プラグイン）

このリポジトリは単一プラグインのマーケットプレイスも兼ねているため、Claude Code からサーバーをインストールできます。

/plugin marketplace add shigechika/zapi-mcp
/plugin install zapi-mcp@zapi-mcp

このプラグインは uvx zapi-mcp を起動し、設定に記載されている同じ環境変数を読み込みます。Claude Code を起動する前に環境変数をエクスポートしてください。ZABBIX_CATEGORIES_INI は未設定のままでもかまいません。

uvx は Claude Code を実行するプロセスの PATH に含まれている必要があります。通常、ログインシェルには含まれていますが、GUI から起動したアプリには含まれていない場合があります。プラグインが起動しない場合は、uv をシステム全体にインストールしてください。

Claude Code（手動）

.mcp.json に追加します。

{
  "mcpServers": {
    "zapi-mcp": {
      "type": "stdio",
      "command": "zapi-mcp",
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_USER": "api-user",
        "ZABBIX_PASSWORD": "",
        "ZABBIX_CATEGORIES_INI": "/path/to/categories.ini"
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "zapi-mcp": {
      "command": "zapi-mcp",
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_USER": "api-user",
        "ZABBIX_PASSWORD": ""
      }
    }
  }
}

Codex

codex mcp add zapi-mcp \
  --env ZABBIX_URL=https://zabbix.example.com \
  --env ZABBIX_USER=api-user \
  --env ZABBIX_PASSWORD=your-password \
  --env ZABBIX_CATEGORIES_INI=/path/to/categories.ini \
  -- zapi-mcp

stdio サーバーを起動する他の MCP クライアントも同じ方法で動作します。コマンドに zapi-mcp を指定し、環境に ZABBIX_* 変数を設定してください。

直接実行

export ZABBIX_URL=https://zabbix.example.com
export ZABBIX_USER=api-user
export ZABBIX_PASSWORD=your-password
# or, instead of the user and password: export ZABBIX_API_TOKEN=your-token
zapi-mcp

CLI オプション

zapi-mcp --version   # Print version and exit
zapi-mcp --check     # Verify environment variables and authentication, then exit
zapi-mcp --brief     # Print the daily_brief to stdout and exit (handy for cron)
zapi-mcp             # Start MCP server (STDIO, default)

--check の終了コード：0 は成功、1 は設定エラー、2 は認証／接続エラーです。

--brief の終了コード：0 は成功、1 はセクションの失敗（認証、アクティブな問題の取得、またはカテゴリの読み込み。出力に埋め込まれた Error: 行を参照してください）です。

開発

git clone https://github.com/shigechika/zapi-mcp.git
cd zapi-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
.venv/bin/pytest -v
.venv/bin/ruff check .

ライブスモークテスト

pytest はフィクスチャに対してロジックを確認しますが、ツールが実データを返さなくなったことは検出できません。scripts/smoke_test.py は、設定済みの Zabbix に対して登録済みのすべてのツールを実行し、空、不正形式、またはエラーの応答があると失敗します。

# needs the same ZABBIX_* environment variables as the server
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only get_problems --traceback

• 読み取り専用です。 acknowledge_problem と set_maintenance は名前でスキップされます。確認応答はすべてのオペレーターに表示され、ひそかに取り消すことができません。また、set_maintenance は実際のメンテナンス期間を開始してアラートを抑制します。このことはテストで強制されています。レポートにはツール名とステータスのみが出力され、ペイロードは出力されません。Zabbix が照会対象のホストを引用するため、サーバーが生成したエラーテキストも伏せられます。--traceback を指定すると、オペレーター自身の端末には全文が表示されます。
• 実在するホスト、グループ、またはタグ値を特定する引数は、scripts/smoke_probes.py に書き込まず、実行時に検出します。これを強制するテストが2つあります。1つは、これらのパラメーターがリテラル値として記述されている場合に拒否し、もう1つは、ファイル内のどこであってもアドレス形式（メールアドレス、URL、ホスト名、IPv4、IPv6）の値を禁止します。
• 何も問題がない監視システムこそが目標であるため、空の応答も実際の観測結果です。そこで、プローブでは行数ではなく、ツールが生成すべきエンベロープを検証します。
• CI では、簡易的なチェックを行います。プローブ仕様なしで登録されたツールがあるとビルドが失敗します（tests/test_smoke_probes.py）。そのため、ツールを追加する際に「動作していることをどう確認するか」という問いが必ず生じます。
• scripts/smoke_harness.py はエンジンであり、Zabbix に関する知識を持ちません。このファイルは、同じエンジンを共有するサーバー間で同一に保たれているため、エンジンのバグは一度修正してファイルを同期し、このコピーにパッチを当てないでください。

リリース

リリースは release-please で自動化されています。Conventional Commits（feat:、fix:、…）を main にマージすると、次のバージョンと変更履歴を記載したリリース PR が開いた状態に保たれます。その PR をマージすると vX.Y.Z タグが付与され、GitHub Release が公開されます。その release: published イベントによって release ワークフローが起動し、PyPI と MCP Registry へのビルドと公開が行われます。zapi_mcp/__init__.py と server.json のバージョンは release-please が管理します（手動で更新しないでください）。

重要

release-please ワークフローには、リポジトリシークレット RELEASE_PLEASE_TOKEN（contents: write と pull-requests: write の権限を持つ PAT）を設定してください。 デフォルトの GITHUB_TOKEN では、後続の release ワークフローを起動する Release を作成できません（GitHub は GITHUB_TOKEN によって起動されるワークフローの実行をブロックします）。そのため、PAT がないと何も公開されません。シークレットが未設定の場合、ワークフローは GITHUB_TOKEN にフォールバックするため、フォーク上でも PR の CI は引き続き動作します。

ロードマップ

• リモート／モバイルでの利用に向けた Streamable HTTP トランスポートと OAuth2
• 主要メトリクスの視覚的なレンダリング

ライセンス

MIT