💾 Synology MCP Server

💾 Synology MCP サーバー

Synology NAS デバイス向けの Model Context Protocol（MCP）サーバーです。安全な認証とセッション管理を通じて、AI アシスタントがファイルとダウンロードを管理できるようにします。

🌟 新機能：統合サーバーが Claude/Cursor（stdio）と Xiaozhi（WebSocket）の両方を同時にサポートします！

📦 PyPI からインストール

リポジトリをクローンする必要はありません。PyPI から直接パッケージをインストールできます。

# With pip
pip install mcp-server-synology

# Or with pipx (isolated environment)
pipx install mcp-server-synology

# Or with uv
uv tool install mcp-server-synology

これにより、同等のコマンド synology-mcp と mcp-server-synology がインストールされます。

MCP クライアントでは、uvx が最も簡単な方法です。手動インストールやローカルでのクローンは不要で、パッケージを自動的にダウンロードしてキャッシュします。

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-server-synology"]
    }
  }
}

設定はパッケージの外部に保存されるため、ソースをチェックアウトした場合と同じように動作します。設定オプションの説明に従って、~/.config/synology-mcp/settings.json を作成してください。

🚀 Docker ですばやく開始

1️⃣ 環境をセットアップ

# Clone repository
git clone https://github.com/atom2ueki/mcp-server-synology.git
cd mcp-server-synology

# Create environment file
cp env.example .env

2️⃣ .env ファイルを設定

基本設定（Claude/Cursor のみ）：

# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false

拡張設定（Claude/Cursor と Xiaozhi の両方）：

# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false

# Enable Xiaozhi support
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/

.env は実行時に読み込まれ、イメージに組み込まれることはありません。docker-compose.yml が env_file を介して、その内容をコンテナーの環境変数として渡すため、ファイル自体はコンテナー内に存在しません。このファイルは任意です。代わりに settings.json で NAS を設定する場合（推奨）は、このファイルを省略できます。

3️⃣ Docker で実行

どちらのモードも、次の簡単なコマンドで実行できます。

# Claude/Cursor only mode (default if ENABLE_XIAOZHI not set)
docker-compose up -d

# Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)
docker-compose up -d

# Build and run
docker-compose up -d --build

4️⃣ 別の方法：ローカルの Python

# Install the package and its dependencies (from PyPI, or from a clone with 'pip install .')
pip install mcp-server-synology

# Run with environment control
python main.py

🔌 クライアントのセットアップ

以下の例では、このリポジトリをローカルにクローンして Docker を使用します。PyPI からインストールした場合は、代わりにPyPI からインストールの uvx 設定を使用してください。ローカルパスを変更する必要はなく、Claude Desktop、Cursor、Continue、Codeium のいずれでも動作します。

🤖 Claude Desktop

Claude Desktop の設定ファイルに追加します。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

↗️ Cursor

Cursor の MCP 設定に追加します。

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

🔄 Continue（VS Code 拡張機能）

Continue の設定（.continue/config.json）に追加します。

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

💻 Codeium

Codeium の MCP サポートを設定するには、次のようにします。

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

🐍 別の方法：Python を直接実行

Docker を使用しない場合は、次のようにします。

{
  "mcpServers": {
    "synology": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/your/mcp-server-synology",
      "env": {
        "SYNOLOGY_URL": "http://192.168.1.100:5000",
        "SYNOLOGY_USERNAME": "your_username",
        "SYNOLOGY_PASSWORD": "your_password",
        "AUTO_LOGIN": "true",
        "ENABLE_XIAOZHI": "false"
      }
    }
  }
}

🌐 リモート Streamable HTTP デプロイ

デフォルトでは、サーバーはstdioで通信するため、MCP クライアントがプロセスをローカルで起動する必要があります（または SSH／docker exec などのブリッジを介して起動します）。NAS がリモートにある（Claude/Cursor の実行環境とは別のマシンにある）構成では、MCP_HTTP=true を設定すると、同じプロセス内の uvicorn からネイティブの Streamable HTTPでサーバーを提供します。mcp-proxy のサイドカーも、別個の /sse エンドポイントも必要ありません。これにより、ha-mcp などの他の「リモート」MCP サーバーと同様に、URL ベースのコネクターをサポートするあらゆる MCP クライアントから利用できます。

アーキテクチャ

[Claude Desktop / Cursor / ...]
        │
        │ HTTPS (URL connector)
        ▼
[Reverse proxy: DSM / Nginx / Traefik / Caddy]
        │  (TLS termination + auth)
        │ HTTP localhost:8765
        ▼
[Docker container]
  └─ python main.py
       └─ uvicorn → Streamable HTTP at /mcp

デプロイ

1. すべての依存関係は pyproject.toml から取得します。mcp>=2.0.0 には starlette、uvicorn、sse-starlette が含まれているため、同じイメージで stdio と Streamable HTTP の両方を提供できます。追加のビルド引数や別個の requirements ファイルは不要です。
2. 用意されている docker-compose.http.yml を使用します。

# Edit credentials in docker-compose.http.yml first
docker compose -f docker-compose.http.yml up -d --build
docker logs -f synology-mcp-http

