Zabbix Mcp

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 MCP_SETUP.md 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