Initial implementation
This commit is contained in:
+196
@@ -0,0 +1,196 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user