marcus
f2abf2af1e
- README.md: replace v0.1 placeholder with full v0.3.5 reference docs (all 26 tools documented with parameters, return values, caveats) - CLAUDE.md: bump implemented-tools header to v0.3.5; roadmap updated (v0.3 complete, v0.4 candidates: none planned) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
305 lines
8.1 KiB
Markdown
305 lines
8.1 KiB
Markdown
# mcp-synology-filestation
|
|
|
|
MCP server that exposes a **Synology NAS FileStation** as tools for Claude Desktop (and any
|
|
other MCP client). All 26 tools are production-tested against DSM 7.x.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
26 tools covering the full FileStation surface:
|
|
|
|
| Group | Tools |
|
|
|-------|-------|
|
|
| **Browse** | `list_shares`, `list_dir`, `get_info`, `check_exist`, `search` |
|
|
| **Transfer** | `download`, `upload`, `get_thumbnail` |
|
|
| **Organise** | `create_folder`, `rename`, `copy`, `move`, `delete`, `compress`, `extract` |
|
|
| **Analyse** | `dir_size`, `get_md5`, `check_permission` |
|
|
| **Sharing** | `create_sharing_link`, `list_sharing_links`, `delete_sharing_link` |
|
|
| **Favorites** | `list_favorites`, `add_favorite`, `delete_favorite` |
|
|
| **System** | `background_tasks`, `list_snapshots` |
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- Python 3.12+
|
|
- [`uv`](https://docs.astral.sh/uv/) (recommended) or pip
|
|
- Synology NAS running DSM 7.x with FileStation enabled
|
|
- A DSM user account with FileStation access
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### From Gitea
|
|
|
|
```bash
|
|
uv tool install git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
|
|
```
|
|
|
|
### Reinstall (upgrade)
|
|
|
|
```bash
|
|
uv tool install --reinstall git+https://gitea.gecheckt.de/marcus/mcp-synology-filestation.git
|
|
```
|
|
|
|
> **Windows / Claude Desktop:** close Claude Desktop before reinstalling — Windows holds
|
|
> file locks on running executables.
|
|
|
|
---
|
|
|
|
## Setup
|
|
|
|
Run the interactive wizard once to configure the NAS connection and store credentials
|
|
securely in the OS keyring:
|
|
|
|
```bash
|
|
mcp-synology-filestation setup
|
|
```
|
|
|
|
The wizard will:
|
|
1. Ask for your NAS host, port, and HTTPS settings
|
|
2. Ask for your DSM username and password (stored in OS keyring — never written to disk)
|
|
3. Handle 2FA / device token if required
|
|
4. Verify the FileStation API is reachable
|
|
5. Print a ready-to-paste Claude Desktop config snippet
|
|
|
|
### Verify the setup
|
|
|
|
```bash
|
|
mcp-synology-filestation check
|
|
```
|
|
|
|
---
|
|
|
|
## Claude Desktop integration
|
|
|
|
Add the server to `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"synology-filestation": {
|
|
"command": "mcp-synology-filestation",
|
|
"args": ["serve"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
The server uses **stdio transport** and is fully compatible with Claude Desktop on
|
|
Windows, macOS, and Linux.
|
|
|
|
### Environment variable overrides
|
|
|
|
| Variable | Purpose |
|
|
|----------|---------|
|
|
| `SYNOLOGY_HOST` | Override NAS hostname |
|
|
| `SYNOLOGY_USERNAME` | Override DSM username |
|
|
| `SYNOLOGY_PASSWORD` | Override DSM password (not stored) |
|
|
|
|
---
|
|
|
|
## Tool reference
|
|
|
|
### Browse
|
|
|
|
#### `list_shares`
|
|
List all shared folders with volume usage (total / used / %).
|
|
|
|
#### `list_dir`
|
|
List a directory's contents with pagination and sorting.
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `path` | — | Share-relative path (e.g. `/docker`, `/data/photos`) |
|
|
| `offset` | 0 | Items to skip |
|
|
| `limit` | 100 | Max items (hard cap: 500) |
|
|
| `sort_by` | `name` | `name` \| `size` \| `user` \| `group` \| `mtime` \| `atime` \| `crtime` \| `type` |
|
|
| `sort_direction` | `asc` | `asc` \| `desc` |
|
|
|
|
#### `get_info`
|
|
Detailed metadata (size, owner, permissions, timestamps) for one or more paths.
|
|
Accepts comma-separated paths.
|
|
|
|
#### `check_exist`
|
|
Yes/No existence check for one or more comma-separated paths.
|
|
|
|
#### `search`
|
|
Glob-pattern search across a directory tree with async DSM polling.
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `path` | — | Root directory |
|
|
| `pattern` | — | Filename glob, e.g. `*.log` |
|
|
| `recursive` | `true` | Search subdirectories |
|
|
| `max_results` | 200 | Cap on returned matches |
|
|
|
|
---
|
|
|
|
### Transfer
|
|
|
|
#### `download`
|
|
Download a file as base64-encoded content. Files > 10 MB are rejected.
|
|
Returns JSON: `{filename, size, content_base64}`
|
|
|
|
#### `upload`
|
|
Upload base64-encoded content to the NAS. Files > 50 MB are rejected.
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `path` | — | Destination directory |
|
|
| `filename` | — | Name for the new file |
|
|
| `content_base64` | — | Base64-encoded bytes |
|
|
| `overwrite` | `false` | ⚠ Overwrites existing file if `true` |
|
|
| `create_parents` | `true` | Create missing parent directories |
|
|
|
|
#### `get_thumbnail`
|
|
Fetch a JPEG thumbnail for an image or video file.
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `path` | — | Share-relative file path |
|
|
| `size` | `small` | `small` \| `medium` \| `large` \| `original` |
|
|
|
|
Returns JSON: `{filename, size_bytes, content_base64}`.
|
|
A `"warning"` field is added when the thumbnail exceeds ~500 KB base64.
|
|
Thumbnails > ~2 MB base64 are rejected with an error — use `size=small` in that case.
|
|
|
|
> **Note:** The DSM `quality` parameter has no effect — DSM ignores it. `size=small` is
|
|
> the default and recommended value; larger sizes can exceed MCP buffer limits.
|
|
|
|
---
|
|
|
|
### Organise
|
|
|
|
#### `create_folder`
|
|
Create a folder. Set `create_parents=true` to create intermediate directories.
|
|
|
|
#### `rename`
|
|
Rename a file or folder. `new_name` is a bare name (not a full path).
|
|
|
|
#### `copy` / `move`
|
|
Async copy or move. Default `overwrite=false`.
|
|
|
|
#### `delete`
|
|
**Irreversible.** Requires `confirmed=true`.
|
|
Without it, returns a preview of what would be deleted — nothing is removed.
|
|
|
|
#### `compress`
|
|
Compress one or more paths into a ZIP or 7z archive (async DSM task).
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `paths` | — | List of source paths |
|
|
| `dest_file_path` | — | Output archive path including filename |
|
|
| `level` | `moderate` | `store` \| `fastest` \| `fast` \| `normal` \| `moderate` \| `maximum` |
|
|
| `format` | `zip` | `zip` \| `7z` |
|
|
| `password` | `""` | Archive password |
|
|
|
|
#### `extract`
|
|
Extract a ZIP or 7z archive to a destination folder (async DSM task).
|
|
|
|
| Parameter | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `file_path` | — | Archive path on NAS |
|
|
| `dest_folder_path` | — | Destination directory |
|
|
| `overwrite` | `false` | ⚠ Overwrite existing files if `true` |
|
|
| `keep_dir` | `true` | Preserve directory structure |
|
|
| `create_subfolder` | `false` | Extract into a new subfolder |
|
|
| `password` | `""` | Archive password |
|
|
|
|
---
|
|
|
|
### Analyse
|
|
|
|
#### `dir_size`
|
|
Total size, file count, and folder count for one or more directories (comma-separated).
|
|
|
|
#### `get_md5`
|
|
Compute the MD5 checksum of a file.
|
|
|
|
#### `check_permission`
|
|
Check whether the current DSM user can write a given filename into a directory.
|
|
|
|
---
|
|
|
|
### Sharing
|
|
|
|
#### `create_sharing_link`
|
|
Create a public sharing link with optional password and expiry date (`YYYY-MM-DD`).
|
|
|
|
#### `list_sharing_links`
|
|
Paginated table of all sharing links (ID, URL, path, owner, expiry, status).
|
|
|
|
#### `delete_sharing_link`
|
|
Delete a sharing link by its ID (from `list_sharing_links`).
|
|
|
|
---
|
|
|
|
### Favorites
|
|
|
|
#### `list_favorites`
|
|
List all FileStation user favorites (name, path, type, status, real path, modified).
|
|
|
|
#### `add_favorite`
|
|
Pin a path as a FileStation favorite with a display label.
|
|
|
|
#### `delete_favorite`
|
|
Remove a favorite by its path.
|
|
|
|
---
|
|
|
|
### System
|
|
|
|
#### `background_tasks`
|
|
Paginated list of active/recent FileStation background tasks
|
|
(copy, move, delete, extract, compress) with type, status, path, and file progress.
|
|
|
|
> Only the `list` method is available on DSM 7.x — tasks cannot be cancelled via this API.
|
|
|
|
#### `list_snapshots`
|
|
List Btrfs snapshots for a shared folder (snapshot ID, creation time, description, locked).
|
|
|
|
> Requires a Btrfs-formatted volume. Returns a clear error on ext4/non-Btrfs shares
|
|
> ("requires Btrfs-formatted volume").
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install with dev dependencies
|
|
uv sync --dev
|
|
|
|
# Format
|
|
uv run ruff format src/ tests/
|
|
|
|
# Lint
|
|
uv run ruff check src/ tests/
|
|
|
|
# Tests (113 tests)
|
|
uv run pytest
|
|
|
|
# Run server locally (stdio)
|
|
uv run mcp-synology-filestation serve
|
|
```
|
|
|
|
See [CLAUDE.md](CLAUDE.md) for the full development context and
|
|
[SPEC.md](SPEC.md) for DSM API call details and quirks.
|
|
|
|
---
|
|
|
|
## Security
|
|
|
|
- Passwords are stored in the **OS keyring only** — never in the config file or logs.
|
|
- Session IDs and credentials are masked in all debug output.
|
|
- The `delete` tool requires explicit `confirmed=true` to prevent accidents.
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
MIT
|