Mcp Zabbix

MCP Zabbix

Zabbix 監視 API と、Claude Desktop、Cursor などの AI アシスタントや、その他の MCP 互換クライアントを橋渡しする、本番環境向けの Model Context Protocol サーバーです。非同期 httpx クライアント、型付き Pydantic モデル、構造化ログ、オンディスクの PNG とインライン表示用の base64 ペイロードの両方を返すトレンドグラフ描画機能を備え、FastMCP 上に構築されています。

---

目次

• アーキテクチャ
• 主な機能
• 利用可能なツール
• プロジェクト構成
• クイックスタート
  • ローカル（pip）
  • ローカル（uv）
  • Docker
• 設定
• MCP クライアントのセットアップ
• 使用例
• 開発
• ライセンス

---

アーキテクチャ

                       ┌─────────────────────────────────────┐
                       │       AI Assistant / MCP Client     │
                       │   (Claude Desktop, Cursor, etc.)    │
                       └────────────────┬────────────────────┘
                                        │
                                        │   MCP stdio (JSON-RPC)
                                        ▼
        ┌──────────────────────────────────────────────────────────┐
        │                   FastMCP server (main.py)               │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │  @mcp.tool registrations  →  async handlers        │  │
        │  └────────────────────────────────────────────────────┘  │
        │            │                  │                 │        │
        │            ▼                  ▼                 ▼        │
        │  ┌──────────────────┐  ┌────────────┐  ┌──────────────┐  │
        │  │  ZabbixClient    │  │  Email     │  │  Graph       │  │
        │  │  (httpx async,   │  │  (smtplib  │  │  (matplotlib │  │
        │  │   retry, auth)   │  │   thread)  │  │   PNG+b64)   │  │
        │  └────────┬─────────┘  └─────┬──────┘  └──────┬───────┘  │
        │           │                  │                │          │
        │  ┌────────┴──────────────────┴────────────────┴──────┐   │
        │  │  core/  : Settings  •  Logger  •  Exceptions      │   │
        │  └───────────────────────────────────────────────────┘   │
        └────────────┬────────────────────────┬────────────────────┘
                     │                        │
                     ▼                        ▼
            ┌────────────────┐        ┌──────────────────┐
            │ Zabbix API     │        │  SMTP (Gmail)    │
            │ (JSON-RPC)     │        │                  │
            └────────────────┘        └──────────────────┘

AI アシスタントからのリクエストは MCP stdio 経由で届き、非同期ツールハンドラーにルーティングされた後、サービスレイヤー（ZabbixClient、メール、グラフ）に委譲されます。すべてのレイヤーは、単一の pydantic-settings Settings オブジェクトから設定を取得し、1 つのローテーションハンドラーを通してログを記録します。

---

主な機能

• 完全非同期 — ベアラートークン認証、設定可能なタイムアウト、一時的な障害に対する指数バックオフ再試行を備えた httpx.AsyncClient。
• 型付きの境界 — Pydantic v2 モデルが、ネットワークに送られる前にツール入力（メールアドレス、IP アドレス、時間範囲）を検証します。
• 設定の単一の信頼できる情報源 — pydantic-settings がプロセス環境変数、続いて .env から読み込みます。シークレットは SecretStr でラップされます。
• stdio に安全なログ — ローテーションファイルハンドラーと stderr ストリームを使用します（MCP プロトコルを stdout に出力することはありません）。
• グラフ描画 — PNG をディスクに保存し、さらに base64 も返すため、MCP クライアントは追加のラウンドトリップなしでインライン表示できます。
• 適切な縮退動作 — SMTP 認証情報が不足している場合、メールツールは自動的に無効になり、サーバーをクラッシュさせずに構造化エラーを返します。
• テスト済み — respx で HTTP をモックする非同期 pytest スイートがあり、CI で実際の Zabbix を用意する必要はありません。

---

利用可能なツール

ツール	シグネチャ	説明
get_zabbix_host	()	インターフェース、グループ、タグを含むホストの一覧。
get_zabbix_host_group	()	ホストグループの一覧。
get_zabbix_host_by_group	(group_id: str)	グループ内のホスト。
get_zabbix_item	(host_id: str)	ホストに設定されたアイテム。
get_zabbix_problem	()	現在の問題（新しい順）。
get_zabbix_problem_by_host	(host_id: str)	単一ホストの問題。
get_zabbix_trend	(item_id, start_time, end_time)	アイテムのトレンド行。
get_zabbix_user	()	ロールとアクセスフラグを含むユーザー。
get_zabbix_proxy	()	プロキシの一覧。
get_zabbix_ha_cluster_nodes	()	HA クラスターノードの状態。
create_zabbix_host	(hostname, ip, group_ids, ...)	ホストの作成（agent/snmp/ipmi/jmx）。
send_email_tool	(to_email, subject, body)	SMTP 経由で送信。
construct_graph	(item_id, start_time, end_time, item_name)	トレンドチャートを描画（PNG + base64）。

すべての Zabbix ツールは、JSON-RPC 応答から生の result ペイロードを返します。失敗時には例外をスローするのではなく、{"error": ..., "type": ...} 形式の構造化エラーを返します。

---

プロジェクト構成

