openHop MCP Server
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
openHop MCP Server plugin
An openHop Repeater plugin that exposes mesh telemetry as a Model Context Protocol server over Streamable HTTP.
Installs entirely locally — no catalogue submission or PR required. See the upstream guide: "You can upload a wheel to your own test installation without a catalogue listing or PR."
Security model
The MCP endpoint is protected by two independent, fail-closed controls:
Source IP allowlist — the TCP peer address must fall inside a configured CIDR. Requests from anywhere else get
403.Bearer token with role — every request needs
Authorization: Bearer <token>(orX-Auth-Token: <token>). Missing or wrong tokens get401.
GET /healthz is exempt from the token check but still requires an allowed
source address. It returns only {"status":"ok"}.
Multiple keys and roles
You can issue several tokens, each with a name and a role:
read— telemetry tools only. This is what a dashboard, Grafana, or an AI assistant should use.admin— telemetry plus mutating tools. Only granted whenread_onlyisfalse.
Role enforcement happens per request inside the plugin. A read token cannot
call a write tool even if the tool is registered — the handler returns a
permission error without touching the Repeater API. Call openhop_whoami to see
which identity and role a token has.
Configure all credentials in the auth_tokens list. Each entry takes a
name, a role (read or admin), and either a token or, preferably, a
token_sha256. With hashes, the config file holds nothing a thief could replay.
The plugin only ever keeps SHA-256 digests in memory and compares them in
constant time.
Minting and rotating tokens
The wheel ships an openhop-mcp-token command:
openhop-mcp-token mint --name grafana --role readIt prints the token once (give it to the client) and a ready-to-paste
auth_tokens entry holding only token_sha256. To hash a token you already
have: echo -n "$TOKEN" | openhop-mcp-token hash.
To rotate, mint a new token under the same name, replace the config entry, restart the plugin, then update the client. The old token stops working at the restart.
Audit log and rate limits
Every tool call, resource read and prompt fetch is written as one JSON line to
<plugin data>/audit.log (mode 0600, rotated at audit_log_max_bytes, five
backups). Each record has the time, token name, role, source IP, operation,
arguments (secrets redacted, long values truncated), outcome and duration.
Results are never logged, so channel message content stays off disk.
Each token gets rate_limit_per_minute operations per minute, with bursts up to
the same number. Over the limit, calls fail with a "rate limit exceeded" error
saying how long to wait. Set it to 0 to turn limiting off.
Additional guardrails:
Binding to a non-loopback address requires
allow_insecure_bind: true, so a careless edit cannot quietly expose the plugin to the LAN.An empty or
0.0.0.0/0allowlist is rejected unless the same flag is set.If no token is configured, the plugin generates a random admin token on first start and writes it to
<plugin data>/auth_token.txtwith mode0600.Tokens shorter than 16 characters and duplicate token values are rejected at startup.
Failed authentication is throttled per source IP: 10 failures inside 5 minutes triggers a 15-minute lockout (
429withRetry-After). A successful request clears the counter.The Repeater API key is never logged or forwarded to clients.
Secret-looking fields (passwords, secrets, tokens, API keys, private keys, PSKs, JWTs) are redacted from every Repeater response before it reaches a client.
/api/statsembeds MQTT broker config, for example.Read-only mode defaults to true. Write tools are not even registered unless the operator sets
read_only: false.
Note: openHop plugin API tokens are administrator-equivalent. The plugin needs one to read most endpoints. Treat its config file accordingly.
Related MCP server: Universal Host Manager MCP
Configuration
The plugin manager seeds config.json in the plugin's persistent data directory
from the manifest defaults. Edit it via the Repeater's Plugins page or
POST /api/plugins/settings, then restart the plugin.
Key | Default | Notes |
|
| Bind address. Non-loopback needs |
|
| MCP endpoint port. |
|
| Repeater REST API base URL. |
|
| Repeater |
|
| List of |
|
| CIDRs allowed to connect. |
|
| When false, advert/mode tools are registered. |
|
| Upstream request timeout. |
|
| Hard cap for list-returning tools. |
|
| Acknowledge LAN exposure / wide allowlists. |
|
| Failed auth attempts allowed per source IP within the window. |
|
| Sliding window for counting failures. |
|
| Lockout duration once the failure limit is hit. |
|
| Repeater SQLite database, read-only. |
|
| Register the channel-history tools. Content stays admin-only. |
|
| How long Repeater GET responses are reused (0 to 300). |
|
| Write |
|
| Rotate the audit log at this size. |
|
| Operations per minute per token. |
After changing config, restart the plugin (settings writes with restart: true
do this automatically).
Tools
Tool | Purpose |
| Compact typed overview: identity, counters, noise floor, duty cycle, GPS. |
| The full |
| Neighbour list, optional zero-hop filter and sorting. |
| Recent packets with type/route filters. |
| Packet counters for N hours. |
| Counts grouped by packet type. |
| Counts grouped by route type. |
| Noise floor statistics. |
| GPS diagnostics and NMEA attributes. |
| Host CPU/RAM/disk/temperature stats. |
| Repeater application logs, filterable by level or id. |
| Host process CPU/memory usage. |
| MQTT bridge and per-broker connection state. |
| Configured web frontends and selection. |
| Radio presets, serial ports, site info, hardware options. |
| Room-server messages (not channel chat). |
| Channel names and indices from the Repeater DB. No secrets. |
| Admin-only. Decrypted channel history from the Repeater DB (max 90 days per call). |
| GET against an explicit allowlist of telemetry |
| One neighbour's RSSI/SNR spread, SNR trend, gaps and duplicate ratio. Without |
| Per-minute transmit airtime vs the duty-cycle limit, plus receive load. |
| Noise-floor spikes and dips, found with a median/MAD robust z-score. |
| Name and role of the calling token. |
| Admin-only. Validate the Repeater's |
| Write, admin, only when |
| Write, admin, only when |
| Write, admin, only when |
| Write, admin, only when |
| Write, admin, only when |
| Write, admin, only when |
| Write, admin, only when |
Every tool carries MCP annotations (readOnlyHint, destructiveHint,
idempotentHint, openWorldHint) so clients can tell reads from writes. Tools
that build their own output return typed models, so clients get an
outputSchema and structuredContent. Failures come back as isError: true
with a readable message.
Resources
URI | Contents |
| Same compact overview as |
| Neighbour table, most recently heard first. |
| Channel names and indices (only when history is enabled). |
Prompts
Prompt | What it does |
| Walks through stats, airtime, noise, neighbours, logs and hardware, then gives a verdict and the top three issues. |
| Takes a node name and works out whether a weak link is distance, interference or the neighbour dropping out. |
| Summarises recent chat on one channel by topic (admin token needed). |
openhop_api_read only reaches the telemetry paths listed in
src/openhop_mcp/api_policy.py (stats, packets, noise floor, airtime, CRC,
neighbour links, rooms, MQTT status and similar). Everything else is refused,
including plugin settings, config export, identity export, transport keys,
auth tokens, companion data, streaming routes, and GET handlers that change
state. Paths containing percent-escapes, dot segments or doubled slashes are
rejected rather than decoded.
Client configuration
Point an MCP client at http://<host>:<port>/mcp and send the bearer token in the
Authorization header. Example for an MCP client that accepts headers:
{
"mcpServers": {
"openhop": {
"type": "streamable-http",
"url": "http://<repeater-host>:8765/mcp",
"headers": { "Authorization": "Bearer <token-from-auth_tokens>" }
}
}
}Install
Option 1 — GUI (recommended)
Download
openhop_mcp_plugin-<version>-py3-none-any.whlfrom the latest release (check it againstSHA256SUMS), or build it yourself.Open the Repeater web UI, go to Plugins, click Install plugin and choose the wheel.
Open the plugin's settings, fill in
auth_tokensandallowed_ips(see Configuration), then Enable.
No shell access needed, and the plugin manager creates and owns its venv.
Option 2 — CLI / API
Build the wheel first if you have not already:
python -m build --wheelThen upload it to the node and install by host path:
curl -X POST -H "X-API-Key: $OPENHOP_API_KEY" -H "Content-Type: application/json" \
-d '{"wheel_path":"/tmp/openhop_mcp_plugin-<version>-py3-none-any.whl"}' \
http://127.0.0.1:8000/api/plugins/installEnable and start:
curl -X POST -H "X-API-Key: $OPENHOP_API_KEY" -H "Content-Type: application/json" \
-d '{"id":"openhop.mcp"}' http://127.0.0.1:8000/api/plugins/enableCheck logs:
curl -H "X-API-Key: $OPENHOP_API_KEY" \
"http://127.0.0.1:8000/api/plugins/logs?id=openhop.mcp&tail=100"Installing a new wheel replaces the code but does not cycle the running process — disable then enable the plugin to load the new build.
Development
uv venv --python python3 .venv
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy
.venv/bin/python -m pytest -q # unit tests
.venv/bin/python tests/smoke_test.py # starts the server and checks the gate end to end
.venv/bin/python -m build --wheelThe version lives in one place, src/openhop_mcp/__init__.py. Bump
openhop-plugin.json to match; tests/test_version.py fails if they drift.
To release, bump both, merge, then publish a GitHub release tagged v<version>.
The release workflow checks that the tag matches, runs the tests, validates the
wheel against the Repeater parser, and attaches the wheel plus SHA256SUMS.
Set OPENHOP_SMOKE_LIVE=1 (and OPENHOP_BASE_URL / OPENHOP_TEST_API_KEY)
to make the smoke test require live data from a real Repeater.
Validate the wheel against the real Repeater parser without starting Repeater:
git clone --no-checkout https://github.com/openhop-dev/openhop_repeater.git repeater-source
git -C repeater-source checkout --detach <baseline-sha>
PYTHONPATH="$PWD/repeater-source" .venv/bin/python validate_wheel.pyTool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Streamable HTTP MCP gateway for NV oOS fleets — one API key, namespaced tools, quotas and policy.
Public Streamable HTTP MCP gateway for XGRChain, XDaLa sessions, Explorer data and XGR standards.
Remote MCP server exposing SMI Aware tools, resources, and skills over Streamable HTTP.
Streamable HTTP MCP server exposing planner flows, tasks, and squads.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables MCP client interaction via streamable HTTP, providing example tools (echo, getPostsByUser) and resources (posts, users) with pluggable authentication providers.6MIT
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients such as ChatGPT and Claude to administer Linux or macOS hosts through authenticated Streamable HTTP, including running shell commands, reading and writing files within a workspace, listing directories, and retrieving system metrics.MIT
- AlicenseNot gradedqualityAmaintenanceActs as a central hub that connects to multiple backend MCP resource servers and exposes their aggregated tools and resources through a unified SSE, Streamable HTTP, or Stdio interface. Provides optional web admin management, endpoint authentication, live configuration reloads, and granular per-tool controls.120 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables aggregating and routing multiple backend MCP resource servers so clients can access their combined tools and resources through a unified SSE, Streamable HTTP, or Stdio interface, with optional authentication and web-based management.120 npmMIT