quickfile-mcp

MCP server for the Quickfile REST API v2. Multi-account, secret-isolated.

Features

• 45 tools -- one per API operationId, generated from the embedded spec.json.

• Multi-account -- configure multiple Quickfile accounts; each tool takes an account param.

• Both auth modes -- static Personal Bearer Tokens and OAuth 2.0 (auto-refresh + rotating refresh-token persistence).

• Secret isolation -- tokens live in accounts.json (gitignored), never exposed to the AI agent. Tool schemas expose only an account selector + endpoint params.

Setup

Option A: Claude Desktop Extension (.mcpb) — one-click install

1. Build and pack: npm install && npm run build && npm install -g @anthropic-ai/mcpb && mcpb pack mcpb-build

2. Open the resulting mcpb-build.mcpb file with Claude Desktop.

3. Claude prompts for Accounts (JSON) — paste your accounts config:

   {"defaultAccount":"importair","accounts":[{"id":"importair","label":"Import Air","type":"static","token":"YOUR_TOKEN"}]}

   Stored in the OS keychain. Never written to disk, never exposed to the agent.

4. Click Install. Done.

Option B: Manual (dev / non-Claude clients)

1. npm install

2. cp accounts.example.json accounts.json and fill in account credentials.

3. npm run build

4. Configure your MCP client (Claude Desktop, etc.):

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

The server reads accounts from QF_ACCOUNTS_CONFIG env var (JSON string — used by the .mcpb path) if set, otherwise from accounts.json in the working directory (or QF_ACCOUNTS_FILE for a custom path). OAuth token material (accessToken, refreshToken, expiresAt) lives in a separate internal tokens.json (or QF_TOKENS_FILE) that the server manages — you never edit it by hand.

Authentication

Static token (own account)

Generate a Personal Bearer Token in QuickFile: Account Settings -> Third Party Integration -> API. In accounts.json, set "type": "static" and "token": "<your token>".

OAuth (partner app)

1. Register an app in QuickFile to get clientId / clientSecret. Put these in accounts.json with "type": "oauth".

2. Complete the OAuth authorise + token-exchange flow out-of-band (a small CLI or manual paste) to obtain the first accessToken, refreshToken, and expiresAt.

3. Seed tokens.json once:

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

   After this, you never touch tokens.json — the server auto-refreshes expiring access tokens and persists the rotated refresh token back into it.

Account selection

Every tool accepts an optional account parameter (enum of configured labels). Omit to use defaultAccount from accounts.json.

API reference

Full endpoint schemas: src/spec.json (Swagger 2.0, 45 paths). Source: Quickfile API docs.