Skip to main content
Glama
mcp-syncnology

mcp-syncnology

by humyai99

mcp-syncnology

MCP server ที่เปิดให้ Hermes agent (หรือ MCP client อื่น ๆ) ควบคุม/ดูข้อมูล Synology NAS ผ่าน DSM Web API — ไม่ใช่ web scraping, เป็น API ทางการของ Synology ที่ล็อกอินด้วย username/password แล้วได้ session token (_sid) มาใช้เรียก endpoint อื่น ๆ ต่อ

โครงสร้าง

src/mcp_syncnology/
  config.py   # อ่าน env: SYNOLOGY_BASE_URL, SYNOLOGY_USERNAME, SYNOLOGY_PASSWORD, ...
  client.py   # SynologyClient: login/session + wrapper รอบ DSM API แต่ละตัว
  server.py   # FastMCP server + tool definitions

client.py มี call(api, method, version, **params) กลางที่ resolve path/version จริงของแต่ละ API ผ่าน SYNO.API.Info เอง (ไม่ hardcode path) และ auto re-login ถ้า session หมดอายุ — เพิ่ม DSM API ตัวใหม่ได้ง่าย ๆ โดยเรียก self.call("SYNO.xxx", "method", ...)

Related MCP server: synology-office-mcp

ความปลอดภัย

  • ห้ามใส่รหัสผ่านจริงในโค้ดหรือแชทเด็ดขาด — เก็บไว้ใน .env (ไฟล์นี้อยู่ใน .gitignore แล้ว) เท่านั้น

  • ถ้า DSM account เปิด 2FA ไว้ ต้องใส่ SYNOLOGY_OTP_CODE ต่อการ login หนึ่งครั้ง (code หมดอายุเร็ว) — แนะนำให้สร้าง local DSM account แยกสำหรับ automation นี้แล้วปิด 2FA เฉพาะ account นั้น หรือใช้ Application Password ถ้า DSM version รองรับ

  • Tool syncnology_delete_path เป็น irreversible action ต้องเรียกด้วย confirm=True เท่านั้น และควรให้ agent ยืนยันกับผู้ใช้ก่อนเรียกทุกครั้ง

  • ถ้า NAS ใช้ self-signed cert ในเครือข่ายภายใน ให้ตั้ง SYNOLOGY_VERIFY_SSL=false ใน .env — ห้ามปิดถ้าเข้าผ่านอินเทอร์เน็ตสาธารณะ

ติดตั้ง

cd D:/MCP/mcp-syncnology
pip install -e .
copy .env.example .env