サーバーログに Starting Streamable HTTP MCP server on http://0.0.0.0:8765/mcp と表示され、自動ログインが成功することを確認してください。compose ファイルのデフォルト設定では、uvicorn 自身の Uvicorn running on … バナーは表示されません。これは uvicorn.error ロガーの INFO レベルのログですが、DEBUG=true でない限り、サーバーはそのロガーを warning に設定するためです。

リバースプロキシ

ほとんどの MCP クライアントでは HTTPS が必要なため、HTTP エンドポイントの前段に TLS 終端リバースプロキシを配置する必要があります。DSM ユーザーの場合は、組み込みの ログインポータル → リバースプロキシ を使用できます。

• ソース：HTTPS、ホスト名 synology-mcp.example.com、ポート 443
• 宛先：HTTP、localhost、ポート 8765
• カスタムヘッダー：不要です。ストリーミング可能な HTTP は、単一のエンドポイントでの通常の POST/GET であり、WebSocket アップグレードではありません。すでに別の場所で適用している場合、作成 → WebSocket のプリセットを使用しても問題ありません（実際のアップグレード要求に対してのみ Connection: upgrade を設定します）が、ストリームを開いたままにするためのものではありません。

Nginx では、次のようになります。

location / {
    proxy_pass http://localhost:8765;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Responses may stream as long-lived text/event-stream
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 24h;
}

クライアントの設定

Claude Desktop（またはリモートコネクターに対応する任意の MCP クライアント）で、次の URL を指定するカスタムコネクターを追加します。

https://synology-mcp.example.com/mcp

パスには MCP_HTTP_PATH の設定値が使用されます（デフォルトは /mcp）。command も args もローカルの Python も不要で、URL だけで設定できます。

セキュリティ

このサーバーには、アプリケーションレベルの認証機能はありません。HTTP エンドポイントにアクセスできるユーザーは、すべてのツールを呼び出せます。一方、MCP SDK の DNS リバインディング保護は有効になっており、Host／Origin ヘッダーが許可リストに含まれていないリクエスト（MCP_HTTP_ALLOWED_HOSTS／MCP_HTTP_ALLOWED_ORIGINS。デフォルトではループバックを指定）を拒否します。リバースプロキシの背後に配置する場合は、形式の違いに注意して両方を設定してください。ホストはスキームなし（synology-mcp.example.com）、オリジンはスキーム付き（https://synology-mcp.example.com）です。docker-compose.http.yml 内のコメントアウトされた例を参照してください。これにより、ブラウザーをリバインディング攻撃から保護できますが、認証機能ではありません。対策：

• プライベートネットワーク内または VPN の背後で運用します
• 公開ポートはループバックにバインドしたままにします（docker-compose.http.yml は 127.0.0.1:8765 にバインドするため、同じホスト上のリバースプロキシだけがアクセスできます）
• リバースプロキシで IP 許可リストを適用します
• リバースプロキシ層で Basic Auth／mTLS／OAuth2 プロキシを追加します
• 権限を制限した専用の DSM ユーザーを使用します（上記のセキュリティ警告でも推奨しています）

🌟 Xiaozhi 連携

新しい統合アーキテクチャにより、両方のクライアントを同時にサポートします！

仕組み

• ENABLE_XIAOZHI=false（デフォルト）：stdio 経由で Claude／Cursor に接続する標準 MCP サーバー
• ENABLE_XIAOZHI=true：次の両方をサポートするマルチクライアントブリッジ：
  • 📡 Xiaozhi：WebSocket 接続
  • 💻 Claude／Cursor：stdio 接続

セットアップ手順

1. .env ファイルに追加します：

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

2. 通常どおり実行します：

# Same command, different behavior based on environment
python main.py
# OR
docker-compose up

主な機能

• ✅ 設定の競合なし：1 つのサーバーで複数のクライアントを利用できます
• ✅ 並行動作：両方のクライアントを同時に動作させることができます
• ✅ すべてのツールを利用可能：Xiaozhi はすべての Synology MCP ツールにアクセスできます
• ✅ 後方互換性：既存の設定は変更せずに動作します
• ✅ 自動再接続：WebSocket 接続の切断に対応します
• ✅ 環境変数で制御：ブール値フラグで簡単に有効化／無効化できます

起動メッセージ

Claude／Cursor のみのモード：

🚀 Synology MCP Server
==============================
📌 Claude/Cursor only mode (ENABLE_XIAOZHI=false)

両方のクライアントを使用するモード：

🚀 Synology MCP Server with Xiaozhi Bridge
==================================================
🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!

🛠️ 利用可能な MCP ツール

🔐 認証

• synology_status - 認証状態とアクティブなセッションを確認します
• synology_list_nas - settings.json に設定されたすべての NAS ユニットを一覧表示します
• synology_login - Synology NAS で認証します（条件付き）
• synology_logout - セッションからログアウトします（条件付き）

📁 ファイルシステム操作

• list_shares - 利用可能な NAS 共有をすべて一覧表示します
• list_directory - メタデータとともにディレクトリの内容を一覧表示します
  • path（必須）：/ で始まるディレクトリパス
