dreambig-nas-mcp

An MCP server that runs in a container on a Synology NAS and lets agents (Claude Code, Claude Desktop) read and manage files inside one or more NAS shared folders. Each is a Mount: a top-level folder of the Root that every Path starts with (e.g. documents/notes/plan.md). A Mount can be read-only. Nothing else on the NAS is visible.

• Tools: list, stat, read (text, PDF text, images), search (name glob + optional content grep), write, edit, mkdir, move, delete.
• Transport: Streamable HTTP at http://:/mcp, LAN only (remote access via Tailscale), one static bearer token (ADR-0002).
• Nothing is ever really deleted by an agent: deleted and overwritten content goes to a Trash folder inside its Mount (ADR-0001). Mounts: ADR-0003.
• Vocabulary (Root, Mount, Path, Trash, Hidden Entry, Destructive Operation): GLOSSARY.md.
• Upgrading from v1 (one folder as the Root): see Migrating from v1.

Target: DS220+ (Intel, linux/amd64), DSM 7.4.1, Container Manager.

Synology setup

You need: DSM admin access, a Mac on the same LAN, and the NAS’s LAN IP address (Control Panel > Network > Network Interface). This README uses 192.168.1.10 as a placeholder; substitute your NAS’s actual IP everywhere. Don’t use the router/default gateway IP (often x.x.x.1); it isn’t the NAS. Below, agents (read/write) and photos (read-only) are the example shared folders used as Mounts and nas-mcp the example DSM user; use your own names.

1. Choose or create the shared folders (Mounts)

For each folder agents should see:

1. DSM > Control Panel > Shared Folder.
2. Either pick an existing shared folder, or click Create > Create Shared Folder, name it (e.g. agents), pick the volume (e.g. Volume 1), and finish the wizard (you can leave encryption and advanced options off).
3. Note its NAS path: /volume1/agents (volume number + folder name). You can also use a sub-folder, e.g. /volume1/agents/claude; the agent sees only what is mounted.
4. Decide its Mount name (the top-level folder agents see, e.g. agents; letters, digits, -/_; not starting with .) and whether agents may change it (read/write) or only read it (read-only).

2. Create a dedicated DSM user

1. Control Panel > User & Group > User > Create.
2. Name: nas-mcp. Set a long random password (nobody needs to log in as this user). Tick Disallow the user to change account password. Next.
3. Join groups: leave only users. Next.
4. Assign shared folders permissions: tick Read/Write for each read/write Mount (e.g. agents) and Read only for each read-only Mount (e.g. photos); tick No access for every other shared folder. Next.
5. Assign user quota: skip. Next.