mcp-synology-container/docs/setup.md

Setup Guide

Prerequisites

• Python 3.12 or higher
• A Synology NAS running DSM 7.x with Container Manager installed
• Network access to the NAS from the machine running Claude Desktop

Installation

With pip

pip install mcp-synology-container

With uv

uv tool install mcp-synology-container

Verify installation:

mcp-synology-container --help

---

Running Setup

mcp-synology-container setup

The wizard will prompt you for:

Prompt	Example	Notes
NAS hostname or IP	192.168.1.100 or nas.example.com
Use HTTPS?	y	Recommended
Port	443	Default for HTTPS
Verify SSL certificate?	y	Disable only for self-signed certs
Base path for compose projects	/volume1/docker	Where your compose projects live on the NAS
Alias	HomeNAS	Optional friendly name
DSM username	admin	DSM account with Container Manager access
DSM password		Hidden input

If 2FA is enabled

If your DSM account has OTP enabled, the setup wizard will ask for your OTP code and store a device token in the OS keyring. Subsequent logins will use the device token — no OTP prompts during normal operation.

If your device token is revoked, run setup again to re-bootstrap.

---

Verifying the Connection

mcp-synology-container check

Example output:

Host:       nas.example.com:443
HTTPS:      True
Verify SSL: True
Compose:    /volume1/docker

Credentials: found (user=admin, 2FA=yes)
API info: fetched successfully
Login: successful

Required APIs:
  SYNO.Docker.Container: v1-v1 ✓
  SYNO.Docker.Container.Log: v1-v1 ✓
  SYNO.Docker.Image: v1-v1 ✓
  SYNO.Docker.Project: v1-v1 ✓
  SYNO.FileStation.Download: v1-v2 ✓
  SYNO.FileStation.Upload: v1-v3 ✓

All checks passed.

Exit code 0 means everything is working. Exit code 1 means a problem was detected.

---

Configuring Claude Desktop

After running setup, the wizard prints a configuration snippet. Add it to your Claude Desktop config file:

macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synology-container": {
      "command": "mcp-synology-container",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop after editing the config.

---

Config File Location

The config is saved to:

~/.config/mcp-synology-container/config.yaml

Example config:

# Generated by mcp-synology-container setup
schema_version: 1
alias: HomeNAS
connection:
  host: nas.example.com
  port: 443
  https: true
  verify_ssl: true
compose_base_path: /volume1/docker

Credentials are NOT stored in this file. They are stored in the OS keyring.

---

Alternative: Environment Variables

If you prefer not to use the keyring (e.g. in Docker or CI environments), set these environment variables:

export SYNOLOGY_HOST=192.168.1.100
export SYNOLOGY_USERNAME=admin
export SYNOLOGY_PASSWORD=yourpassword

Environment variables take priority over the keyring.

You can also specify the config path:

export MCP_SYNOLOGY_CONTAINER_CONFIG=/path/to/config.yaml

Or pass it explicitly:

mcp-synology-container serve --config /path/to/config.yaml

---

DSM User Permissions

The DSM account used by the MCP server needs:

• Access to Container Manager (DSM > Control Panel > User > Applications)
• Read/Write access to the shared folder where compose projects are stored

For read-only use (listing projects and viewing logs), read access is sufficient.

---

Troubleshooting

Connection refused / timeout

• Check NAS hostname and port
• Verify the NAS is reachable from your machine
• Try mcp-synology-container check --verbose

Login failed

• Run mcp-synology-container setup to re-enter credentials
• Check DSM > Control Panel > Security > Auto Block for IP blocks

2FA fails

• Run mcp-synology-container setup again to get a fresh device token
• If your account has app-specific 2FA enforcement, ensure the device token was saved

Container Manager APIs not found

• Ensure Container Manager is installed and running in DSM Package Center
• The package may appear as "Docker" in older DSM versions

SSL certificate errors

• For self-signed certificates: run setup again and answer n to "Verify SSL certificate?"
• Alternatively set verify_ssl: false in your config file