quickfile-mcp

Quickfile REST API v2용 MCP 서버입니다. 다중 계정, 비밀 정보 격리.

기능

• 45개 도구 -- API operationId당 하나씩, 내장된 spec.json에서 생성됩니다.

• 다중 계정 -- 여러 Quickfile 계정을 구성합니다. 각 도구는 account 매개변수를 받습니다.

• 두 가지 인증 모드 -- 정적 개인 Bearer 토큰 및 OAuth 2.0(자동 갱신 + 회전 refresh-token 저장)을 지원합니다.

• 비밀 정보 격리 -- 토큰은 accounts.json에 저장되며(git에서 무시됨), AI 에이전트에 노출되지 않습니다. 도구 스키마는 account 선택자와 엔드포인트 매개변수만 노출합니다.

Related MCP server: iikoServer MCP Server

설정

1. npm install

2. cp accounts.example.json accounts.json을 실행한 후 계정 자격 증명을 입력합니다.

3. npm run build

4. MCP 클라이언트(Claude Desktop 등)를 구성합니다:

{
  "mcpServers": {
    "quickfile": {
      "command": "node",
      "args": ["path/to/quickfile-mcp/dist/index.js"],
      "cwd": "path/to/quickfile-mcp"
    }
  }
}

서버는 작업 디렉터리에서 accounts.json을 읽습니다(사용자 지정 경로는 QF_ACCOUNTS_FILE 환경 변수를 사용). OAuth 토큰 정보(accessToken, refreshToken, expiresAt)는 서버가 관리하는 별도의 내부 tokens.json(또는 QF_TOKENS_FILE)에 저장됩니다 — 직접 편집할 필요가 없습니다.

인증

정적 토큰(본인 계정)

QuickFile에서 개인 Bearer 토큰을 생성합니다: Account Settings -> Third Party Integration -> API. accounts.json에서 "type": "static" 및 "token": "<your token>"을 설정합니다.

OAuth(파트너 앱)

1. clientId / clientSecret을 얻으려면 QuickFile에 앱을 등록합니다. 이 값들을 "type": "oauth"로 accounts.json에 입력합니다.

2. 첫 accessToken, refreshToken, expiresAt을 얻으려면 OAuth 인증 + 토큰 교환 흐름을 대역 외(out-of-band)로 완료합니다(간단한 CLI 또는 수동 붙여넣기).

3. tokens.json을 한 번 시드합니다:

   { "beta": { "accessToken": "...", "refreshToken": "...", "expiresAt": 0 } }

   이후에는 tokens.json을 직접 건드릴 필요가 없습니다 — 서버가 만료되는 액세스 토큰을 자동으로 갱신하고, 회전된 refresh token을 다시 그 파일에 저장합니다.

계정 선택

모든 도구는 선택적 account 매개변수(구성된 레이블의 enum)를 받습니다. 생략하면 accounts.json의 defaultAccount를 사용합니다.

API 참조

전체 엔드포인트 스키마: src/spec.json(Swagger 2.0, 45개 경로). 출처: Quickfile API 문서.