Beszel MCP Server
Provides tools for interacting with Beszel's PocketBase backend to monitor systems and containers, including listing systems, containers, alerts, and alert history, as well as querying system and container statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Beszel MCP Server list all active alerts from the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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_mcpUsing pip
pip install -e .Or install directly from the dependencies:
pip install fastmcp httpxConfiguration
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 authenticationBESZEL_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.pyAvailable 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 stringsort(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 stringsort(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 stringsort(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 stringsort(optional): Sort order
query_system_stats
Query statistics for a specific system.
Parameters:
system_id(required): The system IDstart_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 IDstart_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 routingBetter DX - Hot reloading, dev mode, and more
See Why FastMCP? for a detailed comparison.
License
MIT
Available Tools
6 toolslist_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
Scored across 6 tools
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.
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.
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.
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
Manage scheduled requests, uptime monitors and heartbeats from your AI assistant.
Self-hostable uptime monitoring: create checks, read incidents, manage status pages.
Heartbeat and tokens/sec monitoring for self-hosted LLM servers (Ollama etc.), with down alerts.
Heartbeat and tokens/sec monitoring for self-hosted LLM servers (Ollama etc.), with down alerts.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceLets an LLM client monitor devices, services, disk usage, and uptime in a home network and home lab.-
- FlicenseAqualityBmaintenanceEnables 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.1115-
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmISC
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmISC