skywalking-zabbix-mcp

# Tool List [](https://github.com/ningjiabing/skywalking-zabbix-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/skywalking-zabbix-mcp/) [](https://pypi.org/project/skywalking-zabbix-mcp/) [](LICENSE) English | [简体中文](README.md) An MCP Server that integrates **SkyWalking (Application APM)** and **Zabbix (Host Monitoring)** into a single process, enabling AI assistants to view application and machine metrics in a single conversation and correlate them. **What problem does it solve?** When troubleshooting, you usually need to open two systems: SkyWalking to see where the service is slow, and Zabbix to see if the machine is overwhelmed. Then, you manually correlate the timelines to determine if the machine or application issue came first. This server automates this step, allowing you to ask a question like "what's wrong with payment-service" and get a conclusion that correlates application and machine data. **Why can it automatically correlate?** SkyWalking service names are in the format `<IP>::<service name>` (e.g., `192.0.2.11::payment-service`), where the IP segment matches the hostname in Zabbix. This natural alignment using IP addresses **eliminates the need to maintain a service↔host mapping table**. <p align="center"> <img src="docs/demo.svg" alt="diagnose_service 与 correlate_incident 的实际输出" width="100%"> </p> <p align="center"> _{Actual server code runs on a <a href="docs/demo/">mock backend</a>, with synthetic data. Use <code>uv run python docs/demo/run_demo.py</code> to reproduce.} </p> --- ## Two Running Forms | Configuration | Resulting Server | |---|---| | Only configure `SW_*` | **Pure SkyWalking**: 16 tools + 10 prompts + 4 resources | | Add `ZABBIX_URL` etc. | **Application + Machine Integrated**: 16 (above) + Zabbix 2 + Cross-Stack Correlation 2 = **20 tools** | In other words, **only when `ZABBIX_URL` is configured will Zabbix and correlation-related tools be registered**, otherwise, it degrades to a pure SkyWalking server. --- ## Quick Start ### 1. Installation (Choose One) **A. uvx — No cloning, run in one line (recommended)** ```bash uvx skywalking-zabbix-mcp --version ``` **B. Docker** ```bash docker run --rm -i \ -e SW_URL=http://<oap-host>:12800 \ ghcr.io/ningjiabing/skywalking-zabbix-mcp ``` **C. Source Code (for code changes)** ```bash git clone https://github.com/ningjiabing/skywalking-zabbix-mcp.git cd skywalking-zabbix-mcp uv sync uv run skywalking-zabbix-mcp --version ``` ### 2. Connect to AI Client <details open> <summary><b>Claude Code</b></summary> ```bash claude mcp add obs -s user \ -e SW_URL=http://<oap-host>:12800 \ -e ZABBIX_URL=http://<zabbix-host>/zabbix/api_jsonrpc.php \ -e ZABBIX_USER=<user> -e ZABBIX_PASSWORD='${MY_ZBX_PWD}' \ -e READ_ONLY=true \ -- uvx skywalking-zabbix-mcp ``` </details> <details> <summary><b>Claude Desktop</b>（<code>claude_desktop_config.json</code>）</summary> ```json { "mcpServers": { "obs": { "command": "uvx", "args": ["skywalking-zabbix-mcp"], "env": { "SW_URL": "http://<oap-host>:12800", "ZABBIX_URL": "http://<zabbix-host>/zabbix/api_jsonrpc.php", "ZABBIX_USER": "<user>", "ZABBIX_PASSWORD": "${MY_ZBX_PWD}", "READ_ONLY": "true" } } } } ``` </details> <details> <summary><b>Cursor</b>（<code>.cursor/mcp.json</code> or global <code>~/.cursor/mcp.json</code>）</summary> ```json { "mcpServers": { "obs": { "command": "uvx", "args": ["skywalking-zabbix-mcp"], "env": { "SW_URL": "http://<oap-host>:12800", "READ_ONLY": "true" } } } } ``` </details> <details> <summary><b>Codex CLI</b>（<code>~/.codex/config.toml</code>）</summary> ```toml [mcp_servers.obs] command = "uvx" args = ["skywalking-zabbix-mcp"] [mcp_servers.obs.env] SW_URL = "http://<oap-host>:12800" ZABBIX_URL = "http://<zabbix-host>/zabbix/api_jsonrpc.php" ZABBIX_USER = "<user>" READ_ONLY = "true" ``` Equivalent command-line usage: ```bash codex mcp add obs -- uvx skywalking-zabbix-mcp ``` Note that Codex's configuration is in TOML, with key names `mcp_servers` (underscore), unlike Claude/Cursor's JSON `mcpServers`. It's recommended to keep credentials in shell environment variables, inherited by the Codex process, rather than writing them in `config.toml`. </details> <details> <summary><b>VS Code</b>（<code>.vscode/mcp.json</code>）</summary> ```json { "servers": { "obs": { "type": "stdio", "command": "uvx", "args": ["skywalking-zabbix-mcp"], "env": { "SW_URL": "http://<oap-host>:12800", "READ_ONLY": "true" } } } } ``` </details> <details> <summary><b>Source Code</b> (replace `uvx skywalking-zabbix-mcp` with an absolute path)</summary> ```json { "command": "uv", "args": ["--directory", "/absolute/path/skywalking-zabbix-mcp", "run", "skywalking-zabbix-mcp"] } ``` </details> > Credentials are recommended to be referenced using `${ENV}` (see [Configuration](#configuration)), avoiding plaintext. See `.env.example` for all variables. ### 3. Run Directly (stdio / HTTP) ```bash uvx skywalking-zabbix-mcp # stdio, default uvx skywalking-zabbix-mcp sse --port 8000 uvx skywalking-zabbix-mcp streamable --port 8000 --path /mcp ``` > ⚠️ **sse / streamable have no authentication**, binding to `127.0.0.1` by default. Binding to other addresses exposes OAP and Zabbix read permissions (and write permissions if `READ_ONLY` is not enabled) to anyone who can connect to this port. For external access, add an authentication-enabled reverse proxy or restrict access at the network layer. See [SECURITY.md](SECURITY.md) for details. ### 4. Try a Query > "Diagnose `192.0.2.11::payment-service`" The server will return the service's application metrics (cpm / response time / SLA + alarms) and host metrics (CPU / memory / IO + current problem) in one go using `diagnose_service`. --- ## Tool Overview ### SkyWalking (16, any configuration) | Category | Tool | Effect | |---|---|---| | **Metadata** | `list_layers` `list_services` `list_instances` `list_endpoints` `list_processes` | List layers / services / instances / endpoints / processes | | **Topology** | `query_services_topology` `query_instances_topology` `query_endpoints_topology` `query_processes_topology` | Four-level call topologies | | **Trace** | `query_traces` | Query traces, supporting summary / errors_only / full views, automatic v1/v2 protocol selection | | **Metrics** | `execute_mqe_expression` `list_mqe_metrics` `get_mqe_metric_type` | Run MQE expressions, list available metrics, query metric types | | **Alarms/Events/Logs** | `query_alarms` `query_events` `query_logs` | Query alarms, events, logs | ### Zabbix (2, with `ZABBIX_URL` configured) | Tool | Effect | |---|---| | `zabbix_query` | Execute arbitrary Zabbix JSON-RPC methods (`host.get` / `item.get` / `problem.get` / `history.get`…). Read-only mode allows only `*.get` methods | | `zabbix_list` | List common methods + real-time API version detection | ### Cross-Stack Correlation (2, with `ZABBIX_URL` configured) | Tool | Effect | |---|---| | `diagnose_service` | Pass SkyWalking service name, retrieve **application-side** (cpm / resp_time / sla + alarms) + **machine-side** (host's CPU/memory/IO + current problem) | | `correlate_incident` | Align alarms within a time window, determine if "machine issues first" or "application issues first" | ### Additional - **10 prompts** (troubleshooting guidance): `analyze-performance` `compare-services` `top-services` `investigate-traces` `trace-deep-dive` `analyze-logs` `explore-service-topology` `generate_duration` `build-mqe-query` `explore-metrics` - **4 resources** (MQE documentation): `mqe://docs/syntax`, `mqe://docs/examples`, `mqe://docs/ai_prompt` (static), `mqe://metrics/available` (dynamic, real-time backend metrics) --- ## Configuration All through environment variables. Credential classes support `${ENV}` expansion (e.g., `SW_PASSWORD=${MY_SW_PWD}`), avoiding plaintext. See `.env.example` for an example. | Variable | Description | Default | |---|---|---| | `SW_URL` | OAP address, automatically appends `/graphql` | `http://localhost:12800/graphql` | | `SW_USERNAME` / `SW_PASSWORD` | SkyWalking Basic Auth | Empty | | `SW_INSECURE` | Skip TLS verification (only for testing) | `false` | | `SW_LOG_LEVEL` | Log level | `info` | | `ZABBIX_URL` | Zabbix `api_jsonrpc.php` full path. **Configured only when enabled Zabbix + correlation tools** | Empty (disabled) | | `ZABBIX_USER` / `ZABBIX_PASSWORD` | Zabbix credentials | Empty | | `READ_ONLY` | Read-only guard: intercept all non-`*.get` write methods for Zabbix | `false` | | `VERIFY_SSL` | Zabbix TLS verification | `true` | | `ZABBIX_SKIP_VERSION_CHECK` | Compatibility placeholder (no-op) | `false` | > **`ZABBIX_URL` path should not be incorrect**: if installed in a subdirectory, use `http://host/zabbix/api_jsonrpc.php`, if installed in the root path, use `http://host:port/api_jsonrpc.php`. Incorrect configuration results in a 404 error. See the complete JSON configuration in the [Connect to AI Client](#2-connect-to-ai-client) section. --- ## Typical Usage | Scenario | How to | |---|---| | **One sentence to see service overview** | `diagnose_service("192.0.2.11::payment-service")` — application metrics + alarms + host metrics + problems, all at once | | **Determine who caused the issue first** | `correlate_incident(time window)` — align alarms on both sides by time, determine machine or application issues | | **Drill down into traces to find bottlenecks** | `query_traces` pull slow/error traces, use `trace-deep-dive` prompt to locate time-consuming spans | | **Run metric expressions** | `execute_mqe_expression`; if unsure, read `mqe://docs/syntax` or use `build-mqe-query` prompt | --- ## Compatibility **Compatible with new and old OAP** — automatically detect backend version and schema capabilities, adjust queries accordingly: - Version detection (`version` → major.minor): metadata / endpoints / trace use v1 or v2 queries based on version. - Schema capability detection (introspection): alarm / MQE adjust selection sets based on actual backend fields, avoiding old version verification errors. - MQE old syntax rewriting: `service_percentile{p='50,90'}` → `{_='0,2'}`, return results and restore to `p` label. - `coldStage` only issued when requesting cold data (old OAP does not have this field). **Zabbix 4.0 compatible** — PHP pollution response denoising, `user` login parameter, body `auth` field, `/zabbix/` subdirectory, all automatically processed. **Security** — SkyWalking's 16 tools are read-only queries; with `READ_ONLY=true`, Zabbix side only allows `*.get` methods, intercepting all write methods. Read [SECURITY.md](SECURITY.md) before deployment: credential management, HTTP transport without authentication, tool output flowing to LLM, all require evaluation based on your environment. **Minimal dependencies** — only `fastmcp` + `httpx`. --- ## Development ```bash uv sync # Install runtime + development dependencies uv run pre-commit install # ruff / private key detection / gitleaks uv run ruff check . && uv run ruff format --check . uv run mypy uv run pytest --cov ``` Test coverage includes GraphQL client authentication and error handling, backend version/capability detection and caching, trace v1/v2 protocol selection and three views, MQE old syntax rewriting, Zabbix login/re-login/read-only guard/PHP pollution denoising, and end-to-end paths for two cross-stack correlation tools, as well as the contract itself: pure SkyWalking 16 tools, adding Zabbix to 20 tools. Contribution process see [CONTRIBUTING.md](CONTRIBUTING.md). ## License Apache License 2.0, see [`LICENSE`](LICENSE) / [`NOTICE`](NOTICE). Change records see [CHANGELOG.md](CHANGELOG.md). SkyWalking-related query text source from Apache SkyWalking project, cross-language transplantation retains original permission.