dropbox-mcp

LLM 에이전트에게 Dropbox 계정(개인용 또는 Business/Team)에 대한 읽기/쓰기 액세스를 Dropbox API v2를 통해 제공하는 Model Context Protocol 서버입니다.

문제

Dropbox의 자체 데스크톱 클라이언트는 파일 동기화 문제를 해결합니다. AI 에이전트가 로컬 사본이 없는 계정에 대해 통제된 액세스를 갖는 문제는 해결하지 않습니다. 동기화된 폴더만 볼 수 있는 에이전트는 2TB 규모의 팀 아카이브를 검색할 수 없고, 공유 링크를 만들 수 없으며, 받은 적 없는 파일을 읽을 수도 없습니다.

이 서버는 그 격차를 해소합니다. Dropbox HTTP API에 직접 통신하므로 디스크에 단 한 바이트도 동기화하지 않고 전체 계정을 대상으로 작동하며, 해당 액세스를 원시 HTTP 클라이언트가 아닌 고정된 MCP 도구 세트로 노출합니다. — 에이전트는 fetch가 아니라 dropbox_search를 얻게 됩니다.

Related MCP server: Dropbox MCP Server

아키텍처

네 가지 도구 모듈(files, search, sharing, account)은 stdio로 MCP를 사용하는 단일 McpServer에 등록됩니다. 모든 모듈은 Dropbox API가 까다롭게 만드는 두 가지, 즉 OAuth 토큰 수명 주기와 팀 공간 네임스페이스를 담당하는 하나의 HTTP 클라이언트를 통해 처리됩니다. 모듈은 시작 시 DROPBOX_DISABLED_MODULES로 개별적으로 비활성화할 수 있으므로, 공개 공유 링크를 만들면 안 되는 배포는 해당 모듈을 단순히 등록하지 않습니다. — 이는 단지 권장되지 않는 수준이 아니라 해당 기능이 아예 존재하지 않는 것입니다.

  MCP host (Claude, etc.)
          | stdio (JSON-RPC)
  +-------v--------------------------------------+
  |  index.ts   module registry / stdio transport|
  +-------+--------------------------------------+
          |
  +-------v-------+ +--------+ +---------+ +---------+
  |  tools/files  | | search | | sharing | | account |
  +-------+-------+ +---+----+ +----+----+ +----+----+
          |             |           |           |
          +------+------+-----------+-----------+
                 |
        +--------v-----------------------------------+
        |  client.ts                                 |
        |   - refresh-token -> access-token cache     |
        |   - 401 retry with a forced refresh         |
        |   - Dropbox-API-Path-Root resolution        |
        |   - ASCII-safe Dropbox-API-Arg encoding     |
        +--------+-----------------------------------+
                 |
      RPC api.dropboxapi.com   Content content.dropboxapi.com

두 가지 엔드포인트 계열은 의도적으로 별도의 함수로 유지됩니다. RPC 엔드포인트는 JSON 입력/JSON 출력을 주고받으며, Content 엔드포인트는 인수를 HTTP 헤더에 넣고 본문은 파일 바이트에 사용합니다. 이들을 하나의 일반 request()로 통합하면 인수가 어디로 가는지 조용히 바뀌는 매개변수가 되기 때문에, 분리된 상태를 유지합니다.

진짜 어려운 부분

Dropbox Business 팀에서는 API가 기본적으로 구성원의 홈 네임스페이스를 대상으로 합니다. 실제 공유 작업이 있는 모든 팀 폴더는 대신 팀의 루트 네임스페이스에 있으며, 그대로 보이지 않습니다. 빈 문자열 ""에 대한 list_folder는 구성원의 개인 파일만 반환하고 다른 것은 아무것도 반환하지 않으며, 계정의 대부분이 누락되어 있다는 오류나 힌트도 제공하지 않습니다. 이는 권한 문제처럼 보이지만 권한 문제가 아닙니다.

해결 방법은 팀 루트 네임스페이스를 가리키는 Dropbox-API-Path-Root 헤더를 보내는 것이며, 해당 네임스페이스의 id는 users/get_current_account에서 얻습니다. 이때 재귀 함정이 생깁니다. 일반 RPC 헬퍼가 모든 호출에 path-root 헤더를 붙이기 때문에, 헬퍼를 통해 users/get_current_account를 호출해서 네임스페이스를 해석하면 헤더 해석이 자기 자신을 무한히 호출합니다. 따라서 resolveRootNamespaceId()는 헬퍼를 우회하는, 의도적으로 아무것도 감싸지 않은 fetch를 수행하며, 그 결과는 메모이즈되어 프로세스당 한 번의 추가 왕복만 발생합니다 (src/client.ts).