แก้ .env ให้เป็น IP/พอร์ต NAS จริง (เช่น https://192.168.1.10:5001) และ username/password ของ DSM

รันทดสอบ (stdio)

python -m mcp_syncnology.server

หรือทดสอบผ่าน MCP Inspector:

mcp dev src/mcp_syncnology/server.py

Tools ที่มีให้แล้ว

Tool

ทำอะไร

syncnology_list_shared_folders

list shared folder บน NAS

syncnology_list_files

list ไฟล์/โฟลเดอร์ในพาธที่กำหนด

syncnology_get_file_info

ดู metadata ของไฟล์/โฟลเดอร์

syncnology_create_folder

สร้างโฟลเดอร์ใหม่

syncnology_delete_path

ลบไฟล์/โฟลเดอร์ (ต้อง confirm=True)

syncnology_system_info

ข้อมูลรุ่น/DSM version/uptime

syncnology_utilization

CPU/RAM/network usage ปัจจุบัน

syncnology_storage_info

สถานะ storage pool/volume/disk

syncnology_list_backup_tasks

list Active Backup for Business task

syncnology_backup_task_status

สถานะ backup task ตาม task_id (filter จาก list, ไม่มี method status แยก)

syncnology_list_download_tasks

list Download Station task

syncnology_create_download_task

เพิ่ม download task ใหม่ (URL/magnet)

syncnology_delete_download_task

ลบ download task

syncnology_list_cameras

list กล้องใน Surveillance Station

syncnology_system_logs

ดู system log ล่าสุด

เพิ่ม tool ใหม่: เพิ่มเมธอดใน client.py ที่เรียก self.call("SYNO.xxx", "method", ...) แล้วห่อด้วย @mcp.tool() ใน server.py

ต่อกับ Hermes agent

Hermes เก็บ MCP server config ไว้ที่ ~/.hermes/config.yaml (Linux/DGX Spark) หรือ %LOCALAPPDATA%\hermes\config.yaml (Windows) ใต้ key mcp_servers: ค่า secret (SYNOLOGY_USERNAME/SYNOLOGY_PASSWORD) อ่านจาก .env ในโฟลเดอร์นี้โดยตรงเสมอ ไม่ต้องใส่ใน config ของ Hermes

Deploy บน DGX Spark (Linux) — ที่ Hermes รันจริง

git clone https://github.com/humyai99/mcp-syncnology.git
cd mcp-syncnology
python3 -m venv .venv
.venv/bin/python -m pip install -e .
cp .env.example .env   # แก้ SYNOLOGY_BASE_URL/USERNAME/PASSWORD ให้เป็นค่าจริง
chmod +x run-hermes.sh

แล้วเพิ่มใน ~/.hermes/config.yaml:

mcp_servers:
  mcp-syncnology:
    command: bash
    args:
      - /path/to/mcp-syncnology/run-hermes.sh
    enabled: true

Windows (ถ้ามี Hermes instance แยกบนเครื่องนี้ด้วย)

mcp_servers:
  mcp-syncnology:
    command: powershell.exe
    args:
      - -NoProfile
      - -ExecutionPolicy
      - Bypass
      - -File
      - D:\MCP\mcp-syncnology\run-hermes.ps1
    enabled: true

หลังแก้ config ต้อง restart Hermes เพื่อโหลด MCP server ตัวใหม่

ทดสอบแล้วกับ NAS จริง

  • ผ่าน: login, system_info, utilization, storage_info, list_shared_folders, list_files, get_file_info, create_folder, delete_path, system_logs, list_backup_tasks, backup_task_status

  • syncnology_list_download_tasks / syncnology_list_cameras ยังไม่ได้ทดสอบจริง เพราะ NAS ที่ใช้ทดสอบไม่ได้ติดตั้งแพ็กเกจ Download Station / Surveillance Station — โค้ดเรียก API ตามเอกสารทั่วไป แต่ยังไม่ยืนยันกับ NAS ที่มีแพ็กเกจเหล่านี้จริง

  • รันด้วย python scripts/smoke_test.py (read-only) หรือ --with-write (รวม create/delete โฟลเดอร์ทดสอบ) เพื่อตรวจสอบกับ NAS ของคุณเองอีกครั้ง เพราะพฤติกรรม DSM API บางอย่าง (เช่น version ของ method ที่ใช้ได้) ต่างกันไปตาม DSM version

ยังไม่ได้ทำ / ข้อจำกัดที่ควรรู้

  • ยังไม่รองรับ Application Password / OAuth ของ DSM 7+ (ถ้ามีจะปลอดภัยกว่า username/password ตรง ๆ)

  • syncnology_create_download_task ให้ NAS ไปดึงไฟล์จาก URL ใดก็ได้ — ควรจำกัดว่า agent เรียกได้จาก URL ที่ผู้ใช้ระบุเองเท่านั้น

Available Tools

15 tools
syncnology_backup_task_statusA

Get the status (incl. last_result) of a specific Active Backup for Business task by its task_id.

Inputs: task_id (required). Returns: result

syncnology_create_download_taskA

Add a new Download Station task for the given URI (http/ftp/magnet link).

Inputs: uri (required). Returns: result

syncnology_create_folderB

Create a new folder named name inside folder_path on the NAS.

Inputs: name (required), folder_path (required). Returns: result

syncnology_delete_download_taskB

Remove a Download Station task by its id.

Inputs: task_id (required). Returns: result

syncnology_delete_pathA

Permanently delete a file or folder on the NAS. Irreversible.

Call with confirm=True only after the user has explicitly confirmed they want this specific path deleted.

Inputs: path (required), confirm. Returns: result

syncnology_get_file_infoA

Get metadata (size, timestamps, permissions) for a file or folder path on the NAS.

Inputs: path (required). Returns: result

syncnology_list_backup_tasksB

List Active Backup for Business tasks configured on the NAS.

Inputs: no named parameters. Returns: result

syncnology_list_camerasA

List cameras configured in Surveillance Station.

Inputs: no named parameters. Returns: result

syncnology_list_download_tasksA

List Download Station tasks and their transfer status.

Inputs: no named parameters. Returns: result

syncnology_list_filesA

List files/folders under a path on the NAS, e.g. '/home' or '/shared_folder/subdir'.

Inputs: folder_path (required), limit, offset. Returns: result

syncnology_list_shared_foldersA

List shared folders available on the Synology NAS.

Inputs: no named parameters. Returns: result

syncnology_storage_infoA

Get storage pool, volume, and disk health info from the NAS.

Inputs: no named parameters. Returns: result

syncnology_system_infoA

Get general Synology NAS system info (model, DSM version, serial, uptime).

Inputs: no named parameters. Returns: result

syncnology_system_logsC

Get the most recent system log entries from the NAS.

Inputs: count. Returns: result

syncnology_utilizationA

Get current CPU, memory, and network utilization of the NAS.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool targets a distinctly different resource or action: file browsing vs system monitoring vs backup status vs download tasks vs camera listing vs logs. No two tools appear to overlap in purpose, making selection unambiguous.

    Naming Consistency4/5

    All tools share the 'syncnology_' prefix and follow an action_noun pattern (list, get, create, delete). Minor deviations exist such as 'backup_task_status' and 'system_logs' instead of 'get_backup_task_status' and 'get_system_logs', but overall the naming is consistent and predictable.

    Tool Count5/5

    15 tools is well within the ideal range for a server covering multiple NAS subdomains. Each tool serves a clear purpose, and the count is neither too sparse nor overwhelming.

    Completeness3/5

    The toolset covers core NAS operations—file listing/info/create/delete, system stats, backup task queries, and download management. However, gaps exist: no file upload/download content transfer, no backup task creation/modification, and camera support is limited to listing. These are notable but not fatal for many workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Synology NAS — modular, secure (2FA-ready), permission-tiered. File management and beyond.
      59
      417 PyPI
      16
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Self-hosted MCP server that exposes Synology Drive, Spreadsheet, MailPlus, and Calendar as structured tools for AI agents, enabling file, spreadsheet, email, and calendar management via natural language.
      39
      13 npm
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with Synology NAS services including DSM, File Station, Calendar, Note Station, Contacts, Chat, Download Station, and Container Manager through a modular MCP interface with configurable safety modes.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that exposes a Synology NAS through the official DSM WebAPI, covering File Station, Download Station, Synology Photos, Container Manager, and system management with curated tools and a generic bridge for other APIs.
      1
      MIT