Beszel MCP Server

A Model Context Protocol (MCP) server for the Beszel system monitoring tool.

Overview

This MCP server provides tools to interact with Beszel's PocketBase backend, allowing you to:

• List systems, containers, alerts, and alert history
• Query system statistics
• Query container statistics

Built with FastMCP - A high-level Python framework for building MCP servers with minimal boilerplate. See Why FastMCP? for details.

Works great with uv - The blazing-fast Python package manager. See uv Quick Start for a 2-minute setup!

Installation

Using uv (Recommended)

uv is a fast Python package manager that handles virtual environments automatically:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install the project
uv pip install -e .

# Or run directly without installing
uv run python -m beszel_mcp

Using pip

pip install -e .

Or install directly from the dependencies:

pip install fastmcp httpx

Configuration

The server requires the following environment variables:

• BESZEL_URL: The URL of your Beszel/PocketBase instance (e.g., http://localhost:8090)
• BESZEL_EMAIL (optional): Admin email for authentication
• BESZEL_PASSWORD (optional): Admin password for authentication

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

Using uv (recommended):

{
  "mcpServers": {
    "beszel": {
      "command": "uvx",
      "args": ["--from", "/path/to/beszel-mcp", "beszel-mcp"],
      "env": {
        "BESZEL_URL": "http://localhost:8090",
        "BESZEL_EMAIL": "your-email@example.com",
        "BESZEL_PASSWORD": "your-password"
      }
    }
  }
}

Or using Python directly:

{
  "mcpServers": {
    "beszel": {
      "command": "python",
      "args": ["-m", "beszel_mcp"],
      "env": {
        "BESZEL_URL": "http://localhost:8090",
        "BESZEL_EMAIL": "your-email@example.com",
        "BESZEL_PASSWORD": "your-password"
      }
    }
  }
}

Standalone

export BESZEL_URL="http://localhost:8090"
export BESZEL_EMAIL="your-email@example.com"
export BESZEL_PASSWORD="your-password"

# Using uv (recommended)
uv run beszel-mcp

# Or with python -m
uv run python -m beszel_mcp

# Without uv
python -m beszel_mcp

# Or use fastmcp's CLI
fastmcp run src/beszel_mcp/server.py

Available Tools

list_systems

List all monitored systems.

Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 50)
• filter (optional): PocketBase filter string
• sort (optional): Sort order (e.g., "-created")

list_containers

List all monitored containers.

Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 50)
• filter (optional): PocketBase filter string
• sort (optional): Sort order

list_alerts

List all alerts.

Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 50)
• filter (optional): PocketBase filter string
• sort (optional): Sort order

list_alert_history

List alert history.

Parameters:

• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 50)
• filter (optional): PocketBase filter string
• sort (optional): Sort order

query_system_stats

Query statistics for a specific system.

Parameters:

• system_id (required): The system ID
• start_time (optional): Start time for statistics (ISO 8601 format)
• end_time (optional): End time for statistics (ISO 8601 format)
• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 100)

query_container_stats

Query statistics for a specific container.

Parameters:

• container_id (required): The container ID
• start_time (optional): Start time for statistics (ISO 8601 format)
• end_time (optional): End time for statistics (ISO 8601 format)
• page (optional): Page number (default: 1)
• per_page (optional): Results per page (default: 100)

PocketBase Filter Examples

# Filter by name
filter="name ~ 'server'"

# Filter by status
filter="status = 'active'"

# Filter by date range
filter="created >= '2024-01-01' && created <= '2024-12-31'"

# Complex filters
filter="(cpu > 80 || memory > 90) && status = 'active'"

Why FastMCP?

This server is built with FastMCP instead of the raw MCP SDK for several reasons:

• 35% less code - Focus on logic, not boilerplate
• Automatic schema generation - Type hints become JSON schemas
• Clean decorators - Simple @mcp.tool() instead of manual routing
• Better DX - Hot reloading, dev mode, and more

See Why FastMCP? for a detailed comparison.

License

MIT