beszelscope MCP server
Commit Nov 1, 2026Lets AI assistants monitor system health, live metrics, and trends by connecting to a Beszel hub.
Also known as agrmohit/beszelscope
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 1, 2026
- License
- MIT
What is beszelscope MCP?
beszelscope lets AI assistants monitor system health, live metrics, and trends by connecting to a Beszel hub. It exposes 3 tools, such as fleet_status, system_detail, metric_history.
Summary generated from the project's README
About beszelscope MCP server
Monitoring system health and live metrics through an AI assistant is what beszelscope enables for administrators of Beszel hubs. This read-only MCP server connects your local AI client, such as Claude Desktop or Cursor, to your existing monitoring infrastructure to provide real-time insights and historical trends. Because it functions as a local program, it is designed for use with local AI harnesses rather than web-based interfaces.
Users interact with their infrastructure using plain language, allowing the assistant to utilize specific tools like fleet_status, system_detail, and metric_history. The server communicates with your Beszel hub using a dedicated read-only user token, ensuring that the AI can inspect data without the ability to modify any settings or system configurations. This setup provides a safe way to query CPU usage, memory consumption, disk health, and container status across your entire fleet.
What you can do with it
- 1Check fleet-wide healthAsk your assistant to summarize which systems are currently online and if any are experiencing problems.
- 2Analyze resource usageIdentify which specific containers are consuming the most memory on a particular host.
- 3Investigate performance spikesDetermine if there were any significant increases in CPU activity over a specific timeframe.
- 4Monitor hardware and storageVerify the physical health of drives or SSDs within your monitored systems.
Written from the project's README. Every use case is checked against a quote from it.
beszelscope MCP tools 3
Detected from the READMEfleet_statussystem_detailmetric_history
Configuration
BESZELSCOPE_TOKENBESZELSCOPE_URL
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableagrmohit/beszelscope is public and reachablegithub.com/agrmohit/beszelscope ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-01github.com/agrmohit/beszelscope ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubbeszelscope
beszelscope is a read-only MCP server for Beszel, a lightweight platform for monitoring your systems. It lets AI assistants check system health, live metrics and trends.
Requirements
- A Beszel hub that you can administer
- An AI app that runs local MCP servers. Most local AI harnesses can use it. Web based ones that expect http or sse cannot (claude.ai, chatgpt on web, mobile apps)
Table of Contents
- What you can ask
- How it works
- Install
- Connect it to your hub
- Add it to your AI app
- Configuration
- Tools
- Limits
- Beszel version
- Development
What you can ask
Ask in plain words; the assistant picks the right tool. For example:
You: How are my systems doing?
Assistant: Two of your three systems are up. The laptop has been down for 2 days and 11 hours, and the backup storage pool on web-1 is degraded.
Behind that answer, the assistant called fleet_status and got back this (shortened):
{
"as_of": "2026-10-30T22:42:22Z",
"counts": { "total": 3, "up": 2, "down": 1, "with_problems": 2 },
"systems": [
{
"name": "laptop",
"status": "down",
"last_seen_ago_s": 212538,
"problems": [{ "code": "status_down", "detail": "down for 2d 11h", "section": "summary" }]
},
{
"name": "web-1",
"status": "up",
"cpu_pct": 7,
"mem_pct": 66.8,
"disk_pct": 40.1,
"problems": [{ "code": "pool_degraded", "detail": "backup DEGRADED", "section": "disk" }]
}
]
}
More questions it can answer:
- "Which containers use the most memory on web-1?"
- "Did CPU on web-1 spike in the last 24 hours?"
- "Is the SSD on my laptop healthy?"
- "When does the certificate on my monitored site expire?"
- "Which system went down, and since when?"
How it works
flowchart LR
App["AI app<br/>(Claude Desktop, Cursor, ...)"] -->|"starts it on<br/>your computer"| BS[beszelscope]
BS -->|"read-only requests<br/>with a token"| Hub[(Beszel hub)]
Hub --- A1[agent on system 1]
Hub --- A2[agent on system 2]
Your AI app starts beszelscope in the background and talks to it directly. beszelscope reads from your Beszel hub with a token for a dedicated read-only user. It never writes to the hub.
Install
Download. Each release has one binary per platform, built by GitHub Actions from the tagged commit, with a build provenance attestation and a checksums.txt. The platforms are darwin_arm64 (Apple silicon), linux_arm64, linux_amd64, windows_arm64 and windows_amd64.
-
Download yours and check where it came from, here with the GitHub CLI.
gh attestation verifyproves the file was built by this repo's release workflow:gh release download -R agrmohit/beszelscope -p '*_<platform>*' gh attestation verify <file> -R agrmohit/beszelscope --signer-workflow agrmohit/beszelscope/.github/workflows/release.ymlOr download it from the release page and compare its SHA-256 with its line in
checksums.txt. -
Rename it to
beszelscope(keep the.exeon Windows) and move it to a folder on yourPATH. On macOS and Linux, make it executable withchmod +x beszelscope. -
The binaries are not code signed, so a copy downloaded with a browser is flagged on first run. Clear the flag with
xattr -d com.apple.quarantine <file>on macOS, orUnblock-File <file>in PowerShell on Windows. Copies fetched withghorcurlare not flagged.
With Go (1.27 or later). This installs into $(go env GOPATH)/bin:
go install github.com/agrmohit/beszelscope/cmd/beszelscope@latest
From source, on macOS and Linux. This installs into ~/.local/bin:
git clone https://github.com/agrmohit/beszelscope
cd beszelscope
make install
Check that it runs:
beszelscope version
Connect it to your hub
beszelscope signs in as its own Beszel user with the readonly role, using a long-lived token. Password login can stay switched off on your hub.
-
Create the user. As a superuser, open your hub's admin panel at
/_/, go to theuserscollection and add a user (for examplebeszelscope@example.com) with the rolereadonly. -
Share your systems. Beszel shows a user only the systems they are listed on. In
/_/, open thesystemscollection and add the new user to each system'susers. Do the same for every system you add later. -
Create a token. In
/_/, open the new user, choose Impersonate from its menu, set the duration in seconds (315360000is 10 years) and copy the token. These tokens cannot be refreshed; beszelscope warns when fewer than 30 days are left. -
Store the token.
-
On macOS, save it in your Keychain. Piping it in avoids typing errors:
pbpaste | BESZELSCOPE_URL=https://beszel.example.com beszelscope token settoken setchecks the token, asks the hub whether it works, and stores it. A failed hub check only warns. -
On Linux and Windows, put it in the
BESZELSCOPE_TOKENenvironment variable instead (see Add it to your AI app).
-
-
Check it. This shows where the token comes from, when it expires, and whether the hub accepts it:
BESZELSCOPE_URL=https://beszel.example.com beszelscope check
Renewing. Create a new token (step 3) and store it again.
Revoking. Change the user's password in /_/. That resets the user's token key, so every token for the user stops working.
Add it to your AI app
Most apps take a JSON entry like this one. Use the full path to the binary, because apps often start MCP servers without your shell's PATH:
{
"mcpServers": {
"beszelscope": {
"command": "/Users/you/.local/bin/beszelscope",
"env": {
"BESZELSCOPE_URL": "https://beszel.example.com"
}
}
}
}
- VS Code names the top-level key
serversinstead ofmcpServers. - On Windows, write the path with doubled backslashes, such as
C:\\Users\\you\\bin\\beszelscope.exe. - On Linux and Windows, add
"BESZELSCOPE_TOKEN": "<token>"underenv. The token then sits in that file in plain text, so keep the file private. - Restart the app, then try one of the sample questions.
Configuration
All settings are environment variables.
| Variable | Meaning |
|---|---|
BESZELSCOPE_URL |
Your hub's address. Required. A sub-path such as https://example.com/beszel works. |
BESZELSCOPE_TOKEN |
The token, when it is not in the macOS Keychain. Setting both is an error. |
BESZELSCOPE_ALLOW_INSECURE_HTTP |
1 or true allows plain http:// to a hub on another machine. http://localhost always works. |
BESZELSCOPE_LOG_LEVEL |
debug, info (the default), warn or error. Logs go to stderr as JSON. |
OTEL_EXPORTER_OTLP_ENDPOINT |
Turns on export of OpenTelemetry traces and logs over OTLP/HTTP. The other standard OTEL_* variables tune it but do not turn it on. |
beszelscope check works on every system. The token commands manage the Keychain and exist only on macOS. None of them ever prints a token.
| Command | What it does |
|---|---|
beszelscope check |
Shows the hub, where the token comes from and when it expires, then checks both with the hub. |
beszelscope token set |
macOS: stores the token for BESZELSCOPE_URL's host, from a pipe or a prompt. One token per host name. |
beszelscope token list |
macOS: lists the hubs that have a stored token. |
beszelscope token delete |
macOS: removes the token for BESZELSCOPE_URL. |
Tools
beszelscope gives the assistant three tools. Every answer carries one as_of time; all other times are ages in seconds, and sizes are plain byte counts.
| Tool | What it answers |
|---|---|
fleet_status |
One line per system: status, CPU, memory, fullest disk, temperature, load and uptime. It flags problems such as a system down, failed services, unhealthy or stopped containers, failing drives, degraded storage pools, packet loss, expiring certificates and pending security updates. |
system_detail |
Everything about one system, in the same sections as Beszel's own pages: summary, core (CPU, memory, sensors), network, disk, GPU, containers, services and updates. Long container and service lists can be filtered, sorted and capped. |
metric_history |
Trends for up to five systems over the last hour, 12 hours, day, week or 30 days: average, low, high, latest value and how much of the period has data. |
Limits
Never supported, by design
- Changing anything. No pausing systems, adding systems or editing settings. beszelscope only reads, so an AI app cannot break your monitoring.
- Alerts. Beszel alerts belong to the user who created them, so the read-only user cannot see yours. Problems come from what Beszel records anyway, such as a failed service or a failing drive.
- Running online. beszelscope runs only as a local program that your AI app starts. There is no hosted mode, so it will not work from claude.ai in a browser or other web apps.
- Password login. It signs in only with a user token, never with a username and password. Superuser tokens are refused.
Worth knowing
- Token storage on macOS. It uses Apple's
securitytool, so any program running as you can read the token without a prompt. That avoids password dialogs and code signing. The token can only read, but it can read everything the beszelscope user can see. - Package updates. They are reported only for systems whose Beszel agent runs directly on Linux, not in a container. beszelscope says when that is why a system has none.
- Containers. Only running ones appear. Beszel forgets a stopped container within 10 minutes; beszelscope lists those that stopped in the last hour.
- Short spikes. They can hide in long periods. Beszel keeps true peaks for CPU, memory, total network traffic, disk activity and monitor latency. Other readings, such as temperature or a single network interface, are averaged over each time slot.
Beszel version
beszelscope was built and tested against Beszel 0.21.1. A newer hub usually works, but anything Beszel added after it will not appear until beszelscope supports it.
Development
make # list every target
make check # tidy, lint, race tests, vulnerability, secret and workflow scans
make build # build bin/beszelscope with the version stamped in
- Tests use recordings from a real hub, with names and addresses replaced (
make fixtures). They never touch the network. - Releases are
vX.Y.Ztags on a commit that hasdocs/releases/vX.Y.Z.md.make release-check TAG=vX.Y.Zchecks both. Pushing the tag runs CI, then the release workflow builds the binaries (make dist), attests them and publishes the release.
License
beszelscope MCP questions
What tools does beszelscope MCP provide?
It exposes 3 tools, including fleet_status, system_detail, metric_history.
Can the AI assistant change my system settings?
No, the server is read-only by design to ensure the AI cannot break your monitoring or change any settings.
Does this work with web-based AI clients like Claude.ai?
No, it only works with local AI applications that can run local MCP servers; web-based clients expecting HTTP or SSE are not supported.
How does the server authenticate with Beszel?
It uses a long-lived token for a dedicated read-only user and does not support username and password login.