Synology MCP Server

💾 Synology MCP服务器

Synology MCP Server

用于Synology NAS设备的模型上下文协议（MCP）服务器。使AI助手能够通过安全身份验证和会话管理来管理文件和下载。

🌟 新功能：统一服务器同时支持Claude/Cursor（stdio）和小智（WebSocket）！

🚀 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

扩展配置（克劳德/光标+小智）：

# 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/

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 dependencies
pip install -r requirements.txt

# Run with environment control
python main.py

🔌 客户端设置

🤖 克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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"
    }
  }
}

↗️ 光标

添加到光标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"
    }
  }
}

🔄 继续（VS代码扩展）

添加到“继续”配置(.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的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"
      }
    }
  }
}

🌟 小智集成

新的统一架构同时支持两个客户端！

运作原理

• 启用_小智=假 （默认）：通过stdio为Claude/Cursor提供标准MCP服务器
• 启用_小智=真：支持以下两者的多客户端网桥：

- 📡 小智：WebSocket连接 - 💻 克劳德/光标：stdio连接

设置步骤

1. 添加到.env文件中：

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

1. 正常运行：

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

主要特点

• ✅ 零配置冲突：一台服务器，多个客户端
• ✅ 并行操作：两个客户端可以同时工作
• ✅ 所有可用工具：晓志可以访问所有Synology MCP工具
• ✅ 向后兼容：现有设置不变
• ✅ 自动重新连接：处理WebSocket连接中断
• ✅ 环境受控：用于启用/禁用的简单布尔标志

启动消息

克劳德/仅光标模式：

🚀 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 （必需）：文件路径以开头 /

• search_files -搜索与模式匹配的文件

- path （必填）：搜索目录 - pattern （必填）：搜索模式（例如。， *.pdf)

• create_file -创建包含内容的新文件

- path （必需）：以开头的完整文件路径 / - content （可选）：文件内容（默认值：空字符串） - overwrite （可选）：覆盖现有文件（默认值：false）

• create_directory -创建新目录

- folder_path （必需）：父目录路径以开头 / - name （必填）：新目录名 - force_parent （可选）：如果需要，创建父目录（默认值：false）

• delete -删除文件或目录（自动检测类型）

- path （必需）：以开头的文件/目录路径 /

• rename_file -重命名文件或目录

- path （必需）：当前文件路径 - new_name （必填）：新文件名

• move_file -将文件移动到新位置

- source_path （必需）：源文件路径 - destination_path （必填）：目标路径 - overwrite （可选）：覆盖现有文件

📥 下载站管理

• ds_get_info -获取下载站信息
• 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_network -获取网络接口状态和传输速率
• synology_ups -获取UPS状态、电池电量、电源读数
• synology_services -列出已安装的软件包及其运行状态
• synology_system_log -获取最近的系统日志条目
• synology_health_summary -聚合系统信息、利用率、磁盘运行状况和卷状态

📦 NFS管理

• synology_nfs_status -获取NFS服务状态和配置
• synology_nfs_enable -启用或禁用NFS服务
• synology_nfs_list_shares -列出所有具有NFS权限的共享文件夹
• synology_nfs_set_permission -设置共享文件夹上的NFS客户端访问权限

🧠 克劳德代码/Claude.ai技能

对于Claude Code、Claude Desktop和Claude.ai用户，此仓库提供了一种Anthropic Agent技能，教Claude如何有效地使用MCP工具——选择正确的工具，在多NAS设置中瞄准正确的NAS，更喜欢聚合健康检查而不是扇出调用，并使用正确的路径约定。

技能生活在 skills/synology-nas/ 并在六个域（身份验证、文件、下载、健康状况、共享/NFS、用户管理）中使用渐进式披露。

安装：

• 克劳德代码：将文件夹复制或符号链接到 ~/.claude/skills/synology-nas/
• Claude.ai/克劳德桌面：上传 synology-nas/ 通过技能设置页面访问文件夹

该技能纯粹是累加的——它与MCP一起工作，只在Synology/NAS相关的提示下触发。

⚙️ 配置选项

⚠️ 安全警告：使用专用帐户 对于此MCP服务器，请创建具有适当权限的专用Synology用户帐户。该账户应： - 未启用2FA -MCP服务器无法处理2FA提示，身份验证将失败 - 仅具有所需的最小权限（不是管理员！） - 仅用于MCP服务器自动化 使用2FA的主帐户是危险的-如果自动登录失败，您可能会被锁定在NAS之外！

使用settings.json（推荐）

\*自动登录和默认操作需要

使用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基本目录规范 - ~/.config/ 是Linux/macOS上用户配置文件的标准位置。您可以通过设置来自定义位置 XDG_CONFIG_HOME 环境变量。

使用Docker： docker-compose.yml会自动挂载您的 ~/.config/synology-mcp 目录放入容器中 /home/mcpuser/.config/synology-mcp，因此多NAS也可以与Docker一起开箱即用。

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"
    }
  },
  "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"
  }
}

配置字段：

笔记：

• 如果端口为5001，服务器将使用端口5001（HTTPS），否则默认为HTTP（5000）
• 文件权限： chmod 600 ~/.config/synology-mcp/settings.json 是安全所必需的
• 如果权限太开放，服务器将拒绝加载设置
• .env和settings.json都可以一起使用（settings.json优先）

⚠️ 安全建议

SSL证书验证（VERIFY_SSL）：

• 默认值为 false 支持内部NAS设备上的自签名证书
• 如果您的NAS具有有效的SSL证书（例如，来自Let's Encrypt或公司CA），请设置 VERIFY_SSL=true
• 设置 VERIFY_SSL=false 禁用证书验证并使您的连接容易受到中间人（MITM）攻击
• 从不在不受信任的网络上禁用SSL验证

自动登录（Auto_Login）：

• 默认值为 true 方便使用settings.json
• 凭据安全地存储在 ~/.config/synology-mcp/settings.json 具有0600权限
• 如果您更喜欢手动登录，请设置 AUTO_LOGIN=false 并使用 synology_login 工具

📖 用法示例

📁 文件操作

✅ 创建文件和目录

File Creation

// 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
}

🗑️ 删除文件和目录

File Deletion

// 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 环境变量
• ✅ 多客户端支持 -克劳德/光标+小智同时访问
• ✅ 安全认证 -RSA加密密码传输
• ✅ 会话管理 -跨多个NAS设备的持久会话
• ✅ 完成文件操作 -创建、删除、列出、搜索、重命名、移动具有详细元数据的文件
• ✅ 目录管理 -带安全检查的递归目录操作
• ✅ 下载中心 -完整的torrent和下载管理
• ✅ 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
├── requirements.txt
└── .env                      # Configuration

模式选择

• ENABLE_XIAOZHI=false → main.py → mcp_server.py （仅限stdio）
• ENABLE_XIAOZHI=true → main.py → multiclient_bridge.py → mcp_server.py （两个客户）

非常适合任何工作流程-从简单的Claude/Cursor使用到高级的多客户端设置！ 🚀