beszel-mcp
A Model Context Protocol (MCP) server for Beszel — the lightweight server monitoring platform. Query your servers' health, metrics, containers, and alerts directly from Claude or any MCP-compatible client.
Features
Prerequisites
- Go 1.22+
- A running Beszel hub
- A Beszel user account (email + password)
Installation
git clone https://github.com/yourusername/beszel-mcp
cd beszel-mcp
go mod tidy
go build -o beszel-mcp .
Configuration
The server is configured entirely via environment variables:
Tip: Admin accounts can see all systems; regular users only see systems they own.
Claude Desktop Setup
Add the following to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"beszel": {
"command": "/absolute/path/to/beszel-mcp",
"env": {
"BESZEL_URL": "http://localhost:8090",
"BESZEL_EMAIL": "[email protected]",
"BESZEL_PASSWORD": "yourpassword"
}
}
}
}
Restart Claude Desktop. You should see the Beszel tools available in the tools menu.
Claude Code / Other MCP Clients
Run directly:
BESZEL_URL=http://localhost:8090 \
[email protected] \
BESZEL_PASSWORD=yourpassword \
./beszel-mcp
Or with environment file:
# .env
BESZEL_URL=http://localhost:8090
[email protected]
BESZEL_PASSWORD=yourpassword
env $(cat .env | xargs) ./beszel-mcp
Example Prompts
Once connected to Claude, try these:
- "List all my servers and their current status"
- "Which servers are down right now?"
- "Show me the CPU and memory stats for my prod-web server"
- "List all Docker containers on system
abc123xyz" - "Are there any active alerts I should know about?"
- "Find all servers with 'nginx' in the name"
- "Which servers have status down or paused?"
Tool Reference
list_systems
Lists all systems accessible to the authenticated user.
Parameters:
status_filter(optional) —"up","down","paused", or"pending"
Example output:
Found 3 system(s):
### ✅ prod-web
ID: abc123xyz
Host: 192.168.1.10:45876
Status: up
OS: Linux
Agent: v0.18.6
CPU: 12.3%
Memory: 45.1%
Disk: 61.0%
Load: 0.85 / 0.72 / 0.68
Uptime: 14d 6h 22m
search_systems
Filter systems using PocketBase filter syntax.
Parameters:
filter(required) — Filter expression
Filter examples:
get_system_stats
Detailed metrics for a single system.
Parameters:
system_id(required) — System record IDresolution(optional) — Data granularity:"1m"— most recent ~1 hour of 1-minute samples"10m"— last ~12 hours (default)"20m"— last ~24 hours"120m"— last ~7 days"480m"— last ~30 days
list_docker_containers
Lists Docker/Podman containers.
Parameters:
system_id(optional) — Limit to one system; omit for all systems
Columns: Name, CPU%, Memory (GB), Network (bytes/s), Health, Image
list_alerts
Shows alert rules and their triggered state.
Parameters:
all(optional, bool) —true= show all rules;false(default) = only triggered
Architecture
beszel-mcp/
├── main.go # Entry point, env config, server bootstrap
├── go.mod
├── internal/
│ ├── client/
│ │ └── beszel.go # PocketBase REST client, auth token cache
│ └── tools/
│ └── tools.go # MCP tool definitions and handlers
└── README.md
The client automatically handles JWT authentication and token refresh. Tokens are cached in-memory and refreshed proactively before expiry.
Security Notes
- Credentials are passed via environment variables, never hardcoded
- The JWT token is stored in memory only; never written to disk
- Use a dedicated read-only Beszel user for the MCP server where possible
- If your Beszel instance is behind a reverse proxy with TLS, use
https://inBESZEL_URL
License
MIT