# 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