synology-chat-hermes-mcp

English · 繁體中文

A constrained FastMCP HTTP server that exposes a fixed Synology NAS SMB share to AI agents as read/write file tools — with strict path jail, size limits, and active-content rejection built in.

Originally built as the file channel for a family Hermes deployment (control agent → MCP → SMB3 → NAS). Works with any MCP client (Hermes, Claude, etc.).

Why this exists

AI agents with file access are only safe if the access is bounded. This server:

• Jails every path to one fixed share (NAS_SHARE). Path traversal (.., absolute paths, symlink/reparse-point escape) is rejected before any SMB call.

• Rejects public WAN servers — NAS_SERVER must be a private, link-local, or Tailscale (100.64.0.0/10) literal IP. DNS names and public IPs are refused.

• Never stores credentials — the SMB password is read from a docker secret file at startup (NAS_PASSWORD_FILE), never from env vars or code.

• Blocks active content — DOCX/XLSX/PDF writers generate sanitized documents only; binary uploads are scanned for macros, external relationships, and scripts; extension/media-type mismatches are rejected.

• Bounds everything — file size, binary size, document characters, spreadsheet cells, image pixels, search results all have hard limits.

• Audits operations — every mutation is appended to a JSONL audit log.

Related MCP server: MCP File System Server

Architecture

Hermes (or any MCP client)
  → HTTP :8000/mcp (FastMCP, streamable HTTP)
    → NasService (validation, limits, audit)
      → SMBBackend (smbprotocol, SMB3, encryption+signing required)
        → Synology NAS share

Tools

Known limitation: create_directory validates the parent before makedirs, so a multi-level path whose first segment doesn't exist returns not_found even with parents=True. Create one level at a time.

Quick start

cp .env.example .env   # set NAS_SERVER (Tailscale/private IP), NAS_USERNAME
# provide the SMB password as a docker secret:
printf '%s' 'YOUR_SMB_PASSWORD' > ./synology_password
chmod 600 ./synology_password

docker build -t nas-mcp .
docker run -d --name nas-mcp \
  --env-file .env \
  -v "$PWD/synology_password:/run/secrets/synology_password:ro" \
  -v nas-mcp-audit:/var/log/nas-mcp \
  -p 8000:8000 \
  nas-mcp

Health check:

curl -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Hermes MCP config

mcp_servers:
  nas-mcp:
    type: http
    url: http://nas-mcp:8000/mcp

Running tests

python -m nas_mcp.smoke   # exercises the full tool chain against the live share

Environment reference

Security notes

• The SMB password is the only secret in the system and it lives only in the docker secret file. Nothing is hardcoded, nothing is stored in .env in plaintext beyond non-secret tuning values (and .env is git-ignored).

• Bind to a private interface in production; do not expose :8000 publicly.

• The share name and SMB user are configuration (NAS_SHARE, NAS_USERNAME) — set them per deployment; nothing in the code assumes a particular value.

License

MIT