README

Beszel MCP Server

A Model Context Protocol server for the Beszel system/container monitoring tool. Run it with npx — no git clone required.

Built on the same PocketBase API used by the Beszel Raycast extension and inspired by Red5d/beszel-mcp.

Tools

Tool	Description
`list_systems`	List monitored systems with status and metadata
`list_containers`	List monitored containers
`list_alerts`	List configured alerts
`list_alert_history`	List triggered alert history
`query_system_stats`	Query CPU, memory, disk, and network stats for a system
`query_container_stats`	Query CPU, memory, and network stats for a container

All list tools support PocketBase filter, sort, and pagination.

Configuration

Set these environment variables:

Variable	Required	Description
`BESZEL_URL`	Yes	Beszel/PocketBase URL (e.g. `http://localhost:8090`)
`BESZEL_EMAIL`	No	Admin email for authentication
`BESZEL_PASSWORD`	No	Admin password for authentication

Installation

No git clone required. The server runs from the published npm package:

npx -y beszel-mcp

Usage

Cursor / Claude Desktop

Add to your MCP config. Use the npm package name beszel-mcp — not a local path:

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

Contributing / local development

npm install
npm run build
npm start

Or run without building:

npm install
npm run dev

MCP Inspector

npm run inspect

PocketBase filter examples

name ~ 'server'
status = 'up'
created >= '2024-01-01' && created <= '2024-12-31'
(cpu > 80 || memory > 90) && status = 'active'

License

MIT

beszel-mcp