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에서 파일을 탐색, 검색, 전송 및 관리합니다. 두 가지 권한 계층에 걸쳐 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

시스템

NAS 상태 및 리소스 사용량을 모니터링합니다. 2개의 읽기 전용 도구:

• get_system_info — 모델, 펌웨어 버전, RAM, 온도, 가동 시간 (모든 사용자에게 작동)

• get_resource_usage — 실시간 CPU 부하, 메모리 사용량, 디스크 I/O, 네트워크 처리량 (관리자 계정 필요)

기능

• 대화형 설정 — 구성 생성, 자격 증명 저장, 2FA 처리 및 Claude Desktop 스니펫을 출력하는 가이드 설정

• 권한 계층 — 도구 등록 시 적용되는 모듈별 READ 또는 WRITE 권한

• 2FA 지원 — 자동 감지; 자동 무음 재인증을 통한 장치 토큰 부트스트랩

• 보안 자격 증명 — macOS, Windows 및 Linux(Claude Desktop 포함)에서 투명하게 작동하는 OS 키링 통합. 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는 2단계 인증(2FA)을 사용하는 DSM 계정을 완벽하게 지원합니다. 자동으로 감지되므로 특별히 설정할 필요가 없습니다:

1. 부트스트랩 — mcp-synology setup이 2FA를 감지하고 OTP 코드를 요청한 후 키링에 장치 토큰을 저장합니다.

2. 무음 재인증 — 이후 로그인 시 장치 토큰을 자동으로 사용합니다(OTP 프롬프트 없음).

3. 인스턴스별 — 각 NAS 구성마다 고유한 장치 토큰을 가지므로 2FA/비-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}.

디버깅

디버그 로깅을 활성화하는 두 가지 방법:

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)과 달리, 사양 우선 코딩은 설계를 별도의 신중한 단계로 취급합니다. docs/specs/에 있는 4개의 사양은 장기간의 대화를 통해 개발되었으며, 트레이드오프를 탐색하고 대안을 거부하며 근거와 함께 결정을 문서화했습니다. 이후 구현 단계에서는 11개의 빌드 단계 전반에 걸쳐 사양을 진실의 원천으로 사용했습니다.

실제 하드웨어를 대상으로 한 라이브 테스트를 통해 사양이 예측할 수 없었던 동작(DSM API 특이점, 검색 서비스 스로틀링, 버전 형식 비호환성)이 드러났습니다. 이러한 발견 사항은 CLAUDE.md와 코드에 문서화되어 있으며, 사양이 갈라지는 경우 코드가 권위 있는 기준이 됩니다.

라이선스

Apache 2.0