idrive-mcp-server

iDrive의 웹 백업/복원 콘솔을 MCP 호환 AI 어시스턴트(예: Claude Desktop 또는 Claude Code)의 도구로 노출하는 MCP(Model Context Protocol) 서버입니다. iDrive는 이 콘솔에 대한 공개 API나 OAuth 흐름을 제공하지 않으므로, 로그인된 브라우저에서 복사한 세션 쿠키를 사용하여 iDrive의 문서화되지 않은 내부 웹 API(콘솔 자체가 호출하는 것과 동일한 엔드포인트)와 통신합니다. 이 서버가 기반으로 하는 역공학 엔드포인트 참조는 docs/api-map.md를 참조하세요.

IDRIVE_COOKIE 얻기

1. 브라우저에서 idrive.com에 로그인합니다.

2. DevTools -> Network 탭을 엽니다.

3. www.idrive.com에 대한 XHR 요청을 클릭합니다.

4. 해당 요청의 Cookie 헤더 전체 값을 복사합니다.

5. .env 파일(.env.example 복사)에 IDRIVE_COOKIE=<값>으로 넣습니다.

이 쿠키에는 약 24시간 후 만료되는 세션 토큰(SES_TOKEN, JWT)이 포함되어 있습니다. 만료되면 도구 호출이 "세션을 새로 고치세요"라는 명확한 오류와 함께 실패하므로 위 단계를 반복해야 합니다.

Related MCP server: Google Drive MCP Server

Claude Code / Claude Desktop에서 구성

MCP 구성(.mcp.json for Claude Code, 또는 claude_desktop_config.json for Claude Desktop)에 항목을 추가합니다:

{
  "mcpServers": {
    "idrive": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/absolute/path/to/idrive-mcp-server",
      "env": {
        "IDRIVE_COOKIE": "<your cookie value>"
      }
    }
  }
}

또는 npm run build 실행 후, command/args를 빌드된 출력으로 지정합니다:

{
  "mcpServers": {
    "idrive": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/idrive-mcp-server",
      "env": {
        "IDRIVE_COOKIE": "<your cookie value>"
      }
    }
  }
}

사용 가능한 도구

• list_devices — 입력 없음. 인증된 iDrive 계정에서 백업된 모든 장치를 나열합니다(장치 ID, OS, 별명, IP 주소, 백업 버킷 위치). EVS 호스팅 evs/listDevices 엔드포인트를 통해 호출됩니다. IDRIVE_COOKIE 외에 추가 구성이 필요 없습니다.

• list_files — deviceId(필수), path(기본값 "/"), osType(기본값 "win"). iDrive의 getRestoreData 엔드포인트를 통해 장치의 백업된 파일 트리를 탐색합니다.

• browse_folder — deviceId(필수), path(필수, EVS 형식: "/C", "/C/Users/..."). 더 풍부한 EVS 호스팅 evs/browseFolder 엔드포인트(휴지통/체크섬/라이브 이미지 필드가 list_files보다 추가됨)를 통해 장치의 백업된 폴더를 탐색합니다. evs/browseFolder는 루트 경로를 처리하는 것이 관찰된 적이 없으므로, 먼저 list_files를 사용하여 장치의 사용 가능한 드라이브 문자/루트를 발견하세요.

• get_thumbnail — deviceId(필수), path(필수, browse_folder와 동일한 EVS 형식), timestamp(필수 — 이전 list_files/browse_folder 호출의 파일 lmd_web 값). EVS 호스팅 evs/getThumbnail 엔드포인트를 통해 백업된 파일의 썸네일 미리보기 이미지를 가져오며, MCP 이미지 콘텐츠로 반환됩니다.

• download_file — deviceId(필수), path(필수, browse_folder와 동일한 EVS 형식). EVS 호스팅 evs/downloadFile 엔드포인트를 통해 백업된 파일의 실제 콘텐츠를 다운로드하며, base64로 인코딩된 MCP 리소스 콘텐츠로 반환됩니다. 이 엔드포인트의 iDrive Content-Type은 실제 파일 유형을 식별하는 데 신뢰할 수 없으므로 파일 이름/확장자에서 유추하세요.

• get_file_properties — deviceId(필수), path(필수, browse_folder와 동일한 EVS 형식). EVS 호스팅 evs/getProperties 엔드포인트를 통해 단일 백업 파일 또는 폴더의 크기/수정 시간 메타데이터를 가져옵니다.

• get_file_versions — deviceId(필수), path(필수, browse_folder와 동일한 EVS 형식). EVS 호스팅 evs/getVersions 엔드포인트를 통해 파일의 이전 백업 버전을 나열합니다. 현재까지 "버전 기록 없음" 응답 형태만 확인되었습니다 — 이전 버전이 없는 파일은 도구 오류가 아닌 정상 결과(hasVersions: false)로 보고됩니다. 실제 버전 목록의 형태는 확인되지 않았으며 원시 JSON으로 반환됩니다.