• get_file_info - ファイル／ディレクトリの詳細情報を取得します
  • path（必須）：/ で始まるファイルパス
• get_file_content - 厳密な UTF-8 テキストまたはロスレスな base64 コンテンツを読み取ります
  • path（必須）：/ で始まるファイルパス
  • encoding（省略可）：text（デフォルト）または base64
  • max_bytes（省略可）：読み取る最大生バイト数（デフォルトは 1 MiB、上限は 8 MiB）
• search_files - 名前を指定してファイルやフォルダーを再帰的に検索します
  • path（必須）：検索対象のディレクトリ
  • pattern（必須）：名前に含まれる、大文字と小文字を区別しない部分文字列（例：invoice、.pdf）。ワイルドカードは特別な意味を持ちません。DSM では report と *report* は同じように照合されます。
• create_file - コンテンツを含む新しいファイルを作成します
  • path（必須）：/ で始まる完全なファイルパス
  • content（省略可）：ファイルの内容（デフォルト：空の文字列）
  • overwrite（省略可）：既存のファイルを上書きします（デフォルト：false）
  • encoding（省略可）：text（デフォルト）または厳密な base64。デコード後のコンテンツは 8 MiB に制限されます
• create_directory - 新しいディレクトリを作成します
  • folder_path（必須）：/ で始まる親ディレクトリのパス
  • name（必須）：新しいディレクトリ名
  • force_parent（省略可）：必要に応じて親ディレクトリを作成します（デフォルト：false）
• delete - ファイルまたはディレクトリを削除します（種類は自動判定）
  • path（必須）：/ で始まるファイル／ディレクトリのパス
• rename_file - ファイルまたはディレクトリの名前を変更します
  • path（必須）：現在のファイルパス
  • new_name（必須）：新しいファイル名
• move_file - ファイルを新しい場所に移動します
  • source_path（必須）：移動元のファイルパス
  • destination_path（必須）：移動先のパス
  • overwrite（省略可）：既存のファイルを上書きします
• copy_file - バイトデータを MCP クライアント経由で送信せずに、NAS 内の通常のファイルをコピーします
  • source_path（必須）：コピー元のファイルパス
  • destination_folder（必須）：既存の移動先ディレクトリ。ファイル名はそのまま保持されます
  • overwrite（省略可）：同じ名前の既存ファイルを上書きします（デフォルト：false）

copy_file は移動先のパスとバイト数を検証します。稼働中の SQLite データベースに対する一貫性のあるバックアップ方法ではありません。コピー中に変更される可能性があるデータベースには、SQLite のオンラインバックアップ機構を使用してください。

📥 Download Station の管理

• ds_get_info - Download Station の情報を取得します
• ds_list_tasks - すべてのダウンロードタスクをステータスとともに一覧表示します
  • offset（省略可）：ページネーションのオフセット
  • limit（省略可）：返すタスクの最大数
• ds_create_task - 新しいダウンロードタスクを作成します
  • uri（必須）：ダウンロード URL またはマグネットリンク
  • destination（省略可）：ダウンロード先フォルダのパス
• ds_pause_tasks - ダウンロードタスクを一時停止します
  • task_ids（必須）：タスク ID の配列
• ds_resume_tasks - 一時停止中のタスクを再開します
  • task_ids（必須）：タスク ID の配列
• ds_delete_tasks - ダウンロードタスクを削除します
  • task_ids（必須）：タスク ID の配列
  • force_complete（省略可）：完了したタスクを強制的に削除します
• ds_get_statistics - ダウンロード／アップロード統計情報を取得します

🏥 ヘルスモニタリング

• synology_system_info - システムモデル、シリアル番号、DSM バージョン、稼働時間、温度を取得します
• synology_utilization - CPU、メモリ、スワップ、ディスク I/O のリアルタイム使用率を取得します
• synology_disk_health - SMART 状態、モデル、温度、サイズとともに、すべての物理ディスクを一覧表示します
• synology_disk_smart - 指定したディスクの詳細な SMART 属性を取得します
• synology_volume_status - 状態、サイズ、使用量、ファイルシステムの種類とともに、すべてのボリュームを一覧表示します
• synology_storage_pool - RAID／ストレージプールを、レベル、状態、メンバーディスクとともに一覧表示します
• synology_lun_list - 名前、UUID、サイズ、種類、状態、バックアップボリュームとともに、すべての iSCSI LUN を一覧表示します。LUN がどのターゲットに接続されているかを確認するには、synology_target_list を使用してください。DSM は LUN 側ではマッピングを報告しません。
• synology_lun_get - 単一の iSCSI LUN の詳細を取得します
  • name（必須）：synology_lun_list の出力にある LUN 名または UUID
• synology_network - ネットワークインターフェースの状態と転送速度を取得します

SAN Manager（iSCSI プロビジョニング）

SYNO.Core.ISCSI.LUN と SYNO.Core.ISCSI.Target をラップします。RS1221+ 上の DSM 7.3.2-86009 Update 4 で検証済みです。他の DSM ビルドでは異なる場合があり、DSM 自身の 拒否は独自に判断し直すことなく、そのまま報告されます。

