mcp-synology-container

An MCP (Model Context Protocol) server for managing Docker projects on a Synology NAS via Container Manager. Enables Claude Desktop to list, start, stop, redeploy, and modify Docker Compose projects directly.

Features

• Project management: list, start, stop, redeploy Container Manager projects
• Container inspection: list containers, view status and resource usage, fetch logs
• Compose file editing: read, modify image tags, update env vars, or replace compose files entirely
• Image update checks: see which images have updates available
• 2FA support: device token flow for Synology accounts with OTP enabled
• OS keyring integration: credentials stored securely, never in config files
• Confirmation required for all destructive operations (stop, redeploy, exec, compose writes)

Requirements

• Python 3.12+
• Synology NAS with DSM 7.x and Container Manager installed
• pip or uv for installation

Installation

pip install mcp-synology-container

Or with uv:

uv tool install mcp-synology-container

Setup

Run the interactive setup wizard:

mcp-synology-container setup

The wizard will:

1. Ask for your NAS hostname/IP, port, and HTTPS settings
2. Ask for your DSM username and password
3. Handle 2FA if enabled (stores device token in OS keyring)
4. Save the config to ~/.config/mcp-synology-container/config.yaml
5. Print the Claude Desktop configuration snippet

Claude Desktop configuration

Add the snippet to claude_desktop_config.json:

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

CLI Commands

mcp-synology-container setup

Interactive setup: configure connection and store credentials.

mcp-synology-container setup
mcp-synology-container setup --verbose

mcp-synology-container check

Test the connection and verify all required APIs are available.

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

Exit code 0 = OK, 1 = error.

mcp-synology-container serve

Start the MCP server (used by Claude Desktop).

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

Configuration

Config file: ~/.config/mcp-synology-container/config.yaml

schema_version: 1
alias: HomeNAS                        # Optional display name
connection:
  host: dsm.example.com
  port: 443
  https: true
  verify_ssl: true
compose_base_path: /volume1/docker   # Base path for compose projects on NAS

Environment variable overrides

Variable	Description
SYNOLOGY_HOST	NAS hostname or IP
SYNOLOGY_PORT	DSM port
SYNOLOGY_HTTPS	Use HTTPS (true/false)
SYNOLOGY_VERIFY_SSL	Verify SSL cert (true/false)
SYNOLOGY_USERNAME	DSM username
SYNOLOGY_PASSWORD	DSM password

Credentials from environment variables take priority over the keyring.

MCP Tools

See docs/tools.md for the full tool reference.

Projects

Tool	Description	Confirmation
list_projects	List all Container Manager projects	—
get_project_status	Detailed project status	—
start_project	Start a project	—
stop_project	Stop a project	required
redeploy_project	Pull images + restart project	required

Containers

Tool	Description	Confirmation
list_containers	List containers (optionally filtered by project)	—
get_container_status	Status, uptime, resource limits	—
get_container_logs	Fetch container log output	—
exec_in_container	Execute command in container	required

Compose Files

Tool	Description	Confirmation
read_compose	Read the compose file of a project	—
update_image_tag	Update image tag for a service	required
update_env_var	Add/update an environment variable	required
update_compose	Replace entire compose file	required

Images

Tool	Description	Confirmation
check_image_updates	Check for available image updates	—

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python -m pytest tests/ -v

# Lint
ruff check src/ tests/

# Format
ruff format src/ tests/

Security

• Credentials are stored in the OS keyring only (never in config files)
• All destructive operations require explicit confirmation (confirmed=True)
• HTTPS with certificate verification is enabled by default
• Session IDs and passwords are never written to stderr logs

License

MIT