synology-filestation-mcp

An MCP (Model Context Protocol) service built on top of the Synology File Station Web API, allowing AI agents to directly manage files on Synology NAS: browse directories, search, upload/download, create/rename/copy/move/delete, compress/extract, and more.

Supports two operation modes:

• stdio local mode (src/index.js): Run on your personal computer, credentials stored in local environment variables

• Streamable HTTP remote mode (src/http.js): Centrally deployed on a server, shared by multiple users with each user's NAS credentials passed via request headers

Environment Requirements

• Node.js >= 18 (developed and verified with Node 24; for servers with older glibc, use the glibc-217 build from unofficial-builds)

• DSM 7.x (tested on DSM 7.2)

Related MCP server: Synology MCP Server

Installation

npm install

Mode 1: stdio Local Mode

Provide NAS connection information via environment variables (you can also copy .env.example to .env and fill it in; the service automatically loads it on startup):

Taking Claude Desktop as an example, configure claude_desktop_config.json:

{
  "mcpServers": {
    "synology-filestation": {
      "command": "node",
      "args": ["D:/path/to/synology-filestation-mcp/src/index.js"],
      "env": {
        "SYNOLOGY_HOST": "http://192.168.1.1:5000",
        "SYNOLOGY_USER": "your_username",
        "SYNOLOGY_PASSWORD": "your_password"
      }
    }
  }
}

Mode 2: HTTP Remote Mode (Multi-user)

Server startup:

# .env 或环境变量
SYNOLOGY_HOST=http://192.168.1.1:5000   # 默认 NAS 地址（客户端可用 X-NAS-Host 覆盖）
PORT=3000
MCP_AUTH_TOKEN=<随机令牌>                # 设置后客户端必须带 Bearer token

npm run start:http

Features:

• Multi-user: Each MCP session independently holds its own NAS login state (sid pool), no cross-user interference

• Credential Passing: The client provides its own NAS account via request headers X-NAS-User / X-NAS-Password; optionally X-NAS-Host to override the server default; falls back to server environment variables (supports server-managed unified accounts)

• Authentication: After setting MCP_AUTH_TOKEN, all /mcp requests must include Authorization: Bearer <token>

• Session Management: Idle sessions are automatically cleaned up and logged out of NAS after 30 minutes (SESSION_IDLE_TTL_MS is configurable)

• Health Check: GET /health

Client configuration (for clients supporting remote MCP, via URL):

{
  "mcpServers": {
    "synology-filestation": {
      "url": "http://<部署服务器>:3000/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_AUTH_TOKEN>",
        "X-NAS-User": "同事自己的 NAS 账号",
        "X-NAS-Password": "同事自己的 NAS 密码"
      }
    }
  }
}

systemd deployment example:

[Unit]
Description=Synology FileStation MCP (HTTP)
After=network.target

[Service]
WorkingDirectory=/opt/synology-filestation-mcp
ExecStart=/usr/bin/node src/http.js
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

Security Note: In production, it is recommended to use HTTPS (reverse proxy) to terminate TLS, avoiding NAS credentials being transmitted in plaintext in request headers.

Tool List

Testing

SYNOLOGY_HOST=http://192.168.0.196:5000 SYNOLOGY_USER=xxx SYNOLOGY_PASSWORD=xxx npm test

The smoke test performs a complete chain on the NAS: login → list shared folders → create directory → upload → list → get info → rename → copy → search → download and verify content → delete cleanup → logout. The test creates a temporary directory mcp-smoke-test under a writable shared folder and automatically deletes it afterwards.

There is also an extended capability test test/extended.mjs (node test/extended.mjs, also reads environment variables): covers upload/download byte-by-byte verification for 23 file formats (documents/images/videos/audio/archives/databases/VM images), batch copy/move/delete, NAS-side extraction, recycle bin landing check, and permission and security capability boundary probing.

Implementation Notes (DSM 7.x Compatibility)

• On startup, SYNO.API.Info is called first to discover each API's path and version; login goes through SYNO.API.Auth (format=sid).

• SYNO.FileStation.List v2's additional parameter requires JSON array format (e.g., ["size","time"]); comma-separated strings are silently ignored.

• File info queries use SYNO.FileStation.List / getinfo (SYNO.FileStation.Info / get returns File Station server configuration, not file info).

• Upload uses API version 2: in practice, the overwrite parameter is ineffective under v3; identical filenames return 414. The sid is passed via both form field and Cookie: id=<sid> dual channel.

• Copy/move/delete are asynchronous tasks; DSM 7.x's SYNO.FileStation.BackgroundTask only has a list method (no status), filtering by taskid to query progress.

• Search is an asynchronous task; the tool internally polls list until finished.

• The target directory for SYNO.FileStation.Extract must already exist; otherwise it returns 408 (No such file or directory).

• SYNO.FileStation.Compress depends on the account's application permissions in DSM; if it returns 105 (session does not have permission), grant the appropriate permissions in DSM Control Panel for the account.

Capability Boundaries (Not in File Station API Scope)

The following capabilities do not exist in the official File Station API and cannot be provided by this MCP:

• ACL Permission Management: Belongs to DSM Control Panel functionality (SYNO.Core.* private interfaces, not public File Station API).

• Shared Folder AES Encryption: Belongs to DSM Storage Manager functionality (creating/mounting encrypted shared folders).

• Tamper Protection (Read-only/Non-deletable Flags): File Station API has no setting entry; can be indirectly achieved by read-only mounting of shared folders.

• Network Recycle Bin: Deletion behavior automatically follows each shared folder's recycle bin setting (if enabled, deleted files go to <share>/#recycle); the API does not need and cannot individually control it.

Directory Structure

src/
  index.js    stdio 入口（本地模式）
  http.js     HTTP 入口（远程模式，Streamable HTTP + 多用户会话池）
  server.js   共享的 MCP Server 构建（注册全部工具）
  env.js      .env 加载
  client.js   Synology API 客户端：API 发现、认证、请求封装、错误码映射
  tools/      每个 File Station API 一个工具模块
test/
  smoke.mjs      对真实 NAS 的全链路冒烟测试（stdio 层逻辑）
  http-smoke.mjs HTTP 模式自测（鉴权、会话、工具调用、会话关闭）
  extended.mjs   扩展能力测试（多格式、批量、解压、回收站）