mcp-synology

Synology NASデバイス用のMCPサーバーです。Synology DSM APIの機能をClaudeが使用できるMCPツールとして公開します。

synology-mcpからの移行

synology-mcp (v0.3.x以前) からアップグレードする場合、パッケージ名が変更されています。移行スクリプトが設定、状態、キーリングエントリ、およびClaude Desktopの設定を自動的に処理します：

# Download and run the migration script
curl -O https://raw.githubusercontent.com/cmeans/mcp-synology/main/scripts/migrate-from-synology-mcp.py
python migrate-from-synology-mcp.py          # dry run — preview changes
python migrate-from-synology-mcp.py --apply  # apply changes

このスクリプトは以下を移行します：

• 設定ディレクトリ (~/.config/synology-mcp/ → ~/.config/mcp-synology/)

• 状態ディレクトリ (~/.local/state/synology-mcp/ → ~/.local/state/mcp-synology/)

• キーリングの認証情報

• Claude Desktopの claude_desktop_config.json (コマンドとパスを更新)

破壊的変更の詳細については CHANGELOG.md を参照してください。

サポートされているモジュール

File Station

NAS上のファイルの閲覧、検索、転送、管理を行います。2つの権限階層にわたる14のツール：

• READ — list_shares, list_files, list_recycle_bin, search_files, get_file_info, get_dir_size, download_file

• WRITE — create_folder, rename, copy_files, move_files, delete_files, restore_from_recycle_bin, upload_file

System

NASの健全性とリソース使用率を監視します。2つの読み取り専用ツール：

• get_system_info — モデル、ファームウェアバージョン、RAM、温度、稼働時間 (全ユーザーが利用可能)

• get_resource_usage — リアルタイムのCPU負荷、メモリ使用量、ディスクI/O、ネットワークスループット (管理者アカウントが必要)

機能

• インタラクティブなセットアップ — 設定の作成、認証情報の保存、2FAの処理、Claude Desktop用スニペットの生成を行うガイド付き設定

• 権限階層 — モジュールごとのREADまたはWRITE権限をツール登録時に適用

• 2FAサポート — 自動検出機能。デバイストークンのブートストラップと自動的なサイレント再認証

• セキュアな認証情報 — macOS、Windows、Linuxで透過的に動作するOSキーリング統合 (Claude Desktopからも利用可能)。docs/credentials.md を参照。

• マルチNAS — 個別の設定、認証情報、状態を持つ複数のNASデバイスを管理

クイックスタート

1. セットアップの実行

uvx mcp-synology setup

uv が必要です。uvx は最新バージョンを自動的にダウンロードして実行するため、個別のインストール手順は不要です。

セットアップでは、NASのホスト名、認証情報、設定の入力を求められます。アカウントで2FAが有効な場合、OTPコードの入力を求められ、将来の自動ログイン用にデバイストークンが保存されます。

最後に、コピー＆ペースト可能なClaude Desktop用のJSONスニペットが表示されます。

2. Claude Desktopへの追加

セットアップで生成されたスニペットを claude_desktop_config.json にコピーし、Claude Desktopを再起動します。以下のような形式になります：

{
  "mcpServers": {
    "synology-nas": {
      "command": "uvx",
      "args": ["mcp-synology", "serve", "--config", "~/.config/mcp-synology/nas.yaml"]
    }
  }
}

設定ファイル名 (例: nas.yaml) は接続の識別子としても機能します。NASに合わせて名前を付けることができます (例: home-nas.yaml, office-nas.yaml)。

Linuxでは、サーバーはキーリングアクセスのためにD-Busセッションソケットを自動検出します。自動検出に失敗した場合は、Claude Desktopの設定に "env": {"DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/<uid>/bus"} を追加してください。セットアップコマンドは、生成されるスニペットにこれを含めています。

3. 検証

uvx mcp-synology check                # Validates credentials work
uvx mcp-synology setup --list         # Shows all configured NAS instances

代替案: グローバルインストール

永続的なインストールを希望する場合 (呼び出しごとのダウンロードを回避)：

uv tool install mcp-synology
mcp-synology setup
mcp-synology check

代替案: 環境変数のみのモード

