群晖同步服务器

Name: 群晖同步服务器
Author: atom2ueki

作者：atom2ueki39 星标更新：2025-06-26

安装使用来源：spider==github.com

项目介绍

技术文档摘要

💾 Synology MCP Server

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

🌟 新功能：统一服务器同时支持Claude/Cursor（标准I/O）和Xiaozhi（WebSocket）！

🚀 快速开始使用Docker

1️⃣ 环境设置

# 克隆仓库
git clone https://github.com/atom2ueki/mcp-server-synology.git
cd mcp-server-synology

# 创建环境文件
cp env.example .env

2️⃣ 配置.env文件

基本配置（仅限Claude/Cursor）：

# 必需：Synology NAS连接
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# 可选：启动时自动登录
AUTO_LOGIN=true
VERIFY_SSL=false

扩展配置（同时支持Claude/Cursor和Xiaozhi）：

# 必需：Synology NAS连接
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# 可选：启动时自动登录
AUTO_LOGIN=true
VERIFY_SSL=false

# 启用Xiaozhi支持
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/

3️⃣ 使用Docker运行

一个简单的命令支持两种模式：

# 仅Claude/Cursor模式（默认，如果未设置ENABLE_XIAOZHI）
docker-compose up -d

# 同时支持Claude/Cursor和Xiaozhi模式（如果在.env中设置了ENABLE_XIAOZHI=true）
docker-compose up -d

# 构建并运行
docker-compose up -d --build

4️⃣ 替代方案：本地Python

# 安装依赖
pip install -r requirements.txt

# 使用环境控制运行
python main.py

🔌 客户端设置

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

🌟 Xiaozhi集成

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

工作原理

ENABLE_XIAOZHI=false（默认）：通过标准I/O为Claude/Cursor提供标准MCP服务器
ENABLE_XIAOZHI=true：多客户端桥接支持以下内容：
- 📡 Xiaozhi：WebSocket连接
- 💻 Claude/Cursor：标准I/O连接

设置步骤

添加到您的.env文件：

ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here

正常运行：

# 基于环境的不同行为，相同的命令
python main.py
# 或者
docker-compose up

主要特点

✅ 零配置冲突：一个服务器，多个客户端
✅ 并行操作：两个客户端可以同时工作
✅ 所有工具可用：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_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_URL`	是*	-	NAS基础URL（例如，`http://192.168.1.100:5000`）
`SYNOLOGY_USERNAME`	是*	-	身份验证用户名
`SYNOLOGY_PASSWORD`	是*	-	身份验证密码
`AUTO_LOGIN`	否	`true`	服务器启动时自动登录
`VERIFY_SSL`	否	`true`	验证SSL证书
`DEBUG`	否	`false`	启用调试日志
`ENABLE_XIAOZHI`	否	`false`	启用Xiaozhi WebSocket桥接
`XIAOZHI_TOKEN`	仅Xiaozhi	-	Xiaozhi身份验证令牌
`XIAOZHI_MCP_ENDPOINT`	否	`wss://api.xiaozhi.me/mcp/`	Xiaozhi WebSocket端点

*用于自动登录和默认操作

📖 使用示例

📁 文件操作

✅ 创建文件和目录

文件创建

// 列出目录
{
  "path": "/volume1/homes"
}

// 搜索PDF
{
  "path": "/volume1/documents", 
  "pattern": "*.pdf"
}

// 创建新文件
{
  "path": "/volume1/documents/notes.txt",
  "content": "My important notes\nLine 2 of notes",
  "overwrite": false
}

🗑️ 删除文件和目录

文件删除

// 删除文件或目录（自动检测类型）
{
  "path": "/volume1/temp/old-file.txt"
}

// 移动文件
{
  "source_path": "/volume1/temp/file.txt",
  "destination_path": "/volume1/archive/file.txt"
}

⬇️ 下载管理

🛠️ 创建下载任务

下载样本

// 创建下载任务
{
  "uri": "https://example.com/file.zip",
  "destination": "/volume1/downloads"
}

// 暂停任务
{
  "task_ids": ["dbid_123", "dbid_456"]
}

🦦 下载结果

下载结果

✨ 特性

✅ 统一入口点 - 单个main.py支持标准I/O和WebSocket客户端
✅ 环境控制 - 通过ENABLE_XIAOZHI环境变量切换模式
✅ 多客户端支持 - 同时支持Claude/Cursor和Xiaozhi访问
✅ 安全认证 - RSA加密密码传输
✅ 会话管理 - 在多个NAS设备之间持久会话
✅ 完整的文件操作 - 创建、删除、列出、搜索、重命名、移动文件，带有详细元数据
✅ 目录管理 - 带有安全检查的递归目录操作
✅ 下载站 - 完整的种子和下载管理
✅ Docker支持 - 易于容器化部署
✅ 向后兼容 - 现有配置无需更改即可工作
✅ 错误处理 - 综合错误报告和恢复

🏗️ 架构

文件结构

mcp-server-synology/
├── main.py                    # 🎯 统一入口点
├── src/
│   ├── mcp_server.py         # 标准MCP服务器
│   ├── multiclient_bridge.py # 多客户端桥接
│   ├── auth/                 # 认证模块
│   ├── filestation/          # 文件操作
│   └── downloadstation/      # 下载管理
├── docker-compose.yml        # 单服务，环境控制
├── Dockerfile
├── requirements.txt
└── .env                      # 配置

模式选择

ENABLE_XIAOZHI=false → main.py → mcp_server.py（仅标准I/O）
ENABLE_XXIAOZHI=true → main.py → multiclient_bridge.py → mcp_server.py（两个客户端）

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