# Beszel MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Beszel](https://github.com/henrygd/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](https://github.com/raycast/extensions/tree/master/extensions/beszel-extension) and inspired by [Red5d/beszel-mcp](https://github.com/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:

```bash
npx -y beszel-mcp
```

## Usage

### Cursor / Claude Desktop

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

```json
{
  "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

```bash
npm install
npm run build
npm start
```

Or run without building:

```bash
npm install
npm run dev
```

### MCP Inspector

```bash
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