Deckflow MCP Server

A Model Context Protocol server for Deckflow atomic file and presentation utilities, available as tools in Claude Desktop, Claude Code, Cursor, and any other MCP client.

Features

• HTML→PPTX pipeline — html_to_pptx, html_to_image, markdown_to_image, build_html_player
• PPTX utilities — split, merge, font embedding, font/text inspection
• General file utilities — format conversion, OCR, image resize/WebP, file/video compression
• Fallback task support — query status with blocking wait + progress notifications, refresh result download URLs

14 tools total: 12 atomic capability tools plus get_task and download_task_result. Long-running generation, revamp, and translation workflows are intentionally not exposed as MCP tools; they belong in agent-side skills or scripts. See docs/usage.zh-CN.md for the Chinese usage guide.

Requirements

• Node.js >= 20
• A Deckflow API key (a space ID is optional — when omitted, the server auto-selects your first activated space via GET /my/spaces)

Installation

npm install
npm run build   # outputs dist/entry/stdio.js and dist/entry/http.js

Usage

stdio mode (local, recommended)

Claude Desktop / Cursor configuration:

{
  "mcpServers": {
    "deckflow": {
      "command": "node",
      "args": ["/absolute/path/to/deckflow-mcp/dist/entry/stdio.js"],
      "env": {
        "DECKFLOW_API_KEY": "<your API key>"
      }
    }
  }
}

Claude Code:

claude mcp add deckflow \
  -e DECKFLOW_API_KEY=<your API key> \
  -- node /absolute/path/to/deckflow-mcp/dist/entry/stdio.js

Add DECKFLOW_SPACE_ID=<your space ID> to pin a specific space; otherwise the first activated space of the account is used.

In stdio mode, file parameters accept two forms: a local absolute path or an http(s) URL.

Optional toolset selection:

DECKFLOW_TOOLSET=html2pptx          # only HTML/PPTX pipeline + support tools
DECKFLOW_TOOLSET=html2pptx,pptx     # combine capability domains
# unset = all 12 atomic tools + 2 support tools

Streamable HTTP mode (hosted)

Production endpoints:

Endpoint	Toolset
https://mcp.deckflow.com/v1/html2pptx	HTML→PPTX pipeline
https://mcp.deckflow.com/v1/pptx	PPTX utilities
https://mcp.deckflow.com/v1/tools	General file utilities
https://mcp.deckflow.com/mcp	Compatibility endpoint with all curated atomic tools

All endpoints support four ways to authenticate:

1. OAuth (recommended — works with Claude Code, Manus, and any MCP client supporting remote-server authorization). Add the URL with no credentials; the client discovers the OAuth metadata and opens the Deckflow app authorization page:

claude mcp add --transport http deckflow-html https://mcp.deckflow.com/v1/html2pptx
# then inside Claude Code run /mcp and follow the browser authorization

In Manus: Connect Your Tools → add one of the MCP endpoint URLs → complete the Deckflow authorization page. The server implements the full MCP authorization spec (protected-resource metadata, dynamic client registration, PKCE); the Deckflow app returns a user_... token to the MCP callback, and the MCP server seals it into its own encrypted access token. Upstream Deckflow API calls made through this OAuth flow use X-Auth-Token.

2. Direct Bearer header: Authorization: Bearer <API key> (plus optional X-Space-Id).

3. Direct Deckflow user token: X-Auth-Token: <user_... token> (plus optional X-Space-Id).

4. URL query (for clients without custom headers or OAuth): https://mcp.deckflow.com/v1/html2pptx?API_KEY=<key>.

Self-hosting:

DECKFLOW_HTTP_PORT=3900 DECKFLOW_OAUTH_SECRET=<random hex> node dist/entry/http.js

