MeshCentral MCP Server

A Model Context Protocol (MCP) server that lets AI assistants control your MeshCentral panel.

Features

• List, search, and manage devices (nodes)
• List and manage device groups (meshes)
• Run remote commands on devices (CMD, PowerShell, Linux shell, Agent console)
• Power actions (sleep, reset, poweroff, wake-on-LAN)
• Send toast notifications to devices
• Manage users (list, create, delete)
• View events and audit logs
• Device notes management
• Move devices between groups
• Intel AMT device scanning
• Login token authentication (avoids storing real passwords)
• Local file jail (prevents agent from reading .env or escaping designated directory)
• Confirmation tokens for destructive operations
• Connection health check (ping/pong)
• Output sanitization (ANSI stripping, truncation, prompt injection prevention)

Setup

1. Install dependencies

cd meshcentral-mcp
npm install

2. Configure MeshCentral credentials

Copy .env.example to .env and fill in your server details:

cp .env.example .env

Login tokens (preferred over a password)

Create a login token in the MeshCentral web UI under My Account → Login tokens. MeshCentral returns a pair: a token username (always prefixed ~t:) and a token password. Both are required — a token password on its own cannot authenticate.

MESH_TOKEN_USER=~t:xxxxxxxxxxxxxxxx
MESH_TOKEN_PASS=xxxxxxxxxxxxxxxxxxxx

Or supply both in one variable, comma-separated:

MESH_TOKEN=~t:xxxxxxxxxxxxxxxx,xxxxxxxxxxxxxxxxxxxx

Tokens can be given an expiry and revoked without changing the account password, so they are the right credential for a service account.

Username/password fallback

MESH_SERVER_URL=https://mesh.yourdomain.com
MESH_USERNAME=admin
MESH_PASSWORD=yourpassword

3. MCP Client Configuration

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "meshcentral": {
      "command": "node",
      "args": ["path/to/meshcentral-mcp/src/index.js"],
      "env": {
        "MESH_SERVER_URL": "https://mesh.yourdomain.com",
        "MESH_TOKEN_USER": "~t:xxxxxxxxxxxxxxxx",
        "MESH_TOKEN_PASS": "xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For opencode, add to your opencode.json:

{
  "mcpServers": {
    "meshcentral": {
      "command": "node",
      "args": ["path/to/meshcentral-mcp/src/index.js"],
      "env": {
        "MESH_SERVER_URL": "https://mesh.yourdomain.com",
        "MESH_TOKEN_USER": "~t:xxxxxxxxxxxxxxxx",
        "MESH_TOKEN_PASS": "xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Available Tools (58 total)

Inventory & Monitoring

File Operations (remote device filesystem, via secure tunnels)

Remote Execution & Control

Device & Group Management

Agent Management

Server Administration

Security Notes

• Store credentials in environment variables, never in code
• Use MESH_INSECURE_TLS=true only for self-signed certificates in dev/lab environments
• Use login tokens (MESH_TOKEN_USER / MESH_TOKEN_PASS) rather than an account password — set an expiry on them
• Local file access is confined to MESH_LOCAL_FILE_ROOT (default ./mcp-files); the agent cannot read .env or escape the directory. Set MESH_LOCAL_FILE_ROOT=* to disable (not recommended)
• Confirmation tokens are required for destructive operations (mesh_power_action, mesh_file_delete, mesh_uninstall_agent) — the tool returns a token on first call that must be re-submitted to proceed
• Output sanitization strips ANSI escapes and control characters from all device-sourced output, truncated at 100KB to prevent prompt injection
• Connection health check sends periodic pings to detect dead sockets within 30 seconds
• Serverinfo is cached from the connect handshake — mesh_server_info returns instantly without a second request
• The MCP server acts with the full permissions of the account you give it — use a dedicated, non-admin service account scoped to the device groups you need

What’s New

Login Token Authentication

Instead of storing your real MeshCentral password, use login tokens. Create one in the web UI under My Account → Login tokens. Tokens are a user/password pair that can be expired and revoked without changing your account password.

MESH_TOKEN_USER=~t:xxxxxxxxxxxxxxxx
MESH_TOKEN_PASS=xxxxxxxxxxxxxxxxxxxx

Or combined: MESH_TOKEN=~t:xxxxxxxxxxxxxxxx,xxxxxxxxxxxxxxxxxxxx

Local File Jail (MESH_LOCAL_FILE_ROOT)

mesh_file_download and mesh_file_upload are now confined to a local directory (./mcp-files by default). The agent cannot read your .env, SSH keys, or escape the directory via .. or symlinks. Set MESH_LOCAL_FILE_ROOT=* to disable (not recommended).

Confirmation Tokens for Destructive Tools

Tools that can cause irreversible damage now require a two-step confirmation:

• mesh_power_action (sleep/reset/poweroff)
• mesh_file_delete (delete files/folders)
• mesh_uninstall_agent (remove agent from device)

On first call, the tool returns a confirmation token. Re-invoke with confirm_token: "" to proceed. Tokens expire after 120 seconds.

Connection Health Check

A ping/pong is sent every 30 seconds to detect dead sockets early, instead of waiting for the next command to fail.

Output Sanitization

All device-sourced output is now sanitized:

• ANSI escape sequences stripped
• Control characters removed (except tab/newline/CR)
• Truncated at 100KB to prevent prompt injection from compromised devices

Serverinfo Fix

mesh_server_info now uses cached data from the connect handshake. No more timeout — returns instantly.

Serverstats Fix

mesh_server_stats push subscription cleanup now uses a finally block to guarantee the timer is stopped, even on errors.

Recommendations and future updates

I will be thankful if you suggest any new feature.