SYNOLOGY_HOST が設定されている場合、設定ファイルは不要です。DockerやCI環境で便利です：

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-synology", "serve"],
      "env": {
        "SYNOLOGY_HOST": "192.168.1.100",
        "SYNOLOGY_USERNAME": "your_user",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

またはCLIから：

SYNOLOGY_HOST=192.168.1.100 uvx mcp-synology check

2FAサポート

mcp-synologyは、二要素認証（2FA）を使用するDSMアカウントを完全にサポートしています。自動検出されるため、特別な設定は不要です：

1. ブートストラップ — mcp-synology setup が2FAを検出し、OTPコードの入力を求め、デバイストークンをキーリングに保存します

2. サイレント再認証 — 以降のログインではデバイストークンが自動的に使用されます (OTP入力は不要)

3. インスタンスごと — 各NAS設定が独自のデバイストークンを持つため、2FA有効/無効が混在する環境でも問題なく動作します

デバイストークンは、DSM上で明示的に取り消すまで保持されます (個人 > セキュリティ > サインインアクティビティ)。トークンが取り消された場合は、再度 mcp-synology setup を実行してブートストラップを行ってください。

キーリングと認証情報

認証情報はOSのキーリングに保存され、透過的にアクセスされます：

認証情報の解決順序: 環境変数 > 設定ファイル > キーリング。明示的なソースが暗黙のデフォルトを上書きします。

キーリングのない環境 (Docker、CI) では、環境変数または設定ファイル内のインライン認証情報を使用してください。

キーリングのサービス名、マルチNAS設定、保存された認証情報の確認/削除方法については docs/credentials.md を参照してください。

アップデート

mcp-synologyはアップデートを確認し、Claude Desktopの会話内で通知します。各セッションの最初のツール応答に、PyPIで新しいバージョンが利用可能な場合の通知が含まれます。

CLIからアップデートを管理するには：

mcp-synology --check-update                 # Check for a newer version
mcp-synology --auto-upgrade enable           # Auto-upgrade on each interactive run
mcp-synology --revert                        # Roll back to previous version
mcp-synology --revert 0.1.0                  # Roll back to a specific version

アップデート通知を無効にするには、設定ファイル（トップレベル）に追加します：

# ~/.config/mcp-synology/config.yaml
check_for_updates: false

設定

インタラクティブなセットアップにより設定ファイルが作成されます。手動設定や高度なオプションについては examples/ を参照してください：

• config-minimal.yaml — 最小限の設定

• config-power-user.yaml — HTTPS、カスタムタイムアウト、ログ記録、指示

• config-docker.yaml — 環境変数駆動型

マルチNAS

各NASは独自の設定ファイル、認証情報、Claude Desktopエントリを持ちます。設定ファイル名が自然な識別子として機能します (例: home-nas.yaml, media-server.yaml)。

alias を設定して、Claudeに接続の表示名を与えます：

# ~/.config/mcp-synology/home-nas.yaml
alias: HomeNAS

エイリアスはMCPサーバー名 (例: synology-HomeNAS) に表示されるため、ClaudeはどのNASと通信しているかを認識できます。

カスタム指示

カスタム指示を使用すると、ClaudeがNASツールとどのように対話するかを調整できます。これは以下の場合に便利です：

• 複数のNAS接続 — タスクに応じて優先する接続をClaudeに指示する ("メディアにはこれを使用し、ユーザー間操作には管理者用を使用する")

• 安全ガードレール — "削除前に必ず確認する" や "/Backupsには絶対に触れない" などのルールを追加する

• コンテキスト — NASの内容を説明する ("これはメディアサーバーであり、/videoにはジャンル別に整理されたライブラリがある")

コンテキストの追加 — custom_instructions は組み込みプロンプトの前に付加されます (優先度が高い)：

# ~/.config/mcp-synology/config.yaml
custom_instructions: |
  This is the admin NAS with elevated privileges.
  Prefer this connection for file operations requiring cross-user access.
  Never delete files from /Backups without explicit confirmation.

完全な制御 — instructions_file は組み込みプロンプトを完全に置き換えます。組み込みの server.md を開始点としてコピーしてください：

# ~/.config/mcp-synology/config.yaml
instructions_file: ~/.config/mcp-synology/my-instructions.md

どちらもテンプレート変数 {display_name}, {instance_id}, {host}, {port} をサポートしています。

デバッグ

デバッグログを有効にする2つの方法：

mcp-synology check --verbose                          # --verbose flag on setup/check
SYNOLOGY_LOG_LEVEL=debug mcp-synology serve           # env var, works for all commands

または設定ファイルで永続的に設定：

# ~/.config/mcp-synology/config.yaml
logging:
  level: debug
  file: ~/.local/state/mcp-synology/nas/server.log  # optional, logs to stderr by default

デバッグ出力には、すべてのDSM APIリクエスト/レスポンス (パスワードはマスクされます)、認証情報の解決手順、設定の検出、バージョンネゴシエーション、モジュール登録の決定が含まれます。

貢献

ビルドコマンド、テスト、統合テストのセットアップ、設計ドキュメントについては DEVELOPMENT.md を参照してください。

謝辞

このプロジェクトは Spec-First Coding (仕様先行コーディング) アプローチを使用して構築されました。これは、設計が実装に先行し、仕様が両者の間の契約となる人間とAIのコラボレーションモデルです。

やりたいことを説明してAIにその場でコードを生成させる「vibe coding」とは異なり、Spec-First Codingでは設計を独立した慎重なフェーズとして扱います。docs/specs/ にある4つの仕様は、トレードオフの検討、代替案の拒否、根拠を伴う決定の文書化といった長期的な対話を通じて開発されました。その後、実装は11のビルドフェーズ全体で仕様を信頼できる唯一の情報源として使用しました。

実際のハードウェアに対するライブテストにより、仕様では予測できなかった動作 (DSM APIの癖、検索サービスの制限、バージョン形式の非互換性) が明らかになりました。これらの発見は CLAUDE.md とコードに文書化されており、仕様が乖離している場合はコードが優先されます。

ライセンス

Apache 2.0