mcp-omv

MCP server for OpenMediaVault, delivered as a hardened container (Docker Compose). It lets an MCP client such as Bob inspect and manage:

• the Debian host (system info, services, logs, apt, reboot/shutdown),

• Docker Compose stacks, services, containers, images, volumes and networks through the OMV compose plugin,

• other OMV plugins (filesystems, network, SMB, NFS, SMART, cron, config apply).

It talks to OMV only through the official /rpc.php API. It does not mount the Docker socket or any host path.

Safe by default

Everything is read only until the administrator enables more:

See SECURITY.md for the full threat model.

Related MCP server: synapse-rmcp

Tools

Long commands return a taskId. If the command is still running, call omv_task_output with taskId and nextPos.

Deploy on OpenMediaVault

1. In OMV create a user for the server, with the administrator role, no MFA and a long password.

2. In the compose plugin shared folder create the stack directory and copy compose.yaml and .env.example (as .env).

3. Create the secrets (files, never committed):

   mkdir -p secrets && chmod 700 secrets
   printf '%s' 'THE_OMV_SERVICE_PASSWORD' > secrets/omv_password
   openssl rand -base64 48 | tr -d '\n=' > secrets/mcp_token
   chmod 600 secrets/*

4. Edit .env (OMV_URL, OMV_USERNAME). Keep tiers false at first.

5. Start the stack from the compose plugin, or docker compose up -d.

6. Check: curl http://127.0.0.1:8787/healthz

If the OMV web UI uses a private CA, mount the CA file and set NODE_EXTRA_CA_CERTS in the service environment. Do not disable certificate validation.

Private image

If the GHCR package is private, run once on OMV: docker login ghcr.io -u <user> with a token that has only read:packages.

Verify the image signature

cosign verify ghcr.io/tommypopescu/mcp_omv:latest \
  --certificate-identity-regexp="https://github.com/tommypopescu/.*" \
  --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

Configure the MCP client (Bob)

{
  "mcpServers": {
    "omv": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer ${env:OMV_MCP_TOKEN}" }
    }
  }
}

Set OMV_MCP_TOKEN in your environment to the content of secrets/mcp_token. If the client is on another machine, publish on a specific LAN IP (MCP_PUBLISH_HOST), add that IP to MCP_ALLOWED_HOSTS, and put TLS in front (for example the OMV nginx or a reverse proxy). The token must not travel over plain HTTP on an untrusted network.

Configuration

Develop

npm ci
npm run typecheck
npm test
npm run build

CI/CD

build-push.yml builds the image, blocks on Trivy CRITICAL/HIGH findings, uploads SARIF to the Security tab, pushes to GHCR and signs the digest with Cosign (keyless). ci.yml runs typecheck, tests and audit. codeql.yml runs CodeQL. Dependabot updates Actions, npm and the base image. All Actions are pinned to commit SHAs.

License

MIT