zabbix_api

Instructions

This is the main tool for interacting with Zabbix. It requires multiple
iterations to achieve complex goals. Use other tools for guidance.

WORKFLOW:
1. If unsure about method/params: call zabbix_api_docs(method) first
2. If unsure about available methods: call zabbix_api_list() first
3. Execute the API call with this tool
4. If empty results or errors: iterate with different params/filters
5. Continue iterating until goal is achieved

COMMON PATTERNS:
- Finding an object requires 2+ calls (find ID, then get details)
- CPU usage example: Find host by name, get its items, filter CPU item, get history
- Empty results often mean wrong filters - try broader search first

Args:
    method: Zabbix API method (format: 'object.action').
    Examples: 'host.get', 'item.create', 'trigger.update'
    params: Method parameters (optional). For 'get' operations,
    specify 'output' to limit fields (default: ['name']).

Returns:
    JSON response from Zabbix API.

Examples:
# Simple query
zabbix_api('host.get', {'output': ['hostid', 'name']})

# Multi-step: Find host, then get items
# Step 1: Find host ID
hosts = zabbix_api('host.get', {'filter': {'host': 'my-srv-01'}, 'output': ['hostid']})
# Step 2: Get CPU items for that host
items = zabbix_api('item.get', {'hostids': ['12345'], 'search': {'name': 'CPU'}, 'output': ['itemid', 'name']})
# Step 3: Get history for specific item
history = zabbix_api('history.get', {'itemids': ['67890'], 'output': 'extend', 'history': 0, 'limit': 10})

Note:
- Use zabbix_api_docs() for method documentation
- Use zabbix_api_list() for available methods
- Iterate multiple times - complex queries need 2-5 API calls

Implementation Reference

• src/zabbix_mcp_server/server.py:82-169 (handler)

  The main zabbix_api tool handler function. Decorated with @mcp.tool(), it executes Zabbix API methods by dynamically resolving 'object.action' method strings, applying whitelist/blacklist checks, read-only enforcement, default output parameter, and calling the ZabbixAPI client.

  @mcp.tool()
  @_with_server_url
  def zabbix_api(method: str, params: Optional[Dict[str, Any]] = None) -> str:
      """Execute Zabbix API method.
  
      This is the main tool for interacting with Zabbix. It requires multiple
      iterations to achieve complex goals. Use other tools for guidance.
  
      WORKFLOW:
      1. If unsure about method/params: call zabbix_api_docs(method) first
      2. If unsure about available methods: call zabbix_api_list() first
      3. Execute the API call with this tool
      4. If empty results or errors: iterate with different params/filters
      5. Continue iterating until goal is achieved
  
      COMMON PATTERNS:
      - Finding an object requires 2+ calls (find ID, then get details)
      - CPU usage example: Find host by name, get its items, filter CPU item, get history
      - Empty results often mean wrong filters - try broader search first
  
      Args:
          method: Zabbix API method (format: 'object.action').
          Examples: 'host.get', 'item.create', 'trigger.update'
          params: Method parameters (optional). For 'get' operations,
          specify 'output' to limit fields (default: ['name']).
  
      Returns:
          JSON response from Zabbix API.
  
      Examples:
      # Simple query
      zabbix_api('host.get', {'output': ['hostid', 'name']})
  
      # Multi-step: Find host, then get items
      # Step 1: Find host ID
      hosts = zabbix_api('host.get', {'filter': {'host': 'my-srv-01'}, 'output': ['hostid']})
      # Step 2: Get CPU items for that host
      items = zabbix_api('item.get', {'hostids': ['12345'], 'search': {'name': 'CPU'}, 'output': ['itemid', 'name']})
      # Step 3: Get history for specific item
      history = zabbix_api('history.get', {'itemids': ['67890'], 'output': 'extend', 'history': 0, 'limit': 10})
  
      Note:
      - Use zabbix_api_docs() for method documentation
      - Use zabbix_api_list() for available methods
      - Iterate multiple times - complex queries need 2-5 API calls
      """
      check_method_allowed(method)
  
      if is_read_only() and not is_read_operation(method):
          raise ValueError(
              f"Server is in read-only mode - operation '{method}' is not allowed. "
              f"Only safe read operations (get, version, check, export) are permitted. "
              f"Write operations (create, update, delete) are blocked."
          )
  
      client = get_zabbix_client()
  
      if params is None:
          params = {}
  
      if method.endswith(".get") and "output" not in params:
          params = {**params, "output": ["name"]}
          logger.debug(f"Applied default output=['name'] for {method}")
  
      parts = method.split(".")
      if len(parts) != 2:
          raise ValueError(
              f"Invalid method format: '{method}'. "
              f"Expected format: 'object.action' (e.g., 'host.get', 'item.create')"
          )
  
      api_object, api_action = parts
  
      api_obj = getattr(client, api_object)
      api_method = getattr(api_obj, api_action)
  
      try:
          if params:
              result = api_method(**params)
          else:
              result = api_method()
  
          logger.info(f"Successfully executed {method}")
          return format_response(result)
  
      except Exception as e:
          logger.error(f"Error executing {method}: {e}")
          raise

• src/zabbix_mcp_server/server.py:82-83 (registration)

  Registration of the zabbix_api tool via @mcp.tool() decorator on the handler function.

  @mcp.tool()
  @_with_server_url

• src/zabbix_mcp_server/utils.py:150-168 (helper)

  check_method_allowed() - validates method against whitelist/blacklist environment variables before execution.

  def check_method_allowed(method: str) -> None:
      """Check if a Zabbix API method is allowed by whitelist/blacklist.
  
      Args:
          method: Zabbix API method name to check.
  
      Raises:
          ValueError: If the method is not allowed.
      """
      whitelist_env = get_env(EnvVars.ZABBIX_API_WHITELIST)
      blacklist_env = get_env(EnvVars.ZABBIX_API_BLACKLIST)
  
      whitelist_patterns = (
          parse_regex_patterns(whitelist_env) if whitelist_env else [re.compile(r".*")]
      )
      blacklist_patterns = parse_regex_patterns(blacklist_env)
  
      _check_blacklist(method, blacklist_patterns)
      _check_whitelist(method, whitelist_patterns, whitelist_env)

• src/zabbix_mcp_server/utils.py:32-47 (helper)

  is_read_operation() - determines if a method is a read-only operation (get, version, check, export) for read-only mode enforcement.

  def is_read_operation(method: str) -> bool:
      """Check if a Zabbix API method is a read operation.
  
      Args:
          method: Zabbix API method name (e.g., 'host.get', 'item.create')
  
      Returns:
          True if the method is a read operation, False otherwise.
      """
      if "." not in method:
          return False
  
      operation = method.split(".")[-1].lower()
      read_operations = {"get", "version", "check", "export"}
  
      return operation in read_operations

• src/zabbix_mcp_server/config.py:23-26 (schema)

  Environment variable names for the whitelist, blacklist, and timeout configuration used by the zabbix_api tool.

  ZABBIX_API_WHITELIST = "ZABBIX_API_WHITELIST"
  ZABBIX_API_BLACKLIST = "ZABBIX_API_BLACKLIST"
  ZABBIX_SKIP_VERSION_CHECK = "ZABBIX_SKIP_VERSION_CHECK"
  ZABBIX_API_TIMEOUT = "ZABBIX_API_TIMEOUT"