197 lines
4.4 KiB
Markdown
197 lines
4.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pip install mcp-synology-container
|
|
```
|
|
|
|
### With uv
|
|
|
|
```bash
|
|
uv tool install mcp-synology-container
|
|
```
|
|
|
|
Verify installation:
|
|
|
|
```bash
|
|
mcp-synology-container --help
|
|
```
|
|
|
|
---
|
|
|
|
## Running Setup
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`
|
|
|
|
```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:
|
|
|
|
```yaml
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
export MCP_SYNOLOGY_CONTAINER_CONFIG=/path/to/config.yaml
|
|
```
|
|
|
|
Or pass it explicitly:
|
|
|
|
```bash
|
|
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
|