Ask your AI about your network — the DeviceShelf MCP server

As of Server edition 1.5.3, DeviceShelf can answer questions about your network in plain language. It exposes your live inventory and monitoring state to an AI assistant such as Claude Desktop over the Model Context Protocol (MCP). Ask "what's online right now?", "anything new or offline since yesterday?", "which devices have certificates expiring soon?" or "how does tonight's network differ from last week's snapshot?" and the assistant answers from your own data.

All told, that is 22 tools (14 read, 8 opt-in actions), 3 guided prompts, 4 attachable resources, and an optional live mode that pushes changes to the client as they happen.

Strictly local

The MCP endpoint runs inside your DeviceShelf Server, on the same port as the API, behind a bearer token, reachable only on your LAN. Nothing is sent to an external service except by the AI client you connect; there is no DeviceShelf cloud connector and no remote OAuth. It reads the same in-process data that backs the dashboard, so the AI view can never diverge from what you see.

What it can answer

The read-only tools cover the full monitoring surface:

Inventory: network_summary for the one-shot overview (subnet, gateway, device and alarm counts), list_devices with filters and pagination (online/type/subnet/favorite/tag), find_device free-text search ("the printer", "my NAS"), get_device with full per-device detail (open ports, OS, SNMP, TLS, matched CVEs, notes), and list_interfaces for multi-NIC collectors.
Monitoring: list_changes (recent timeline: new/online/offline/port changes), list_alarms (current alarm state and acknowledgement), list_checks (your configured monitor checks and their current level), get_device_history (online/offline and RTT samples), get_device_uptime (per-device uptime/SLA over up to 90 days), and list_offline_devices ("what disappeared?").
Security: one security_overview call surfaces certificates expiring soon or already expired, self-signed certificates, and devices with known CVEs grouped by severity, across the whole network and without a lookup per host.
Snapshots: list_snapshots and diff_snapshots compare two named captures of your network, or a capture against the live scan: devices added, devices removed, port changes. "What's new since the audit in May?" becomes a single question.

Opt-in actions

With a second, separate opt-in (DEVICESHELF_MCP_ALLOW_ACTIONS=true) the assistant also gets action tools:

set_device_metadata: rename a device, set its type or comment ("name the one ending in :4e 'living-room thermostat'").
acknowledge_alarm: snooze an active alarm from the conversation.
save_check / delete_check: create or update monitor checks (ping/tcp/http/snmp) in plain language. "Monitor my NAS over HTTP and alert me when it's down" becomes a running check.
save_snapshot: capture the current network as a named snapshot for later diffing.
scan_now and port_check: trigger an on-demand scan or probe TCP ports on a host, restricted to your own locally-attached subnets and rate-limited.
test_notification: verify your alert channel end to end.

Optionally, DEVICESHELF_MCP_CONFIRM_ACTIONS=true makes the impactful actions ask the client for confirmation first (MCP elicitation), so a scan is never triggered without you clicking yes.

Prompts and resources

For non-experts, the server ships guided prompts that appear in the client's prompt picker: Security audit (a prioritized risk report), What changed recently, and Identify unknown devices. One click gets you a useful answer, without knowing any tool names.

It also exposes four read-only resources (deviceshelf://network/summary, deviceshelf://devices, deviceshelf://alarms, deviceshelf://security/overview) that a client can attach as context without any tool call.

Live mode

By default the endpoint is stateless request/response. Set DEVICESHELF_MCP_LIVE=true and it switches to stateful sessions: clients can subscribe to the device, alarm and summary resources and receive resources/updated notifications pushed when the inventory changes. The assistant stays current without polling. Idle sessions close after 30 minutes.

Built like a security feature

An AI reading your network inventory deserves the same scrutiny as any other client, so:

/mcp is auth-required, exactly like the API: no token, no answer.
A scoped token (DEVICESHELF_MCP_TOKEN) is accepted for /mcp only, never for the admin API or metrics. Your AI client never needs to hold an admin credential.
Writes are off by default, and the probing actions are restricted to local subnets even when enabled.
All tool calls are rate-limited (token bucket, default 300/min) and audit-logged: tool name and outcome, never arguments.
Device-reported strings (hostnames, banners, certificate subjects) are treated as untrusted input: control and text-spoofing characters (bidi, zero-width) are stripped and values truncated before they reach the model, and the model is told to treat them as data.
An Origin allowlist guards against DNS rebinding from a browser.

Enable it

In /etc/deviceshelf/server.env (or your Docker environment):

DEVICESHELF_MCP_ENABLE=true

Restart the server. The endpoint is served at http://<your-server>:8088/mcp with the bearer token. To connect Claude Desktop, bridge to it with mcp-remote. Keep --allow-http (the endpoint is plain http on your LAN) and pass the token via an env var, which avoids a Windows argument-quoting bug:

{
  "mcpServers": {
    "deviceshelf": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://<your-server>:8088/mcp",
               "--transport", "http-only", "--allow-http",
               "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer <your-token>" }
    }
  }
}

Any MCP client that speaks Streamable HTTP can connect directly. Verified copy-paste configs for Claude Code, Cursor, VS Code, Windsurf, Cline and Gemini CLI are in the Connect your AI agent guide; the full configuration reference (scoped token, action gate, rate limit, live and confirm modes) is on the server page.

Included with your license

MCP is part of the Server edition, not a separate purchase. It works during the 7-day trial so you can evaluate it, and the endpoint returns 402 once an unlicensed trial expires.

Compatibility

Available from deviceshelf-server 1.5.3 (Docker image ghcr.io/wealthwallet/deviceshelf-server:1.5.3, .deb, or any later release). Off by default and fully additive: existing servers are unaffected until you set DEVICESHELF_MCP_ENABLE. Feedback shapes what tools come next — get in touch.