Skip to main content
Glama
openHop MCP Server

openHop MCP Server

by Anquietas86

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:

  1. Source IP allowlist — the TCP peer address must fall inside a configured CIDR. Requests from anywhere else get 403.

  2. Bearer token with role — every request needs Authorization: Bearer <token> (or X-Auth-Token: <token>). Missing or wrong tokens get 401.

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 when read_only is false.

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 read

It 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/0 allowlist 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.txt with mode 0600.

  • 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 (429 with Retry-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/stats embeds 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

host

127.0.0.1

Bind address. Non-loopback needs allow_insecure_bind.

port

8765

MCP endpoint port.

openhop_base_url

http://127.0.0.1:8000

Repeater REST API base URL.

openhop_api_key

""

Repeater X-API-Key. Falls back to OPENHOP_API_KEY env var.

auth_tokens

[]

List of {name, role, token} entries. Empty = one admin token generated and persisted.

allowed_ips

["127.0.0.1/32","::1/128"]

CIDRs allowed to connect.

read_only

true

When false, advert/mode tools are registered.

request_timeout_seconds

15

Upstream request timeout.

max_items

200

Hard cap for list-returning tools.

allow_insecure_bind

false

Acknowledge LAN exposure / wide allowlists.

max_auth_failures

10

Failed auth attempts allowed per source IP within the window.

auth_failure_window_seconds

300

Sliding window for counting failures.

auth_lockout_seconds

900

Lockout duration once the failure limit is hit.

repeater_db_path

/var/lib/openhop_repeater/repeater.db

Repeater SQLite database, read-only.

allow_message_history

true

Register the channel-history tools. Content stays admin-only.

cache_ttl_seconds

3

How long Repeater GET responses are reused (0 to 300). 0 disables.

audit_log

true

Write audit.log in the plugin data directory.

audit_log_max_bytes

1000000

Rotate the audit log at this size.

rate_limit_per_minute

120

Operations per minute per token. 0 disables.

After changing config, restart the plugin (settings writes with restart: true do this automatically).

Tools

Tool

Purpose

openhop_stats

Compact typed overview: identity, counters, noise floor, duty cycle, GPS.

openhop_stats_full

The full /api/stats payload (large, secrets redacted).

openhop_neighbors

Neighbour list, optional zero-hop filter and sorting.

openhop_recent_packets

Recent packets with type/route filters.

openhop_packet_stats

Packet counters for N hours.

openhop_packet_type_stats

Counts grouped by packet type.

openhop_route_stats

Counts grouped by route type.

openhop_noise_floor

Noise floor statistics.

openhop_gps

GPS diagnostics and NMEA attributes.

openhop_hardware

Host CPU/RAM/disk/temperature stats.

openhop_logs

Repeater application logs, filterable by level or id.

openhop_processes

Host process CPU/memory usage.

openhop_mqtt_status

MQTT bridge and per-broker connection state.

openhop_web_frontends

Configured web frontends and selection.

openhop_setup_info

Radio presets, serial ports, site info, hardware options.

openhop_room_messages

Room-server messages (not channel chat).

openhop_channels

Channel names and indices from the Repeater DB. No secrets.

openhop_channel_messages

Admin-only. Decrypted channel history from the Repeater DB (max 90 days per call).

openhop_api_read

GET against an explicit allowlist of telemetry /api/ paths.

openhop_link_quality

One neighbour's RSSI/SNR spread, SNR trend, gaps and duplicate ratio. Without peer_hash, lists links to pick from.

openhop_airtime_headroom

Per-minute transmit airtime vs the duty-cycle limit, plus receive load.

openhop_noise_anomalies

Noise-floor spikes and dips, found with a median/MAD robust z-score.

openhop_whoami

Name and role of the calling token.

openhop_validate_config

Admin-only. Validate the Repeater's config.yaml.

openhop_send_advert

Write, admin, only when read_only=false. Transmits an advert.

openhop_set_mode

Write, admin, only when read_only=false. forward, monitor or no_tx.

openhop_set_duty_cycle

Write, admin, only when read_only=false.

openhop_update_duty_cycle_config

Write, admin, only when read_only=false.

openhop_update_advert_rate_limit

Write, admin, only when read_only=false.

openhop_publish_neighbors

Write, admin, only when read_only=false.

openhop_query_neighbor_scopes

Write, admin, only when read_only=false. Queries one zero-hop neighbour over the air.

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

openhop://stats

Same compact overview as openhop_stats.

openhop://neighbors

Neighbour table, most recently heard first.

openhop://channels

Channel names and indices (only when history is enabled).

Prompts

Prompt

What it does

mesh_health_check

Walks through stats, airtime, noise, neighbours, logs and hardware, then gives a verdict and the top three issues.

diagnose_neighbor

Takes a node name and works out whether a weak link is distance, interference or the neighbour dropping out.

summarise_channel

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

  1. Download openhop_mcp_plugin-<version>-py3-none-any.whl from the latest release (check it against SHA256SUMS), or build it yourself.

  2. Open the Repeater web UI, go to Plugins, click Install plugin and choose the wheel.

  3. Open the plugin's settings, fill in auth_tokens and allowed_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 --wheel

Then 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/install

Enable 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/enable

Check 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 --wheel

The 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.py

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP client interaction via streamable HTTP, providing example tools (echo, getPostsByUser) and resources (posts, users) with pluggable authentication providers.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      A
      maintenance
      Acts 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT