186 lines
4.7 KiB
Markdown
186 lines
4.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
pip install mcp-synology-container
|
|
```
|
|
|
|
Or with `uv`:
|
|
|
|
```bash
|
|
uv tool install mcp-synology-container
|
|
```
|
|
|
|
## Setup
|
|
|
|
Run the interactive setup wizard:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"synology-container": {
|
|
"command": "mcp-synology-container",
|
|
"args": ["serve"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## CLI Commands
|
|
|
|
### `mcp-synology-container setup`
|
|
|
|
Interactive setup: configure connection and store credentials.
|
|
|
|
```bash
|
|
mcp-synology-container setup
|
|
mcp-synology-container setup --verbose
|
|
```
|
|
|
|
### `mcp-synology-container check`
|
|
|
|
Test the connection and verify all required APIs are available.
|
|
|
|
```bash
|
|
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).
|
|
|
|
```bash
|
|
mcp-synology-container serve
|
|
mcp-synology-container serve --config /path/to/config.yaml
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Config file: `~/.config/mcp-synology-container/config.yaml`
|
|
|
|
```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](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
|
|
|
|
```bash
|
|
# 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
|