zabbix-mcp-server

zabbix-mcp-server

3.4

If you are the rightful owner of zabbix-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

Zabbix MCP Server is a comprehensive Model Context Protocol server designed for seamless integration with Zabbix using FastMCP and python-zabbix-utils.

Zabbix MCP Server

A comprehensive Model Context Protocol (MCP) server for Zabbix integration using FastMCP and python-zabbix-utils. This server provides complete access to Zabbix API functionality through MCP-compatible tools.

Features

šŸ  Host Management

  • host_get - Retrieve hosts with advanced filtering
  • host_create - Create new hosts with interfaces and templates
  • host_update - Update existing host configurations
  • host_delete - Remove hosts from monitoring

šŸ‘„ Host Group Management

  • hostgroup_get - Retrieve host groups
  • hostgroup_create - Create new host groups
  • hostgroup_update - Modify existing host groups
  • hostgroup_delete - Remove host groups

šŸ“Š Item Management

  • item_get - Retrieve monitoring items with filtering
  • item_create - Create new monitoring items
  • item_update - Update existing items
  • item_delete - Remove monitoring items

āš ļø Trigger Management

  • trigger_get - Retrieve triggers and alerts
  • trigger_create - Create new triggers
  • trigger_update - Modify existing triggers
  • trigger_delete - Remove triggers

šŸ“‹ Template Management

  • template_get - Retrieve monitoring templates
  • template_create - Create new templates
  • template_update - Update existing templates
  • template_delete - Remove templates

šŸšØ Problem & Event Management

  • problem_get - Retrieve current problems and issues
  • event_get - Get historical events
  • event_acknowledge - Acknowledge events and problems

šŸ“ˆ Data Retrieval

  • history_get - Access historical monitoring data
  • trend_get - Retrieve trend data and statistics

šŸ‘¤ User Management

  • user_get - Retrieve user accounts
  • user_create - Create new users
  • user_update - Update user information
  • user_delete - Remove user accounts

šŸ”§ Maintenance Management

  • maintenance_get - Retrieve maintenance periods
  • maintenance_create - Schedule maintenance windows
  • maintenance_update - Modify maintenance periods
  • maintenance_delete - Remove maintenance schedules

šŸ“Š Additional Features

  • graph_get - Retrieve graph configurations
  • discoveryrule_get - Get discovery rules
  • itemprototype_get - Retrieve item prototypes
  • configuration_export - Export Zabbix configurations
  • configuration_import - Import configurations
  • apiinfo_version - Get API version information

Installation

Prerequisites

  • Python 3.10 or higher
  • uv package manager
  • Access to a Zabbix server with API enabled

Quick Start

  1. Clone the repository:

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

  2. Install dependencies:

    uv sync

  3. Configure environment variables:

    cp config/.env.example .env
# Edit .env with your Zabbix server details

  4. Test the installation:

    uv run python scripts/test_server.py

Configuration

Required Environment Variables

  • ZABBIX_URL - Your Zabbix server API endpoint (e.g., https://zabbix.example.com)

Authentication (choose one method)

Method 1: API Token (Recommended)

  • ZABBIX_TOKEN - Your Zabbix API token

Method 2: Username/Password

  • ZABBIX_USER - Your Zabbix username
  • ZABBIX_PASSWORD - Your Zabbix password

Optional Configuration

  • READ_ONLY - Set to true, 1, or yes to enable read-only mode (only GET operations allowed)

Usage

Running the Server

With startup script (recommended):

uv run python scripts/start_server.py

Direct execution:

uv run python src/zabbix_mcp_server.py

Testing

Run test suite:

uv run python scripts/test_server.py

Read-Only Mode

When READ_ONLY=true, the server will only expose GET operations (retrieve data) and block all create, update, and delete operations. This is useful for:

  • šŸ“Š Monitoring dashboards
  • šŸ” Read-only integrations
  • šŸ”’ Security-conscious environments
  • šŸ›”ļø Preventing accidental modifications

Example Tool Calls

Get all hosts:

host_get()

Get hosts in specific group:

host_get(groupids=["1"])

Create a new host:

host_create(
    host="server-01",
    groups=[{"groupid": "1"}],
    interfaces=[{
        "type": 1,
        "main": 1,
        "useip": 1,
        "ip": "192.168.1.100",
        "dns": "",
        "port": "10050"
    }]
)

Get recent problems:

problem_get(recent=True, limit=10)

Get history data:

history_get(
    itemids=["12345"],
    time_from=1640995200,
    limit=100
)

MCP Integration

This server is designed to work with MCP-compatible clients like Claude Desktop. See for detailed integration instructions.

Docker Support

Using Docker Compose

  1. Configure environment:

    cp config/.env.example .env
# Edit .env with your settings

  2. Run with Docker Compose:

    docker compose up -d

Building Docker Image

docker build -t zabbix-mcp-server .

Development

Project Structure

zabbix-mcp-server/
ā”œā”€ā”€ src/
ā”‚   ā””ā”€ā”€ zabbix_mcp_server.py    # Main server implementation
ā”œā”€ā”€ scripts/
ā”‚   ā”œā”€ā”€ start_server.py         # Startup script with validation
ā”‚   ā””ā”€ā”€ test_server.py          # Test script
ā”œā”€ā”€ config/
ā”‚   ā”œā”€ā”€ .env.example           # Environment configuration template
ā”‚   ā””ā”€ā”€ mcp.json               # MCP client configuration example
ā”œā”€ā”€ pyproject.toml             # Python project configuration
ā”œā”€ā”€ requirements.txt           # Dependencies
ā”œā”€ā”€ Dockerfile                 # Docker configuration
ā”œā”€ā”€ docker-compose.yml         # Docker Compose setup
ā”œā”€ā”€ README.md                  # This file
ā”œā”€ā”€ MCP_SETUP.md              # MCP integration guide
ā”œā”€ā”€ CONTRIBUTING.md           # Contribution guidelines
ā”œā”€ā”€ CHANGELOG.md              # Version history
ā””ā”€ā”€ LICENSE                   # MIT license

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Running Tests

# Test server functionality
uv run python scripts/test_server.py

# Test with Docker
docker-compose exec zabbix-mcp python scripts/test_server.py

Error Handling

The server includes comprehensive error handling:

  • āœ… Authentication errors are clearly reported
  • šŸ”’ Read-only mode violations are blocked with descriptive messages
  • āœ”ļø Invalid parameters are validated
  • šŸŒ Network and API errors are properly formatted
  • šŸ“ Detailed logging for troubleshooting

Security Considerations

  • šŸ”‘ Use API tokens instead of username/password when possible
  • šŸ”’ Enable read-only mode for monitoring-only use cases
  • šŸ›”ļø Secure your environment variables
  • šŸ” Use HTTPS for Zabbix server connections
  • šŸ”„ Regularly rotate API tokens
  • šŸ“ Store configuration files securely

Troubleshooting

Common Issues

Connection Failed:

  • Verify ZABBIX_URL is correct and accessible
  • Check authentication credentials
  • Ensure Zabbix API is enabled

Permission Denied:

  • Verify user has sufficient Zabbix permissions
  • Check if read-only mode is enabled when trying to modify data

Tool Not Found:

  • Ensure all dependencies are installed: uv sync
  • Verify Python version compatibility (3.10+)

Debug Mode

Set environment variable for detailed logging:

export DEBUG=1
uv run python scripts/start_server.py

Dependencies

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

Support

Made with ā¤ļø for the Zabbix and MCP communities