• synology_lun_create - ボリューム上に LUN を作成し、その uuid と lun_id を返します
  • name、location（例：/volume2）、size（バイト単位）は必須です
  • type（任意）：thin（デフォルト、DSM の BLUN）、advanced、file、または DSM の生の 型名を指定します。thin と THIN は異なる点に注意してください。小文字は BLUN の分かりやすい別名で、大文字は DSM 独自のレガシー型です。検証に使用した btrfs ボリュームでは、 シック型は拒否されました。
  • description（任意）
• synology_lun_delete - 破壊的操作。 LUN とその上のすべてを削除します
  • uuid と confirm: true が必須です
• synology_target_list - IQN、認証の種類、各ターゲットにマッピングされた LUN とともに、ターゲットを一覧表示します
• synology_target_get - target_id で指定したターゲットを取得します
• synology_target_create - ターゲットを作成し、その target_id を返します
  • name は必須です。iqn のデフォルト値は iqn.2000-01.com.synology:<name> です
  • chap_user と chap_password を指定すると CHAP が有効になります。両方を指定するか、どちらも指定しないでください。 片方のみ、または空文字列を指定すると、認証なしのターゲットが暗黙に作成されるのではなく拒否されます。 どちらも指定しない場合、接続可能なイニシエーターはすべてターゲットを利用できます。
  • max_sessions（任意、0 = DSM のデフォルト）
• synology_target_map_lun - LUN をターゲットにマッピングします（target_id、lun_uuids）
• synology_target_unmap_lun - 破壊的操作。 LUN のマッピングを解除し、それを使用しているイニシエーターを切断します（target_id、lun_uuids、confirm: true）

これらのツールは、宣言されていない引数を無視せず拒否します。たとえば、chap_user のスペルを 間違えると、認証なしのターゲットが作成されるおそれがあります。また、type のスペルを 間違えると、デフォルト値が暗黙に使用されます。

• synology_ups - UPS の状態、バッテリー残量、電力の測定値を取得します
• synology_services - インストール済みパッケージとその実行状態を一覧表示します
• synology_system_log - 最近のシステムログエントリーを取得します
• synology_health_summary - システム情報、使用率、ディスクの状態、ボリュームの状態をまとめます

🐳 Container Manager

• synology_container_list - Container Manager のコンテナ一覧を表示します
  • offset（任意）：ページネーションのオフセット
  • limit（任意）：返すコンテナの最大数
  • container_type（任意）：コンテナのフィルター（デフォルト：all）
• synology_container_health_summary - コンテナのステータス、ヘルス、再起動回数、イメージを要約します
• synology_container_disk_usage - Container Manager API で利用できる読み取り専用のディスク使用量の概要を表示します
• synology_container_get - Container Manager のコンテナを取得します
  • name（必須）：コンテナ名
• synology_container_start - Container Manager のコンテナを起動します
  • name（必須）：コンテナ名
• synology_container_stop - Container Manager のコンテナを停止します
  • name（必須）：コンテナ名
• synology_container_restart - Container Manager のコンテナを再起動します
  • name（必須）：コンテナ名
• synology_container_delete - Container Manager のコンテナを削除します
  • name（必須）：コンテナ名
  • force（任意）：強制的に削除します（デフォルト：false）
  • preserve_profile（任意）：Synology コンテナプロファイルを保持します（デフォルト：true）
• synology_container_logs - Container Manager のコンテナログを取得します
  • name（必須）：コンテナ名
  • since（任意）：ログの開始時刻／フィルター
  • offset（任意）：ページネーションのオフセット（デフォルト：0）
  • limit（任意）：返すログ行の最大数（デフォルト：1000）
• synology_container_resource - Container Manager のコンテナのリアルタイムのリソース使用量を取得します
  • name（必須）：コンテナ名
• synology_container_project_list - Container Manager のプロジェクト一覧を表示します
• synology_container_project_get - Container Manager のプロジェクトを取得します（Compose、環境、シークレットのフィールドは省略されます）
  • name（必須）：プロジェクト名
• synology_container_project_create - Container Manager のプロジェクト定義を作成して保存します
  • name（必須）：プロジェクト名
  • share_path（必須）：NAS 上のプロジェクトフォルダーのパス
  • content（必須）：Docker Compose の YAML コンテンツ
  • enable_service_portal（任意）：Synology サービスポータルを有効にします（デフォルト：false）
  • service_portal_name（任意）：サービスポータル名
  • service_portal_port（任意）：サービスポータルのポート
  • service_portal_protocol（任意）：サービスポータルのプロトコル（デフォルト：http）
  • Compose 定義を保存します。実体化するには synology_container_project_build を呼び出してください。
• synology_container_project_update - Container Manager のプロジェクトを更新します
  • name（必須）：プロジェクト名
  • content（必須）：Docker Compose の YAML コンテンツ
  • enable_service_portal（任意）：Synology サービスポータルを有効にします
  • service_portal_name（任意）：サービスポータル名
  • service_portal_port（任意）：サービスポータルのポート
  • service_portal_protocol（任意）：サービスポータルのプロトコル
• synology_container_project_start - Container Manager のプロジェクトを起動します
  • name（必須）：プロジェクト名