mcp_zabbix/
├── src/mcp_zabbix/
│   ├── __init__.py
│   ├── main.py              # FastMCP entrypoint + tool registrations
│   ├── core/
│   │   ├── config.py        # pydantic-settings (env + .env)
│   │   ├── logging.py       # rotating file + stderr handlers
│   │   └── exceptions.py    # ZabbixAPIError / EmailError / GraphError
│   ├── models/
│   │   └── zabbix.py        # Pydantic schemas for tool I/O
│   └── services/
│       ├── zabbix.py        # async ZabbixClient (retry, auth)
│       ├── email.py         # SMTP wrapper (asyncio.to_thread)
│       └── graph.py         # matplotlib renderer (PNG + base64)
├── tests/
│   ├── conftest.py          # autouse env stubbing
│   ├── test_config.py
│   ├── test_zabbix_client.py  # respx-mocked HTTP
│   └── test_graph.py
├── Dockerfile               # python:3.12-slim, non-root user
├── docker-compose.yml       # mounts ./logs and ./output
├── pyproject.toml           # hatchling build, dev extras, ruff/mypy
├── requirements.txt         # mirror of runtime deps for pip users
├── run.sh                   # convenience launcher (loads .env)
├── .env.example
└── LICENSE

---

クイックスタート

前提条件

• Python 3.10 以降
• 有効な API トークンを持つ、接続可能な Zabbix サーバー
• （任意）メールツール用の Gmail／SMTP 認証情報

ローカル（pip）

git clone https://github.com/badoss/mcp_zabbix.git
cd mcp_zabbix

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate

pip install -e ".[dev]"
cp .env.example .env                 # edit ZABBIX_API_URL / TOKEN
./run.sh                             # or: mcp-zabbix

ローカル（uv）

uv は、pip に代わる高速な Rust ベースのツールです。

uv sync                              # installs runtime deps
uv sync --extra dev                  # add dev tooling
cp .env.example .env
uv run mcp-zabbix

Docker

cp .env.example .env                 # edit secrets
docker compose up --build

ログファイルと生成された PNG がホスト上に保持されるよう、./logs と ./output はコンテナにマウントされています。

---

設定

すべての設定は環境変数から読み込まれます。プロジェクトのルートにある .env ファイルは自動的に読み込まれます。全項目については、.env.example を参照してください。

Zabbix

変数	デフォルト	説明
ZABBIX_API_URL	— (必須)	api_jsonrpc.php の完全な URL です。
ZABBIX_API_TOKEN	— (必須)	Bearer トークンです（SecretStr として保存されます）。
ZABBIX_REQUEST_TIMEOUT	30	HTTP タイムアウト（秒）です。
ZABBIX_MAX_RETRIES	3	一時的な障害に対する再試行回数の上限です。

SMTP（任意）

変数	デフォルト	説明
SMTP_HOST	smtp.gmail.com	SMTP サーバーのホストです。
SMTP_PORT	587	SMTP サーバーのポート（STARTTLS）です。
SMTP_USER	empty	ログインユーザーです。メールを有効にするには必須です。
SMTP_PASSWORD	empty	ログインパスワードまたは Gmail のアプリパスワードです。
SMTP_FROM_NAME	MCP Zabbix	From ヘッダーに表示する名前です。

Gmail に関する注意： 2FA を有効にし、アプリパスワードを作成してください。 通常のアカウントパスワードは、Google の SMTP では使用できなくなっています。

実行時

変数	デフォルト	説明
LOG_LEVEL	INFO	DEBUG／INFO／WARNING／ERROR／CRITICAL。
LOG_DIR	logs	ローテーションログのディレクトリ（5 MB × 3 backups）です。
GRAPH_OUTPUT_DIR	output	トレンド PNG の出力先です。

---

MCP クライアントのセットアップ

Claude Desktop／Cursor（uv ランチャー）

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp_zabbix",
        "mcp-zabbix"
      ]
    }
  }
}

pip でインストールした仮想環境

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "/absolute/path/to/mcp_zabbix/.venv/bin/mcp-zabbix"
    }
  }
}

Docker

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "docker",
      "args": ["compose", "-f", "/absolute/path/to/docker-compose.yml", "run", "--rm", "mcp-zabbix"]
    }
  }
}

設定を編集した後、MCP クライアントを再起動してください。ツールパレットにツールが表示されます。

---

使用例

接続したら、アシスタントに自然な言葉でプロンプトを入力してください。適切なツールが自動的に選択されます。

監視対象のホストを一覧表示する

すべての Zabbix ホストと、それぞれが所属するグループを表示してください。

ホストの問題を調査する

ホスト 10084 で発生中の問題は何ですか？ 重要度ごとに分類してください。

トレンドグラフを生成する

アイテム 50134 の過去 24 時間の CPU 使用率をプロットし、グラフに「Web-01 CPU」という名前を付けてください。

construct_graph ツールは、ディスク上のパスと Base64 エンコードされた PNG を返します。ほとんどの MCP クライアントでは、グラフがインライン表示されます。

アラートメールを送信する

[email protected] に、件名「P1: DB latency」、現在の問題を説明する一文の本文でメールを送信してください。

メールツールは、成功時に {"status": "sent", ...} を返します。SMTP が設定されていない場合は、構造化されたエラー情報を返します。

---

開発

pip install -e ".[dev]"

# run the test suite (async + respx-mocked HTTP)
pytest

# lint & format
ruff check src tests
ruff format src tests

# strict type-check
mypy src

テストスイートでは、pytest-asyncio（auto モード）と respx を使って httpx をモックします。CI に実際の Zabbix サーバーは必要ありません。

ローカルの Zabbix に対してサーバーを実行するには：

cp .env.example .env
$EDITOR .env
./run.sh

---

ライセンス

MIT License のもとで公開されています。

サポート

• バグ報告と機能リクエスト： GitHub Issues
• Zabbix API リファレンス： https://www.zabbix.com/documentation/current/en/manual/api
• MCP 仕様： https://modelcontextprotocol.io