Synology Nas

Synology NAS

This skill teaches you how to use the mcp-server-synology MCP effectively. The MCP exposes ~80 tools across seven domains; the trick is picking the right tool, targeting the right NAS, and not exploding a single user request into a dozen redundant calls.

Mental model

Three things shape almost every interaction:

1. Targeting — most setups have one NAS and you can omit the target argument. Multi-NAS setups require a nas_name (or base_url) on every tool call. Don't guess; discover first.
2. State — auth is session-based and usually auto-managed. You almost never need to call synology_login yourself. Check status first; only log in if status says you must.
3. Aggregation — several individual tools have a *_summary equivalent. When the user wants a "checkup" or "overview," reach for the aggregate. When they want a specific number, use the targeted tool.

Once those three are settled, the rest is picking the right domain.

Always start here

Before any operation, run discovery — it's two cheap calls and answers "which NAS?" and "am I logged in?":

1. synology_list_nas — lists configured NAS units with names, URLs, connection status.
2. synology_status — shows which sessions are active.

If the user mentions a NAS by name (e.g. "the backup NAS", "nas2"), match it to a nas_name from synology_list_nas. If only one NAS is configured, you can omit nas_name on subsequent calls. If multiple are configured and the user is ambiguous, ask which one — don't pick.

Tool call shape

Every operational tool accepts an optional target argument:

• nas_name (preferred) — the identifier from settings.json, e.g. "nas1".
• base_url — fallback when the NAS isn't in settings.json.

Pass at most one. Omit both only when there's a single NAS configured.

Path arguments must start with /. User-facing data lives under /volume1/ (or /volume2/, etc., for additional volumes). The root / lists shares; /homes, /photo, /video etc. are share-level mount points underneath. Don't invent paths — list the parent first if unsure.

Domain map

When the user asks about… → read…

Read the reference for a domain before doing non-trivial work in it. Each reference covers the tool list, the right call ordering, and known gotchas. Don't read every reference — only the ones you need.

Cross-cutting patterns

Prefer aggregate tools for overviews

If the user asks "is the NAS healthy?" or "give me a system report," call synology_health_summary once instead of fanning out to synology_system_info + synology_utilization + synology_disk_health + synology_volume_status. The summary is one round-trip and returns the same data. Reach for the individual tools only when the user wants one specific reading (e.g. "what's the CPU at right now?").

Read-only first

When in doubt about a destructive action, list/inspect first:

• Before delete: get_file_info to confirm the path resolves to what you think.
• Before ds_delete_tasks: ds_list_tasks to confirm the IDs.
• Before synology_container_delete, synology_container_project_delete, synology_container_image_delete, or synology_container_network_delete: inspect/list the target first.
• Before synology_delete_user: synology_get_user to confirm the account.

This is a real NAS with real data — there is no "undo" for these tools.

Don't paginate without need

Tools that accept offset/limit (e.g. ds_list_tasks, search_files) default to sensible values. Don't add pagination unless the user mentions a large dataset or a previous call returned suspiciously few results.

Trust auto-login

Auto-login is on by default — the server logs in to every configured NAS at startup. You should expect operational tools to "just work" without calling synology_login first. If a tool returns an auth error, then call synology_status to diagnose, and only call synology_login if no session is active. See references/auth.md for the full state machine.

Multi-step workflows: minimize round-trips

If the user says "list shares and then list the photos folder," do those two calls — don't preface them with a discovery dance. Discovery (synology_list_nas/synology_status) is for when targeting or auth is genuinely unclear, not as a ritual before every request.

Container Manager: GHCR and runtime DNS

GHCR pulls:

1. synology_container_registry_list; require using: GitHub Container Registry for ghcr.io/....
2. On 2202 or docker.io/ghcr.io/..., switch registry in DSM, then synology_container_registry_download.
3. Try owner/image first with GHCR active; try ghcr.io/owner/image only if needed.
4. Wait after successful download; confirm with synology_container_image_list.
5. If project start fails, run synology_container_project_build for DSM logs/start behavior.

Runtime DNS:

• Restart loop: inspect synology_container_logs.
• Logs show Temporary failure in name resolution and NAS has internet: use network_mode: host for single-port apps; remove ports:.
• Avoid dns: first; Synology compose may accept it then fail with 2202.

Optional companion services: skip when README says optional and main app works; add when user needs feature.

Anti-patterns to avoid

• Calling synology_login reflexively. Auto-login almost always handled it.
• Fanning out to 4 health tools when the user asked "how's the NAS doing?" Use synology_health_summary.
• Inventing paths like /Documents/foo or ~/photos. Real paths start with /volume1/. List the parent if unsure.
• Picking a NAS in a multi-NAS setup without confirmation. Ask which one.
• Confusing "shares" with "files." A share is the top-level mount (Photos, video, homes); creating one is an admin action and lives in synology_create_share (see shares-nfs.md). Creating a folder under a share is create_directory.
• Treating containers as files. Container Manager tools use names/repositories/projects, not NAS paths, except project share_path.
• Bulk operations without verification. If the user asks to delete "all old downloads," list them, summarize what you're about to delete, and confirm before calling ds_delete_tasks or delete.

Example: a typical session

User says: "Check on my NAS — anything I should worry about?"

Good response:

1. synology_list_nas → confirm which NAS (or that there's only one).
2. synology_health_summary → one call, full picture.
3. Read the result, surface anything red (degraded volumes, failing disks, high temps), and tell the user.

Avoid:

1. synology_login (unnecessary).
2. synology_system_info, then synology_utilization, then synology_disk_health, then synology_volume_status (4 calls when 1 suffices).

When tool descriptions disagree with this skill

The MCP's own tool descriptions sometimes say "from secrets.json" — settings actually live at ~/.config/synology-mcp/settings.json. Trust this skill over those stale strings. If the user reports an actual auth/config bug, point them at the project README's "Configuration Options" section and don't try to "fix" it from inside Claude.