• synology_container_project_stop - Container Manager のプロジェクトを停止します
  • name（必須）：プロジェクト名
• synology_container_project_restart - Container Manager のプロジェクトを再起動します
  • name（必須）：プロジェクト名
• synology_container_project_build - 保存済みの Container Manager プロジェクトを実体化または再構築します
  • name（必須）：プロジェクト名
• synology_container_project_clean - Container Manager のプロジェクトをクリーンアップします
  • name（必須）：プロジェクト名
• synology_container_project_delete - Container Manager のプロジェクトを削除します
  • name（必須）：プロジェクト名
• synology_container_image_list - Container Manager のイメージ一覧を表示します
  • offset（任意）：ページネーションのオフセット
  • limit（任意）：返すイメージの最大数
  • show_dsm（任意）：DSM イメージを含めます（デフォルト：false）
• synology_container_image_get - Container Manager のイメージを取得します
  • name（必須）：イメージリポジトリ名
  • tag（任意）：イメージタグ（デフォルト：latest）
• synology_container_image_delete - Container Manager のイメージを削除します
  • name（必須）：イメージリポジトリ名
  • tag（任意）：イメージタグ（デフォルト：latest）
• synology_container_image_prune - どのコンテナでも使用されていないイメージを削除します
  • synology_container_image_prune_preview はクリーンアップ前に読み取り専用の候補一覧を表示します
  • Container Manager API のみを使用して、安全に識別できる未使用のタグ付きイメージを削除し、DSM 経由では削除できないダングリングイメージを報告します
  • コンテナ、ネットワーク、ビルドキャッシュは削除しません
• synology_container_image_pull - Container Manager のイメージをプルします
  • repository（必須）：イメージリポジトリ名
  • tag（任意）：イメージタグ（デフォルト：latest）
• synology_container_registry_list - Container Manager のレジストリ一覧を表示します
• synology_container_registry_search - Container Manager のレジストリを検索します
  • query（必須）：イメージの検索クエリ
  • offset（任意）：ページネーションのオフセット
  • limit（任意）：返す結果の最大数
• synology_container_registry_tags - レジストリイメージのタグ一覧を表示します
  • repository（必須）：イメージリポジトリ名
  • offset（任意）：ページネーションのオフセット
  • limit（任意）：返すタグの最大数
• synology_container_registry_download - レジストリイメージをダウンロードします
  • repository（必須）：イメージリポジトリ名
  • tag（任意）：イメージタグ（デフォルト：latest）
• synology_container_network_list - Container Manager のネットワーク一覧を表示します
• synology_container_network_get - Container Manager のネットワークを取得します
  • name（必須）：ネットワーク名
• synology_container_network_create - Container Manager のネットワークを作成します
  • name（必須）：ネットワーク名
  • driver（任意）：ネットワークドライバー（デフォルト：bridge）
  • subnet（任意）：サブネット CIDR
  • gateway（任意）：ゲートウェイ IP
  • ip_range（任意）：割り当て可能な IP 範囲 CIDR
  • enable_ipv6（任意）：IPv6 を有効にします（デフォルト：false）
• synology_container_network_delete - Container Manager のネットワークを削除します
  • name（必須）：ネットワーク名

📦 NFS 管理

• synology_nfs_status - NFS サービスの状態と設定を取得します
• synology_nfs_enable - NFS サービスを有効または無効にします
• synology_nfs_list_shares - NFS 権限とともに、すべての共有フォルダーを一覧表示します
• synology_nfs_set_permission - 共有フォルダーに対する NFS クライアントのアクセス権限を設定します

🔀 ログインポータルのリバースプロキシ

• synology_reverse_proxy_list - リバースプロキシエントリー（コントロールパネル → ログインポータル → 詳細設定 → リバースプロキシ）を、ソース、宛先、HSTS、WebSocket、カスタムヘッダー、アクセス制御プロファイルとともに一覧表示します
• synology_reverse_proxy_get - UUID または説明を指定してエントリーを 1 件取得します
• synology_access_control_profile_list - エントリーから参照できるアクセス制御プロファイルを一覧表示します
• synology_reverse_proxy_create - エントリーを作成します。説明がすでに使用されている場合は拒否されます
• synology_reverse_proxy_update - エントリーの一部のフィールドを変更し、その他のフィールドはそのまま保持します
• synology_reverse_proxy_delete - 破壊的な操作です。 エントリーを削除します（confirm=true が必要です）
• 書き込みのたびに DSM が nginx 設定を再構築して再読み込みします。小型の NAS モデルでは 1 分ほどかかる場合があります。書き込みがタイムアウトした場合は、outcome_unknown: true として報告されます。再試行する前に一覧を確認してください。

🧠 Claude Code / Claude.ai スキル

Claude Code、Claude Desktop、claude.ai のユーザー向けに、このリポジトリには Anthropic Agent Skill が含まれています。このスキルは、適切なツールの選択、複数の NAS がある環境での対象 NAS の指定、複数のツールを呼び出すよりも集約ヘルスチェックを優先する方法、正しいパス規則など、MCP ツールを効果的に使う方法を Claude に教えます。