• get_account_usage — 입력 없음. 계정의 사용/총 Sync 저장 용량을 원시 문자열(예: "0.00 KB", "5000.00 GB")로 반환합니다. iDrive의 account.html 페이지에 있는 두 개의 인라인 <script> 변수에서 스크래핑합니다 — 전용 JSON 사용량 엔드포인트는 없습니다. 본질적으로 취약하며(안정적인 API가 아닌 HTML 스크래핑) 페이지 자체의 "Sync" 용량 명명을 구체적으로 반영합니다. 장치 백업 전체의 총 사용량을 나타내는지 여부는 확인되지 않았습니다.

변경 도구

아래 도구는 위의 모든 도구(모두 읽기 전용)와 달리 계정의 실제 백업된 데이터를 변경합니다. 해당 설명과 MCP annotations에 명시적으로 명시되어 있습니다(readOnlyHint: false, delete_file의 경우 destructiveHint: true).

• create_folder — deviceId(필수), parentPath(필수, EVS 형식, 기존 폴더여야 함), folderName(필수 — 경로가 아닌 새 폴더 이름만). EVS 호스팅 evs/createFolder 엔드포인트를 통해 장치의 라이브 백업 내에 새 폴더를 만듭니다. 라이브 확인됨: 새 폴더는 이후 browse_folder/list_files 목록에 나타납니다.

• delete_file — deviceId(필수), paths(필수, 하나 이상의 EVS 형식 경로 배열 — 단일 배치 호출에서 반복된 p 필드로 전송됨), permanent(선택 사항, 기본값 false). EVS 호스팅 evs/v1/deleteFile 엔드포인트를 통해 장치의 라이브 백업에서 파일/폴더를 제거합니다. permanent: false(기본값)는 경로를 휴지통으로 이동합니다 — 라이브 확인됨, restore_from_trash로 복구 가능. permanent: true는 trash=no를 보내며, 필드 이름/패턴에서 영구적이고 복구 불가능한 삭제를 의미하는 것으로 추정되지만 이것은 독립적으로 라이브 확인된 적이 없습니다 — 의존하기 전에 검증되지 않은 것으로 취급하세요.

• restore_from_trash — deviceId(필수), paths(필수, 하나 이상의 EVS 형식 경로 배열, delete_file과 동일한 반복 p 배치). EVS 호스팅 evs/putBackFromTrash 엔드포인트를 통해 이전에 휴지통에 넣은 파일/폴더를 원래 위치로 복원합니다. 라이브 확인됨. 현재 휴지통에 무엇이 있는지 열거하는 확인된 방법이 없으므로 paths는 이미 알고 있어야 합니다.

모든 EVS 호스팅 도구(browse_folder, get_thumbnail, download_file, get_file_properties, get_file_versions, list_devices, create_folder, delete_file, restore_from_trash)는 EVS 위성 호스트가 요구하는 EVSID 세션을 투명하게 부트스트랩하고 캐시합니다(docs/api-map.md의 "EVSID: how the EVS session is actually established" 섹션 참조) — IDRIVE_COOKIE 외에 추가 구성이 필요 없지만, 쿠키의 EVS_SERVER 값(/idrive/home에서 복사한 쿠키에 있음, idriveent 콘솔에서 복사한 쿠키에는 반드시 있는 것은 아님)이 있어야 부트스트랩할 EVS 호스트를 알 수 있습니다.

테스트

npm test는 단위 테스트를 무조건 실행하고, 환경 변수로 게이트되고 설정되지 않으면 깨끗하게 건너뛰는 라이브 통합 테스트 세트도 실행합니다:

• IDRIVE_COOKIE — 통합 테스트가 실행되려면 필수.

• IDRIVE_TEST_DEVICE_ID — 대부분의 통합 테스트가 필요로 하는 실제 device_id(list_devices에서).

• IDRIVE_TEST_EVS_PATH — 대부분의 통합 테스트가 탐색/읽기하는 실제 EVS 형식 경로(예: /C).

• IDRIVE_TEST_ALLOW_MUTATIONS=1 — 위 세 변수 외에 src/tools/files.test.ts의 create_folder/delete_file/restore_from_trash 통합 테스트가 실행되기 전에 필요한 별도의 명시적 옵트인. 해당 테스트는 실제 계정을 변경합니다: IDRIVE_TEST_EVS_PATH 아래에 고유한 이름의 임시 폴더를 만들고(반복 실행 시 충돌 없음), 세 도구를 모두 실행한 후 테스트가 끝나기 전에 휴지통으로 이동하여 정리합니다(어설션이 중간에 실패해도 try/finally로 정리). 이 변수가 정확히 "1"로 설정되지 않으면 해당 테스트는 건너뛰므로, 읽기 전용 테스트를 위해 IDRIVE_COOKIE/IDRIVE_TEST_DEVICE_ID/IDRIVE_TEST_EVS_PATH만 설정한 개발자는 실제 데이터를 건드릴 위험 없이 npm test를 실행할 수 있습니다.

get_account_usage의 통합 테스트는 읽기 전용이며 다른 계정 도구와 마찬가지로 IDRIVE_COOKIE만 필요합니다.

상태

구성 로딩, 세션 만료 감지, 공유 HTTP 클라이언트(src/client/idriveClient.ts)가 준비되어 있습니다. MCP 도구는 src/tools/ 아래에 점진적으로 추가되고 있습니다(위의 "사용 가능한 도구" 참조).