dsm-mcp

Synology DSM 및 Container Manager용 Model Context Protocol 서버입니다. MCP 클라이언트(Claude)가 NAS를 검사하고 Synology Web API를 통해 컨테이너를 직접 관리할 수 있게 해줍니다. 브라우저도, 요청별 DSM 로그인/2FA도 필요 없습니다. 서버는 전용 서비스 계정으로 한 번 로그인하고 세션을 자체적으로 유지하므로, 사실상 원하셨던 "만료되지 않는 세션"이 됩니다. Claude는 다시 인증하지 않습니다.

arr-mcp의 동반 프로젝트입니다. 동일한 구조(Python, streamable-HTTP, bearer 인증)에 다른 포트(8788)를 사용하며, Synology 전용 클라이언트입니다.

도구

* = 쓰기 작업(컨테이너 시작/중지/재시작). dsm_raw_call은 쓰기를 포함한 모든 DSM 메서드를 호출할 수 있습니다. DSM API의 버전별 차이를 우회할 수 있는 탈출구입니다.

DSM API에 대해 (이것을 읽으세요)

Synology의 Web API는 검색 기반이며 버전/모델에 따라 다릅니다. 각 도구는 호출 시점에 SYNO.API.Info를 통해 올바른 CGI 경로와 버전을 확인하므로, 시스템/스토리지/사용률 도구는 안정적입니다. Docker/Container Manager 메서드는 DSM 릴리스에 따라 문서화가 일관되지 않습니다. dsm_docker_logs, dsm_docker_projects 또는 작업의 매개변수가 사용 중인 DSM과 일치하지 않으면 dsm_api_discover를 실행(SYNO.Docker 또는 all 쿼리)하여 NAS가 실제로 노출하는 항목을 확인한 다음 dsm_raw_call로 구동하세요. 하드코딩된 항목 중 실시간으로 우회할 수 없는 것은 없습니다.

Related MCP server: Synology_MCP

서비스 계정 (먼저 이 작업을 하세요)

이것을 관리자 계정에 연결하지 마세요. DSM에서:

1. 제어판 → 사용자 및 그룹 → 만들기에서 claude-svc 같은 사용자를 생성합니다.

2. 필요한 권한만 부여합니다: Container Manager 앱 권한, 시스템/스토리지 읽기. DSM 버전에서 Docker API를 관리자 없이 허용한다면 administrators 그룹에서 제외하세요. 관리자가 필요하다면 여기서만 사용하는 별도의 관리자 그룹 계정을 선호합니다.

   • 참고: 현재 기준으로, 서비스 계정은 컨테이너 관리자 엔드포인트에 접근하려면 administrators 그룹의 구성원이어야 합니다.

3. 이 계정에서 2FA를 비활성화합니다(데몬은 회전 코드를 입력할 수 없습니다). 정책에서 2FA를 강제한다면 신뢰할 수 있는 기기를 한 번 등록하고 해당 토큰을 DSM_DEVICE_ID에 넣으세요.

4. 선택적으로 LAN으로 제한합니다(제어판 → 보안 → 방화벽/IP 규칙). MCP 서버는 LAN에 있고 터널만 공개되므로.

설정

cp config.example.env .env
# edit .env: DSM_URL, the service account + password, a strong MCP_AUTH_TOKEN.
# HTTPS with the self-signed cert? use :5001 and set DSM_VERIFY_SSL=false

docker compose up -d --build
docker logs -f dsm-mcp        # confirm it starts; auth runs on the first tool call

Docker 없이 개발 실행:

pip install -r requirements.txt
set -a; source .env; set +a
python server.py

Claude에 노출하기

엔드포인트: https://<your-hostname>/mcp. arr-mcp와 동일합니다:

1. 터널링합니다(전용 cloudflared 또는 기존 Jellyfin 터널의 호스트 이름 → http://dsm-mcp:8788), 이상적으로는 Cloudflare Access 뒤에.

2. Claude → 설정 → 커넥터 → 사용자 지정 커넥터 → /mcp URL, Authorization: Bearer <MCP_AUTH_TOKEN> 포함.

보안 참고 사항

• 이 서버는 컨테이너를 재시작하고 시스템 내부를 읽을 수 있으며 DSM 사용자로 인증합니다. 계정을 최소 권한으로 유지하고, 2FA 비활성화를 오직 해당 LAN 계정에만 적용하며, 엔드포인트를 항상 bearer 토큰(이상적으로는 Cloudflare Access) 뒤에 두세요.

• 자격 증명은 .env(git/docker 무시)에만 존재합니다. MCP 클라이언트는 이를 볼 수 없습니다. 도구 결과만 볼 수 있습니다.

• 계정 삭제, DSM 설정 변경, 볼륨/풀 파괴 도구는 노출되지 않습니다. dsm_raw_call은 의도적으로 강력합니다. 엔드포인트의 인증을 그에 맞게 취급하세요.

파일

• server.py — MCP 서버 + 도구(streamable-HTTP + bearer 인증)

• dsm_client.py — Synology Web API 클라이언트(검색, 로그인, 세션 갱신)

• config.py — 환경 변수에서 클라이언트 구성

• Dockerfile / docker-compose.yml — 컨테이너 + 선택적 터널

• config.example.env — .env로 복사