スキルは skills/synology-nas/ にあり、7 つのドメイン（認証、ファイル、ダウンロード、ヘルス、コンテナ、共有/NFS、ユーザー管理）にわたって段階的に情報を開示します。

インストール：

• Claude Code：フォルダーを ~/.claude/skills/synology-nas/ にコピーまたはシンボリックリンクします
• Claude.ai / Claude Desktop：Skills の設定ページから synology-nas/ フォルダーをアップロードします

このスキルは追加機能として動作し、MCP と併用できます。Synology/NAS 関連のプロンプトに対してのみ起動します。

⚙️ 設定オプション

⚠️ セキュリティに関する警告：専用アカウントを使用してください

この MCP サーバーには、適切な権限を設定した専用の Synology ユーザーアカウントを作成してください。このアカウントは次の条件を満たす必要があります。

• 必要最小限の権限のみを付与する（管理者権限は付与しないでください！）
• MCP サーバーの自動化専用として使用する
• 2FA に対応しました。DSM アカウントで 2FA が有効になっている場合は、以下の 2FA / OTP アカウント セクションを参照し、 otp_code（ワンショット）または device_id（永続）のフィールドを指定してください。 「2FA を使用しない」という以前の案内に従う必要はなくなりました。

settings.json を使用する（推奨）

変数	必須	デフォルト	説明
SYNOLOGY_URL	はい*	-	NAS のベース URL（例：http://192.168.1.100:5000）
SYNOLOGY_USERNAME	はい*	-	認証用のユーザー名
SYNOLOGY_PASSWORD	はい*	-	認証用のパスワード
AUTO_LOGIN	いいえ	true	サーバー起動時に自動ログインします
VERIFY_SSL	いいえ	false	SSL 証明書を検証します
DEBUG	いいえ	false	デバッグログを有効にします
ENABLE_XIAOZHI	いいえ	false	Xiaozhi WebSocket ブリッジを有効にします
XIAOZHI_TOKEN	Xiaozhi のみ	-	Xiaozhi の認証トークン
XIAOZHI_MCP_ENDPOINT	いいえ	wss://api.xiaozhi.me/mcp/	Xiaozhi WebSocket エンドポイント

*自動ログインおよびデフォルトの操作に必要

settings.json を使用する（複数の NAS をサポート）

複数の Synology NAS デバイスを管理する場合は、XDG 標準の設定ディレクトリ（~/.config/synology-mcp/settings.json）を使用します。

mkdir -p ~/.config/synology-mcp
touch ~/.config/synology-mcp/settings.json
chmod 600 ~/.config/synology-mcp/settings.json  # Important: secure permissions!

**注：**これはXDG Base Directory Specificationに準拠しています。~/.config/は、Linux/macOS でユーザー設定ファイルを保存する標準の場所です。XDG_CONFIG_HOME 環境変数を設定すると、場所をカスタマイズできます。

Docker を使用する場合： docker-compose.yml は、~/.config/synology-mcp ディレクトリをコンテナ内の /home/mcpuser/.config/synology-mcp に自動的にマウントするため、Docker でも複数の NAS をすぐに使用できます。

settings.json の形式：

{
  "synology": {
    "nas1": {
      "host": "192.168.1.100",
      "port": 5000,
      "username": "admin",
      "password": "your_password",
      "note": "Primary NAS at home"
    },
    "nas2": {
      "host": "192.168.1.200",
      "port": 5001,
      "username": "admin",
      "password": "your_password",
      "note": "Backup NAS"
    },
    "nas3": {
      "url": "https://nas.example.com",
      "username": "admin",
      "password": "your_password",
      "note": "NAS behind a reverse proxy"
    }
  },
  "xiaozhi": {
    "enabled": false,
    "token": "your_xiaozhi_token",
    "endpoint": "wss://api.xiaozhi.me/mcp/"
  },
  "server": {
    "auto_login": true,
    "verify_ssl": false,
    "session_timeout": 3600,
    "debug": false,
    "log_level": "INFO"
  }
}

設定フィールド：

フィールド	必須	説明
host	はい*	NAS のホスト名または IP アドレス
port	いいえ	API ポート（デフォルト：HTTP は 5000、HTTPS は 5001）
url	はい*	ベース URL 全体（例：https://nas.example.com）。host／port より優先されます。リバースプロキシの背後にある NAS に使用します
username	はい	NAS のユーザー名
password	はい	NAS のパスワード
otp_code	いいえ	1 回限りの 6 桁の 2FA コード（初回ログイン時のみ使用し、その後は削除します）
device_id	いいえ	DSM の長期間有効な信頼済みデバイストークン（did）。以降のすべてのログインで OTP を省略します
note	いいえ	参照用の任意の説明

*各 NAS のエントリには、host または url のいずれかが必要です。

注意：

• ポートが 5001 の場合、サーバーはポート 5001（HTTPS）を使用し、それ以外の場合はデフォルトで HTTP（5000）を使用します
• host／port 形式では常にポートが追加され、ポートからスキームが決まるため、デフォルトの 443 で https://nas.example.com を指定できません。リバースプロキシ構成では url を直接設定してください
• ファイルのアクセス権：セキュリティ確保のため、chmod 600 ~/.config/synology-mcp/settings.json が必要です
• アクセス権が過度に開放されている場合、サーバーは設定の読み込みを拒否します
• .env と settings.json は併用できます（settings.json が優先されます）

