synology-filestation-mcp

Synology File Station Web API를 기반으로封装한 MCP(Model Context Protocol) 서비스입니다. AI Agent가 Synology NAS의 파일을 직접 관리할 수 있도록 지원합니다: 디렉터리 탐색, 검색, 업로드/다운로드, 생성/이름 변경/복사/이동/삭제, 압축/해제 등.

두 가지 실행 모드를 지원합니다:

• stdio 로컬 모드(src/index.js): 개인 PC에서 실행하며, 자격 증명은 로컬 환경 변수에 저장합니다.

• Streamable HTTP 원격 모드(src/http.js): 서버에集中 배포하여 여러 사용자가 사용하며, 각자의 NAS 자격 증명은 요청 헤더를 통해 전달합니다.

환경 요구 사항

• Node.js >= 18 (개발은 Node 24로 검증됨; 낮은 glibc 버전의 서버는 unofficial-builds의 glibc-217 빌드 사용 가능)

• DSM 7.x (DSM 7.2에서 실제 테스트 완료)

Related MCP server: Synology MCP Server

설치

npm install

모드 1: stdio 로컬 모드

환경 변수를 통해 NAS 연결 정보를 제공합니다 (.env.example을 복사하여 .env로 만들고 작성하면 서비스 시작 시 자동 로드):

Claude Desktop을 예로 들어, 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"
      }
    }
  }
}

모드 2: HTTP 원격 모드 (다중 사용자 공용)

서버 시작:

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

npm run start:http

특징:

• 다중 사용자: 각 MCP 세션이 독립적으로 NAS 로그인 상태(sid 풀)를 유지하며, 서로 간섭하지 않습니다.

• 자격 증명 전달: 클라이언트는 요청 헤더를 통해 자신의 NAS 계정(X-NAS-User/X-NAS-Password)을 제공하며, 선택적으로 X-NAS-Host로 서버 기본값을 덮어쓸 수 있습니다. 기본값은 서버 환경 변수로 폴백됩니다(서버에서 통합 관리하는 계정 지원).

• 인증: MCP_AUTH_TOKEN이 설정되면 모든 /mcp 요청에 Authorization: Bearer <token>이 필요합니다.

• 세션 관리: 30분 동안 유휴 상태이면 자동 정리 및 NAS 로그아웃 수행 (SESSION_IDLE_TTL_MS로 조정 가능).

• 헬스 체크: GET /health

클라이언트 구성 (원격 MCP를 지원하는 클라이언트, url 방식):

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

systemd 배포 예시:

[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

보안 참고: 프로덕션 환경에서는 HTTPS(리버스 프록시)를 사용하여 TLS를 종료하고, NAS 자격 증명이 요청 헤더에서 평문으로 전송되지 않도록 하는 것이 좋습니다.

도구 목록

테스트

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

스모크 테스트는 NAS에 대해 전체 체인을 실행합니다: 로그인 → 공유 폴더 목록 → 디렉터리 생성 → 업로드 → 목록 → 정보 조회 → 이름 변경 → 복사 → 검색 → 다운로드 및 내용 검증 → 삭제 정리 → 로그아웃. 테스트는 쓰기 가능한 공유 폴더 아래에 mcp-smoke-test 임시 디렉터리를 생성하고, 종료 후 자동으로 삭제합니다.

확장 기능 테스트 test/extended.mjs도 있습니다 (node test/extended.mjs 실행, 동일하게 환경 변수 읽음): 23가지 파일 형식(문서/이미지/동영상/오디오/압축 파일/데이터베이스/가상 머신 이미지)의 업로드/다운로드 바이트 단위 검증, 일괄 복사/이동/삭제, NAS 측 압축 해제, 휴지통 위치 확인, 권한 및 보안 기능 경계 탐색을 포함합니다.

구현 설명 (DSM 7.x 호환성)

• 시작 시 먼저 SYNO.API.Info를 호출하여 각 API의 path와 version을 확인하고, 로그인은 SYNO.API.Auth(format=sid)를 사용합니다.

• SYNO.FileStation.List v2의 additional 매개변수는 JSON 배열 형식(예: ["size","time"])이어야 하며, 쉼표로 구분된 문자열은 자동으로 무시됩니다.

• 파일 정보 조회는 SYNO.FileStation.List / getinfo를 사용합니다 (SYNO.FileStation.Info / get은 File Station 서버 구성을 반환하며, 파일 정보가 아닙니다).

• 업로드는 API version 2를 사용합니다: 실제 테스트 결과 v3에서는 overwrite 매개변수가 작동하지 않으며, 동일한 이름의 파일이 있으면 414를 반환합니다. 업로드 시 sid는 폼 필드와 Cookie: id=<sid> 이중 채널로 전달됩니다.

• 복사/이동/삭제는 비동기 작업입니다. DSM 7.x의 SYNO.FileStation.BackgroundTask에는 list 메서드만 있으며(status 없음), taskid로 필터링하여 진행률을 조회합니다.

• 검색은 비동기 작업이며, 도구 내부에서 list를 finished 상태가 될 때까지 폴링합니다.

• SYNO.FileStation.Extract의 대상 디렉터리는 미리 존재해야 하며, 그렇지 않으면 408(No such file or directory)을 반환합니다.

• SYNO.FileStation.Compress는 DSM의 애플리케이션 권한에 따라 계정이 의존합니다. 105(session does not have permission)가 반환되면 DSM 제어판에서 해당 계정에 적절한 권한을 부여해야 합니다.

기능 경계 (File Station API 범위에 속하지 않음)

다음 기능은 공식 File Station API에 존재하지 않으므로, 본 MCP에서 제공할 수 없습니다:

• ACL 권한 관리: DSM 제어판 기능에 속합니다 (SYNO.Core.* 비공개 인터페이스, 공개 File Station API 아님).

• 공유 폴더 AES 암호화: DSM 스토리지 관리 기능에 속합니다 (암호화된 공유 폴더 생성/마운트).

• 변조 방지(읽기 전용/삭제 불가 표시): File Station API에 설정 진입점이 없습니다. 공유 폴더를 읽기 전용으로 마운트하여 간접적으로 구현할 수 있습니다.

• 네트워크 휴지통: 삭제 동작은 각 공유 폴더의 휴지통 설정을 자동으로 따릅니다(설정 시 삭제된 파일은 <share>/#recycle로 이동). API에서 별도로 제어할 필요가 없으며, 제어할 수도 없습니다.

디렉터리 구조

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   扩展能力测试（多格式、批量、解压、回收站）