dsm-mcp

A Model Context Protocol server for Synology DSM and Container Manager. It lets an MCP client (Claude) inspect the NAS and manage its containers directly over the Synology Web API — no browser, and no per-request DSM login/2FA. The server logs in once with a dedicated service account and keeps the session alive itself, which is effectively the "non-expiring session" you wanted: Claude never re-authenticates.

Companion to arr-mcp. Same shape (Python, streamable-HTTP, bearer auth), a different port (8788), and a Synology-specific client.

Tools

* = write action (start/stop/restart a container). dsm_raw_call can invoke any DSM method, including writes — it's the escape hatch for the parts of DSM's API that vary by version.

About DSM's API (read this)

Synology's Web API is discovery-driven and version/model-dependent. Each tool resolves the correct CGI path and version at call time via SYNO.API.Info, so the system/storage/utilization tools are robust. The Docker/Container Manager methods are less consistently documented across DSM releases — if dsm_docker_logs, dsm_docker_projects, or an action's params don't match your DSM, run dsm_api_discover (query SYNO.Docker or all) to see exactly what your NAS exposes, then drive it with dsm_raw_call. Nothing is hardcoded that can't be worked around live.

Related MCP server: Synology_MCP

Service account (do this first)

Don't point this at your main admin. In DSM:

1. Control Panel → User & Group → Create a user, e.g. claude-svc.

2. Grant only what's needed: Container Manager app permission, and read of system/storage. Keep it out of administrators if your DSM version allows the Docker API without admin; if it requires admin, prefer a separate admin-group account used only here.

   • Note: As of this writing, the service account must be a member of the administrators group to be able to access the container manager endpoints

3. Disable 2FA on this account (a daemon can't type a rotating code). If your policy enforces 2FA, enroll a trusted device once and put its token in DSM_DEVICE_ID.

4. Optionally restrict it to the LAN (Control Panel → Security → firewall / IP rules), since the MCP server sits on the LAN and only the tunnel is public.

Setup

cp config.example.env .env
# edit .env: DSM_URL, the service account + password, a strong MCP_AUTH_TOKEN.
# HTTPS with the self-signed cert? use :5001 and set DSM_VERIFY_SSL=false

docker compose up -d --build
docker logs -f dsm-mcp        # confirm it starts; auth runs on the first tool call

Run without Docker (dev):

pip install -r requirements.txt
set -a; source .env; set +a
python server.py

Exposing it to Claude

Endpoint: https://<your-hostname>/mcp. Same as arr-mcp:

1. Tunnel it (dedicated cloudflared, or a hostname on your existing Jellyfin tunnel → http://dsm-mcp:8788), ideally behind Cloudflare Access.

2. Claude → Settings → Connectors → custom connector → the /mcp URL, with Authorization: Bearer <MCP_AUTH_TOKEN>.

Security notes

• This can restart containers and read system internals, and it authenticates as a DSM user. Keep the account least-privileged, keep 2FA-off scoped to only that LAN account, and always put the endpoint behind the bearer token (and ideally Cloudflare Access).

• Credentials live only in .env (git/docker-ignored). The MCP client never sees them — it only sees tool results.

• No account-deletion, no DSM settings-mutation, no volume/pool destructive tools are exposed. dsm_raw_call is powerful by design; treat the endpoint's auth accordingly.

Files

• server.py — MCP server + tools (streamable-HTTP + bearer auth)

• dsm_client.py — Synology Web API client (discovery, login, session refresh)

• config.py — builds the client from env vars

• Dockerfile / docker-compose.yml — container + optional tunnel

• config.example.env — copy to .env