⚠️ セキュリティに関する推奨事項

settings.json のファイルアクセス権：

• Linux/macOS（POSIX）： chmod 600 ~/.config/synology-mcp/settings.json が必要です。グループまたはその他のユーザーに読み取り／書き込み権限がある場合、または別のユーザーが所有している場合、サーバーはファイルの読み込みを拒否します。
• **Windows：**アクセス制御には POSIX のモードビットではなく、NTFS ACL が適用されます。サーバーはファイルのセキュリティ記述子を監査し、次の 3 つすべてを満たさない限り読み込みを拒否します。（1）所有者 SID が現在のユーザーと一致する。（2）DACL が存在する（NULL DACL（「全員にフルアクセス」）は拒否されます）。（3）許可リストに含まれないプリンシパルにアクセスを許可する allow-ACE がない。許可リストに含まれるのは、現在のユーザー、NT AUTHORITY\SYSTEM、BUILTIN\Administrators です。継承された Everyone／BUILTIN\Users／Authenticated Users による許可があると、チェックに失敗します。

  • オプションの pywin32 パッケージが必要です：pip install pywin32。**pywin32 がインストールされていない場合、サーバーはフェイルクローズし、settings.json の読み込みを拒否します。**未検証のファイルを使用するリスクを受け入れる運用者は、SYNOLOGY_MCP_ALLOW_UNVERIFIED_WINDOWS_ACL=true を設定することで再び読み込みを許可できます。

  • サーバーは XDG_CONFIG_HOME（デフォルトは Path.home() / ".config"）を使用してファイルの場所を解決します。そのため Windows では、XDG_CONFIG_HOME が設定されていない限り、ファイルは %USERPROFILE%\.config\synology-mcp\settings.json にあります。

  • 管理者権限の PowerShell プロンプトからファイルへのアクセスを制限します（サーバーが読み込むのと同じパスを使用します）。

    # サーバーと同じ方法でパスを解決します：$XDG_CONFIG_HOME が設定されている場合はその値、
    # それ以外の場合は %USERPROFILE%\.config を使用します。上記で説明した上書き設定も反映されます。
    $cfg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$env:USERPROFILE\.config" }
    $f = "$cfg\synology-mcp\settings.json"
    # サーバーの ACL 監査では、所有者が現在のユーザーであること、NULL DACL がないこと、
    # 現在のユーザー、SYSTEM、Administrators 以外に対する許可 ACE がないことが必要です。
    # 以下の手順で、この 3 つすべてを満たします。
    #
    # 組み込みのプリンシパルにはすべて *<SID> 形式を使用してください。「Administrators」、
    # 「Everyone」、「Users」のようなアカウント名は、英語以外の Windows ではローカライズされ
    # （例：ドイツ語の「Administratoren」）、解決できません。ロケールに依存しない SID：
    #   *S-1-1-0            Everyone
    #   *S-1-5-11           Authenticated Users
    #   *S-1-5-32-545       BUILTIN\Users
    #   *S-1-5-32-544       BUILTIN\Administrators
    #
    # 1. ファイルの所有者が現在のユーザーであることを確認します（監査では、他の所有者はすべて
    #    拒否されます）。/setowner には昇格が必要です。
    icacls $f /setowner "${env:USERNAME}"
    # 2. 継承された ACE を削除し、一般的な外部の許可を取り消します。/grant:r は指定したプリンシパル
    #    のみを置き換えるため、先に取り消してください。
    icacls $f /inheritance:r
    icacls $f /remove:g "*S-1-1-0" "*S-1-5-11" "*S-1-5-32-545"
    # ここで `icacls $f` を再実行します。ユーザーまたは Administrators 以外のプリンシパルが
    #    まだ表示される場合は、次を実行します：icacls $f /remove:g "<that principal>"
    # 3. 現在のユーザーと Administrators にフルコントロールを付与します。
    icacls $f /grant:r "${env:USERNAME}:(F)"
    icacls $f /grant:r "*S-1-5-32-544:(F)"   # BUILTIN\Administrators（ロケールに依存しません）
    

    ファイルが新規作成されたばかりの場合、/remove:g の手順は何も変更しません。

  • 確認：icacls "$f" — 自分のユーザーと *S-1-5-32-544（Administrators）のみが表示されるはずです。

SSL 証明書の検証（VERIFY_SSL）：

• 内部 NAS デバイスで自己署名証明書をサポートするため、デフォルトは false です
• NAS に有効な SSL 証明書（例：Let's Encrypt または企業の CA による証明書）がある場合は、VERIFY_SSL=true を設定してください
• VERIFY_SSL=false に設定すると証明書の検証が無効になり、中間者（MITM）攻撃に対して接続が脆弱になります
• 信頼できないネットワークでは、SSL の検証を無効にしないでください

自動ログイン（AUTO_LOGIN）：

