Skip to main content
Glama
Beszel MCP Server

Beszel MCP Server

by Red5d

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!

Related MCP server: pocketbase-mcp

Installation

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

Available Tools

6 tools
list_alert_historyA

List alert history in Beszel.

Args: page: Page number (default: 1) per_page: Number of results per page (default: 50) filter: PocketBase filter string sort: Sort order (e.g., "-created" for most recent first)

Returns: Dictionary containing historical records of triggered alerts

Inputs: page, per_page, filter, sort. Returns: object

list_alertsB

List all configured alerts in Beszel.

Args: page: Page number (default: 1) per_page: Number of results per page (default: 50) filter: PocketBase filter string sort: Sort order

Returns: Dictionary containing alert configurations including thresholds and notification settings

Inputs: page, per_page, filter, sort. Returns: object

list_containersB

List all monitored containers in Beszel.

Args: page: Page number (default: 1) per_page: Number of results per page (default: 50) filter: PocketBase filter string sort: Sort order

Returns: Dictionary containing paginated list of containers running on monitored systems

Inputs: page, per_page, filter, sort. Returns: object

list_systemsB

List all monitored systems in Beszel.

Args: page: Page number (default: 1) per_page: Number of results per page (default: 50) filter: PocketBase filter string (e.g., "name ~ 'server'" or "status = 'active'") sort: Sort order (e.g., "-created" for descending by created date)

Returns: Dictionary containing paginated list of systems with their status and metadata

Inputs: page, per_page, filter, sort. Returns: object

query_container_statsB

Query statistics for a specific container.

Args: container_id: The container ID to query statistics for start_time: Start time in ISO 8601 format (e.g., '2024-01-01T00:00:00Z') end_time: End time in ISO 8601 format page: Page number (default: 1) per_page: Number of results per page (default: 100)

Returns: Dictionary containing time-series data for container CPU, memory, and network usage

Inputs: container_id (required), start_time, end_time, page, +1 more. Returns: object

query_system_statsB

Query statistics for a specific system.

Args: system_id: The system ID to query statistics for start_time: Start time in ISO 8601 format (e.g., '2024-01-01T00:00:00Z') end_time: End time in ISO 8601 format page: Page number (default: 1) per_page: Number of results per page (default: 100)

Returns: Dictionary containing time-series data for CPU, memory, disk, and network usage

Inputs: system_id (required), start_time, end_time, page, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: list_alert_history retrieves historical records, list_alerts shows configurations, list_containers and list_systems enumerate monitored entities, and query_container_stats/query_system_stats fetch specific time-series data. The descriptions make it unambiguous which tool to use for each task.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern with snake_case: list_alert_history, list_alerts, list_containers, list_systems, query_container_stats, and query_system_stats. The naming convention is predictable and readable throughout the set.

    Tool Count5/5

    With 6 tools, this server is well-scoped for monitoring systems and containers, covering listing entities and querying statistics. Each tool earns its place without being too sparse or bloated, fitting typical MCP server ranges.

    Completeness4/5

    The toolset provides solid read-only coverage for monitoring: listing alerts, containers, systems, and querying their stats. Minor gaps exist, such as no tools to create/update/delete alerts or containers, but agents can work around this for observation-focused workflows.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      Enables managing PocketBase instances through intent-first tools for schema inspection, record CRUD, bulk operations, authentication, file handling, and server monitoring, with optional destructive operations gated behind explicit opt-in.
      11
      15
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables LLM clients to run advanced operations against a PocketBase backend, including creating and inspecting collections, CRUD on records with filtering and pagination, user authentication and account creation, and database backups. It also supports local stdio and Docker-based deployment with admin credentials configured via environment variables.
      18 npm
      ISC
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables sophisticated interaction with PocketBase databases through the Model Context Protocol, including collection schema creation and retrieval, record CRUD with filtering, pagination and relationship expansion, user authentication and account management, and database backups. It can run locally or in Docker with configurable URL and admin credentials.
      18 npm
      ISC