ry-ops/checkmk-mcp-server

CheckMK MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the CheckMK REST API. This server enables AI assistants to interact with CheckMK monitoring systems to manage hosts, folders, services, and configurations.

Features

• Host Management: Create, update, delete, rename, and list hosts
• Folder Management: Organize hosts in folders with hierarchical structure
• Service Discovery: Automatically discover and configure services on hosts
• Change Management: View and activate pending configuration changes
• Service Monitoring: List and monitor services on hosts
• Bulk Operations: Create multiple hosts in a single operation

Prerequisites

• Python 3.10 or higher
• uv package manager
• Access to a CheckMK instance (version 2.0+)
• CheckMK automation user credentials

Installation

Using uv (Recommended)

# Clone the repository
git clone https://github.com/yourusername/checkmk-mcp-server.git
cd checkmk-mcp-server

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Traditional Installation

# Clone the repository
git clone https://github.com/yourusername/checkmk-mcp-server.git
cd checkmk-mcp-server

# Install dependencies
pip install -e .

Configuration

The server requires the following environment variables:

Setting Environment Variables

Linux/macOS

export CHECKMK_URL="http://your-checkmk-server/mysite"
export CHECKMK_USERNAME="automation"
export CHECKMK_PASSWORD="your-automation-secret"
export CHECKMK_SITE="mysite"

Windows (PowerShell)

$env:CHECKMK_URL = "http://your-checkmk-server/mysite"
$env:CHECKMK_USERNAME = "automation"
$env:CHECKMK_PASSWORD = "your-automation-secret"
$env:CHECKMK_SITE = "mysite"

Using a .env file

Create a .env file in the project root:

CHECKMK_URL=http://your-checkmk-server/mysite
CHECKMK_USERNAME=automation
CHECKMK_PASSWORD=your-automation-secret
CHECKMK_SITE=mysite

Setting Up CheckMK Automation User

1. Log in to your CheckMK instance
2. Navigate to Setup → Users → Users
3. Create a new user or select an existing automation user
4. Set the user role to at least Normal monitoring user or Administrator depending on required permissions
5. Generate an automation secret under Automation secret for machine accounts
6. Save the automation secret as your CHECKMK_PASSWORD

Usage

Running the Server

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server
python server.py

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "checkmk": {
      "command": "python",
      "args": ["/path/to/checkmk-mcp-server/server.py"],
      "env": {
        "CHECKMK_URL": "http://your-checkmk-server/mysite",
        "CHECKMK_USERNAME": "automation",
        "CHECKMK_PASSWORD": "your-automation-secret",
        "CHECKMK_SITE": "mysite"
      }
    }
  }
}

Using with Other MCP Clients

The server uses stdio transport and can be integrated with any MCP-compatible client. Pass the environment variables when starting the server.

Available Tools

Host Management

• checkmk_list_hosts - List all hosts in a folder
• checkmk_get_host - Get detailed information about a specific host
• checkmk_create_host - Create a new host
• checkmk_update_host - Update host attributes
• checkmk_delete_host - Delete a host
• checkmk_rename_host - Rename a host
• checkmk_bulk_create_hosts - Create multiple hosts at once

Folder Management

• checkmk_list_folders - List all folders
• checkmk_create_folder - Create a new folder

Service Management

• checkmk_service_discovery - Run service discovery on a host
• checkmk_list_services - List all services for a host

Change Management

• checkmk_show_pending_changes - Show pending configuration changes
• checkmk_activate_changes - Activate pending changes

Resources

The server provides these resources:

• checkmk://hosts - List of all hosts
• checkmk://folders - List of all folders
• checkmk://pending-changes - List of pending changes

Examples

Create a Host

{
  "tool": "checkmk_create_host",
  "arguments": {
    "host_name": "webserver01",
    "folder": "/",
    "ipaddress": "192.168.1.100",
    "attributes": {
      "tag_agent": "cmk-agent"
    }
  }
}

Create a Folder

{
  "tool": "checkmk_create_folder",
  "arguments": {
    "name": "production_servers",
    "title": "Production Servers",
    "parent": "~",
    "attributes": {
      "tag_criticality": "prod"
    }
  }
}

Run Service Discovery

{
  "tool": "checkmk_service_discovery",
  "arguments": {
    "host_name": "webserver01",
    "mode": "refresh"
  }
}

Activate Changes

{
  "tool": "checkmk_activate_changes",
  "arguments": {
    "sites": ["mysite"],
    "force_foreign_changes": false
  }
}

Bulk Create Hosts

{
  "tool": "checkmk_bulk_create_hosts",
  "arguments": {
    "entries": [
      {
        "host_name": "server01",
        "folder": "/",
        "attributes": {
          "ipaddress": "192.168.1.101"
        }
      },
      {
        "host_name": "server02",
        "folder": "/",
        "attributes": {
          "ipaddress": "192.168.1.102",
          "labels": {
            "environment": "production",
            "team": "ops"
          }
        }
      }
    ]
  }
}

Development

Running Tests

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

Code Formatting

# Format code with black
black .

# Lint code with ruff
ruff check .

API Documentation

For detailed information about the CheckMK REST API, refer to the official documentation:

• CheckMK REST API Documentation
• Access your instance's API docs at: http://your-checkmk-server/mysite/check_mk/api/1.0/ui/

Troubleshooting

Authentication Errors

If you receive authentication errors:

1. Verify your CHECKMK_USERNAME and CHECKMK_PASSWORD are correct
2. Check that the automation user has appropriate permissions
3. Ensure the CHECKMK_URL is correct and accessible

Connection Errors

If you cannot connect to CheckMK:

1. Verify the CHECKMK_URL is accessible from your machine
2. Check firewall settings
3. Ensure CheckMK instance is running

Permission Errors

If operations fail with permission errors:

1. Verify the automation user has sufficient roles/permissions
2. Check if the user is allowed to perform the specific operation
3. Consider granting administrator role for testing

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

License

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

Acknowledgments

• Model Context Protocol by Anthropic
• CheckMK monitoring system
• uv Python package manager

Support

For issues and questions:

• Open an issue on GitHub
• Refer to CheckMK documentation
• Check MCP documentation