• settings.json での利便性を考慮し、デフォルトは true です
• 認証情報は、アクセス許可を 0600 に設定して ~/.config/synology-mcp/settings.json に安全に保存されます
• 手動でログインする場合は、AUTO_LOGIN=false を設定し、synology_login ツールを使用してください

2FA / OTP アカウント（任意）：

MCP サーバーは 2FA が有効な DSM アカウントをサポートしています。使用方法は 2 つあります。

1. synology_login ツールによるワンショット OTP（対話型）：

   { "base_url": "https://nas.lan:5001", "username": "alice", "password": "…", "otp_code": "123456" }
   

   DSM は応答で did（デバイストークン）を返します。この値を settings.json（以下）にコピーすると、以降プロセスを再起動しても OTP を省略できます。

2. 永続的な信頼済みデバイストークン（AUTO_LOGIN=true の場合に推奨）：

   settings.json で NAS ごとに otp_code（ワンショット、初回ログインのみ）や device_id（長期間有効、継続利用）フィールドを追加します。

   {
     "synology": {
       "nas1": {
         "host": "192.168.1.100", "port": 5001,
         "username": "alice", "password": "…",
         "otp_code": "123456",
         "note": "primary — 2FA enabled"
       }
     }
   }
   

   ワークフロー：

   1. otp_code に認証アプリで生成した新しい 6 桁のコードを設定し、サーバーを起動します。
   2. 初回ログインが成功すると、サーバーは次のような警告行をログに記録します： nas1: 2FA bootstrap — copy this device_id into settings.json to skip OTP on future starts: <did> <did> の値をコピーします。
   3. それを device_id に貼り付け、otp_code を削除します。
   4. 以降、DSM はこのプロセスを信頼済みデバイスとして扱います。再起動、DSM エラー 119 の後の再ログイン、コンテナマネージャーのセッションでは、OTP が省略されます。

   device_id が指定されている場合、otp_code より優先されます（信頼済みデバイスの方式）。従来の .env を使用している場合は、ワンショットの SYNOLOGY_OTP_CODE 環境変数を設定できます。永続的な device_id については、長く不透明なトークンを環境変数に適切に収められないため、settings.json に移行してください。

📖 使用例

📁 ファイル操作

✅ ファイルとディレクトリの作成

// List directory
{
  "path": "/volume1/homes"
}

// Search for PDFs
{
  "path": "/volume1/documents", 
  "pattern": ".pdf"
}

// Create new file
{
  "path": "/volume1/documents/notes.txt",
  "content": "My important notes\nLine 2 of notes",
  "overwrite": false
}

🗑️ ファイルとディレクトリの削除

// Delete file or directory (auto-detects type)
{
  "path": "/volume1/temp/old-file.txt"
}

// Move file
{
  "source_path": "/volume1/temp/file.txt",
  "destination_path": "/volume1/archive/file.txt"
}

⬇️ ダウンロード管理

🛠️ ダウンロードタスクの作成

// Create download task
{
  "uri": "https://example.com/file.zip",
  "destination": "/volume1/downloads"
}

// Pause tasks
{
  "task_ids": ["dbid_123", "dbid_456"]
}

🦦 ダウンロード結果

✨ 機能

• ✅ 統一エントリーポイント - 単一の main.py で stdio と WebSocket クライアントの両方をサポートします
• ✅ 環境変数による制御 - ENABLE_XIAOZHI 環境変数でモードを切り替えます
• ✅ マルチクライアント対応 - Claude/Cursor と Xiaozhi から同時にアクセスできます
• ✅ 安全な認証 - RSA による暗号化パスワード送信
• ✅ セッション管理 - 複数の NAS デバイス間でセッションを維持します
• ✅ 完全なファイル操作 - 詳細なメタデータとともに、ファイルの作成、削除、一覧表示、検索、名前変更、移動を行えます
• ✅ ディレクトリ管理 - 安全性を確認しながら、ディレクトリを再帰的に操作します
• ✅ ダウンロードステーション - トレントとダウンロードを完全に管理します
• ✅ Docker 対応 - コンテナ化による簡単なデプロイ
• ✅ 後方互換性 - 既存の設定を変更せずに使用できます
• ✅ エラー処理 - 包括的なエラー報告と復旧

🏗️ アーキテクチャ

ファイル構成

mcp-server-synology/
├── main.py                    # 🎯 Unified entry point
├── src/
│   ├── mcp_server.py         # Standard MCP server
│   ├── multiclient_bridge.py # Multi-client bridge
│   ├── auth/                 # Authentication modules
│   ├── filestation/          # File operations
│   └── downloadstation/      # Download management
├── docker-compose.yml        # Single service, environment-controlled
├── Dockerfile
├── pyproject.toml            # Dependencies (single source of truth)
└── .env                      # Configuration

モード選択

• ENABLE_XIAOZHI=false → main.py → mcp_server.py （stdio のみ）
• ENABLE_XIAOZHI=true → main.py → multiclient_bridge.py → mcp_server.py （両方のクライアント）

シンプルな Claude/Cursor の利用から高度なマルチクライアント構成まで、あらゆるワークフローに最適です！ 🚀