같은 계열의 더 작은 버그: Content 엔드포인트는 인자를 Dropbox-API-Arg에 넣고, HTTP 헤더는 ASCII입니다. 액센트 문자나 이모지가 이름에 포함된 파일은 API 오류를 반환하는 대신 fetch 내부에서 예외를 발생시킵니다. apiArg()는 헤더가 만들어지기 전에 모든 비-ASCII 코드 포인트를 \uXXXX로 이스케이프합니다.

다르게 했을 점

1. 테스트 없음. 코드는 실제 계정을 대상으로 수동으로 만들고 검증했습니다. 토큰 갱신 경로, 401 재시도, 청크 업로드 경계 조건은 모의된 전송 계층으로 테스트를 했어야 하는 부분입니다. — 이들은 드물면서도 큰 비용으로 실패하는 요소입니다.

2. 경로 루트 캐시가 프로세스당 한 번 생성되고 무효화되지 않습니다. 호스트가 자유롭게 재시작하는 stdio 서버에는 무난하지만, 사용자가 팀 간에 이동할 수 있는 장기 실행 서비스에는 부적절합니다.

3. dropbox_delete는 확인 장치 없이 노출됩니다. Dropbox의 자체 보존 정책 덕분에 복구할 수 있지만, 파괴적인 도구는 호스트의 질문에 기댄 발로 연결됩니다.

4. 오류가 문자열로 형태화되어 있습니다. 메시지와 함께 구조화된 오류 코드를 반환하면 에이전트는 문장을 해석하지 않고도 "rate limited"와 "not found"를 구분하여 분기할 수 있습니다.

설정

Node 20+ (개발은 24에서) 및 Dropbox 계정이 필요합니다.

1. Dropbox 앱 만들기

1. https://www.dropbox.com/developers/apps에서 Create app을 선택하세요.

2. Scoped access 및 Full Dropbox 액세스를 선택합니다.

3. Permissions에서 account_info.read, files.metadata.read, files.metadata.write, files.content.read, files.content.write, sharing.read, sharing.write를 활성화한 다음 Submit을 선택하세요.

4. Settings에서 App key 및 App secret**을 복사합니다.

2. 빌드 빌드 인증

git clone <this-repo>
cd dropbox-mcp
npm install
npm run build

cp .env.example .env      # fill in DROPBOX_APP_KEY and DROPBOX_APP_SECRET
npm run auth              # prints DROPBOX_REFRESH_TOKEN — paste it into .env

npm run auth는 동의 화면 URL을 출력하고, 사용자가 붙여 넣은 코드를 받아 리프트 토큰으로 교환합니다. 이후 서버는 스스로 이 토큰을 단기 액세스 토큰과 계속 교환하게 됩니다.

3. MCP 호스트에 등록

{
  "mcpServers": {
    "dropbox": {
      "command": "node",
      "args": ["/absolute/path/to/dropbox-mcp/dist/index.js"],
      "env": {
        "DROPBOX_APP_KEY": "your-app-key",
        "DROPBOX_APP_SECRET": "your-app-secret",
        "DROPBOX_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

호스트를 재시작하고 "내 Dropbox 저장 공간 사용량은?" 같은 질문을 던져 보세요.

호스트 없이 서버를 실행해 보려면:

npm run inspect           # @modelcontextprotocol/inspector

도구

files — dropbox_list_folder, dropbox_get_metadata, dropbox_create_folder, dropbox_move, dropbox_copy, dropbox_delete, dropbox_get_temporary_link, dropbox_read_file, dropbox_upload (대용량 파일은 업로드 세션을 통해 자동 분할됩니다).

search — dropbox_search — 파일 이름과 내용을 계정 전체 또는 특정 폴더 범위에서 검색합니다.

sharing — dropbox_create_shared_link, dropbox_list_shared_links, dropbox_get_shared_link_metadata, dropbox_revoke_shared_link.

account — dropbox_get_current_account, dropbox_get_space_usage.

설정

모든 설정은 환경 변수입니다. 네임스페이스 제어(DROPBOX_PATH_ROOT), 읽기 크기 상한(DROPBOX_MAX_READ_BYTES), 업로드 청크 크기, 팀 앱 가장용 헤더를 포함한 전체 주석 목록은 .env.example을 참조하세요.

라이선스

MIT — LICENSE를 참고하세요.