Additional env vars for hosting: DECKFLOW_PUBLIC_ORIGIN (public origin used in OAuth metadata), DECKFLOW_PUBLIC_MCP_PATH (public compatibility path for /mcp, e.g. /mcp/v1 during migration), DECKFLOW_OAUTH_SECRET (token-sealing key — must stay fixed or issued tokens are invalidated on restart), DECKFLOW_CLI_AUTH_URL (optional override for the frontend auth URL; defaults to https://app.deckflow.com/cli/auth).

• Endpoints: POST /v1/html2pptx, POST /v1/pptx, POST /v1/tools, and compatibility POST /mcp (stateless); health check: GET /healthz
• Credentials per request: Authorization: Bearer <API key>, X-Auth-Token: <user_... token>, or ?API_KEY= query; missing HTTP credentials fall back to environment variables. X-Space-Id: <space ID> (or ?spaceId=) is optional — when omitted, the space is auto-resolved via GET /my/spaces on each request (stateless), so pass it explicitly to save a round trip
• Local file paths are rejected in this mode — use http(s) URLs instead

Environment variables

Variable	Required	Description
DECKFLOW_API_KEY	stdio: yes	Deckflow API key (HTTP mode: may come from request headers)
DECKFLOW_SPACE_ID	no	Space ID; when omitted, auto-selects the first space with memberStatus=activated from GET /my/spaces
DECKFLOW_API_BASE	no	Defaults to https://pw.shuibo.com/v1
DECKFLOW_HTTP_PORT	no	HTTP mode port, defaults to 3900
DECKFLOW_DOWNLOAD_MAX_BYTES	no	Max size for URL file inputs, defaults to 200 MB
DECKFLOW_DOWNLOAD_TIMEOUT_MS	no	Timeout for URL file downloads, defaults to 120 s

Tools

Atomic tools

All creation tools accept an optional waitSeconds parameter. Atomic utility tools wait up to 120 s by default and return the result/download URL directly. If a task times out, use get_task, then fetch or refresh artifacts with download_task_result.

Tool	Description
convert_file	.ppt/.pptx→image/pdf/pptx/video; .pdf→image; .key→image/html/pdf; .doc/.docx→pdf
html_to_pptx	HTML → editable PPTX
html_to_image	HTML → png screenshot
markdown_to_image	Markdown → png image
build_html_player	Bundle multi-page HTML into a swipeable player
split_pptx / merge_pptx / embed_pptx_fonts / inspect_pptx	PPTX split / merge / font embedding / font & text extraction
ocr_image / transform_image / compress_file	Image OCR / resize & WebP conversion / file & video compression

Support tools

Tool	Description
get_task	Task status snapshot; wait: true blocks until terminal state, streaming MCP progress notifications
download_task_result	Signed download URL for a completed task; savePath saves locally (stdio mode)

Client timeouts: MCP clients default to a ~60 s request timeout. For long waits (get_task with wait: true), raise the client-side timeout and enable resetTimeoutOnProgress — this server emits progress notifications while waiting precisely to keep such requests alive. See scripts/smoke.ts for an example.

Development

npm test                  # unit tests (mocked, no network)
npm run typecheck
npm run build

# Integration tests against the real API (creates real tasks):
DECKFLOW_API_KEY=... DECKFLOW_SPACE_ID=... npm run test:integration

# Smoke tests over stdio against the built output:
DECKFLOW_API_KEY=... DECKFLOW_SPACE_ID=... npm run smoke              # connectivity
DECKFLOW_API_KEY=... DECKFLOW_SPACE_ID=... npm run smoke -- html-to-pptx  # HTML to PPTX flow

Debug interactively with the official MCP Inspector:

npx @modelcontextprotocol/inspector \
  -e DECKFLOW_API_KEY=<your API key> -e DECKFLOW_SPACE_ID=<your space ID> \
  -- node dist/entry/stdio.js

Error handling

Upstream API errors ({ code, message, data }) are mapped to readable English tool errors with actionable hints (invalid key, insufficient credits, upstream validation details, etc.). Idempotent requests retry on network errors and 5xx; task creation never auto-retries to avoid double billing.