MCP 伺服器

Deckbase MCP

Deckbase 的 Model Context Protocol 伺服器。AI 工具（Cursor、Claude Code、VS Code 等）可以讀取文件，並管理牌組與卡片。

端點

模式	端點	驗證
託管（HTTP）	POST /api/mcp	`Authorization: Bearer`：儀表板 API 金鑰或 OAuth 存取權杖。生產環境使用相同路徑：`/api/mcp`。

OAuth（瀏覽器登入）是最快的連線方式，請參閱連線到 Deckbase MCP。腳本與 CI 也可使用儀表板 API 金鑰。MCP 提供給 Basic、Pro 與 VIP 訂閱者使用。完整參考請透過 read_doc 閱讀 docs/public/MCP.md。

工具

文件

工具	說明	參數
list_docs	列出 `docs/public/` 中的 Markdown 檔案。	無。
read_doc	依路徑讀取文件。僅提供 `docs/public/` 中的文件。	`path`，例如 `MCP.md` 或 `deckbase://docs/public/MCP.md`。
list_template_block_types	區塊類型鍵與數字 ID（text、media、interactive、layout）。請在 `create_template` 之前使用。靜態資料。	無。
list_block_schemas	各區塊類型的 JSON 結構：`blocksSnapshot`、`values`、`configJson`。可搭配 `export_deck` 取得實際範例。	無。
list_elevenlabs_voices	供 `generate_audio_for_card` 的 `voice_id` 使用的 ElevenLabs 語音 ID 與標籤。Deckbase 精選目錄，不會讀取使用者的 Firestore。	選填 `language`、`gender`、`search`。
list_ai_image_models	可供 `generate_image_for_card` 使用的 AI 圖片模型 ID，附標籤與點數成本。	無。

牌組與卡片：需要驗證

工具	說明	參數
list_decks	使用者的牌組（`deckId`、標題、說明、選填的 `defaultTemplateId`、選填的 `iconEmoji`）。	無。
create_deck	建立牌組。傳回 `deckId`，以及設定時的 `icon_emoji` / `iconEmoji`。	`title`（必填）、`description`（選填）、選填的 `icon_emoji` 或 `iconEmoji`（單一 emoji；除非使用者選擇不要，否則 AI 用戶端應挑選符合標題的 emoji）。
update_deck	更新標題、說明、預設範本或牌組圖示。	`deckId`（必填）；選填 title、description、`default_template_id`、`icon_emoji` 或 `iconEmoji`（空字串會清除圖示）。
list_templates	範本（`templateId`、名稱、說明）。	無。
get_template_schema	版面的確切 JSON：`blockId`、類型、`side`（`"front"` \| `"back"`）、`configJson`、`valuesExample`、`create_card` 提示。	`templateId`，或牌組預設範本的 `deckId`。
create_card	從範本建立新卡片。傳回 `cardId`、`templateId`、`usedDeckDefault`。`front` 會填入主區塊；`block_text` 的鍵包含背面區塊（`side` 取自 `get_template_schema`）。	`deckId` 必填。選填 `templateId`、`front`、`block_text`、`generate_audio`、`voice_id`、`audio_language`、`audio_gender`。
create_cards	批次建立。每次請求最多 50 張。失敗時會傳回 `created` + `failedAt`。	`deckId`、`cards` 陣列（必填）。選填頂層的 `templateId`、`voice_id`、`generate_audio`。
update_card	編輯卡片內容。	`deckId`、`cardId`；選填 `values` / `blocks_snapshot`，或合併 `front` / `block_text`。
delete_card	將單一卡片軟刪除（移至垃圾桶）。除非 `user_confirmed` 為 true，否則伺服器會拒絕：請僅在取得使用者明確同意後使用。	`deckId`、`cardId`、`user_confirmed`（必填布林值）。
delete_cards	在單一牌組中批次軟刪除。同意規則與 `delete_card` 相同。每次請求最多 50 張。	`deckId`、`card_ids`（非空陣列）、`user_confirmed`。
generate_audio_for_card	為現有卡片產生 ElevenLabs TTS。	`deckId`、`cardId`。傳入 `voice_id`，或 `audio_language` + `audio_gender`。選填 `text`、`block_id`、`replace_existing`。
export_deck	牌組與卡片的 JSON。包含 `truncated`、`exportType`。完整匯出會包含每張卡片的 `blocksSnapshot`，其中有 `side` + `values`。	`deckId`（必填）；選填 `max_cards`（預設 2000，上限 5000）、`export_type`：`full` 或 `values_only`。
create_template	建立新範本（區塊版面）。傳回 `templateId` 與區塊 ID。若省略 `block_types`，預設為問答。	`name`（必填）；選填 description、`block_types` / `blocks`（各區塊的 `side`）、`voice_id`、`audio_language`、`audio_gender`、`mainBlockId` / `subBlockId`。
update_template	更新中繼資料和/或版面。會提升 `version`。	`templateId`（必填）；選填 name、description、`block_types` / `blocks`、`voice_id`、`audio_language` + `audio_gender`、`mainBlockId` / `subBlockId`。

會讀取你資料的工具都需要有效的 OAuth 權杖或 API 金鑰。list_template_block_types 與 list_block_schemas 傳回靜態資料（無需驗證）。list_elevenlabs_voices 不會讀取 Firestore。未驗證的請求會傳回 401。

資源

伺服器會為 docs/public/ 中的文件提供 MCP 資源：

resources/list

docs/public/ 中每個 .md 檔案各對應一個資源（例如 deckbase://docs/public/MCP.md）。

resources/read

依該 URI 取得文件內容。

範例：牌組、範本與卡片

1
在用戶端設定 MCP URL 與 Bearer 權杖：Authorization: Bearer YOUR_API_KEY（或從「連線」頁面取得的 OAuth 存取權杖）。
2
呼叫 list_templates。若結果為空，請先使用 list_template_block_types 與 create_template。
3
以選定的 templateId 呼叫 get_template_schema，了解確切的 blockId 鍵與 side 值。
4
呼叫 create_deck，並提供 title、選填的 description，以及在代理應為主題挑選相符圖示時提供 icon_emoji。
5
呼叫 create_card，提供 deckId，並視需要提供 templateId、front（主區塊），以及其他區塊（包含背面）的 block_text。

技術細節

協定MCP 2024-11-05

伺服器名稱deckbase-mcp

託管方式透過 POST 傳輸的 JSON-RPC 2.0。請使用 OAuth 存取權杖或儀表板 API 金鑰（Bearer），不要使用 Firebase ID 權杖。

卡片結構create_card 會複製範本的區塊版面。每個區塊都包含來自範本的 side，值預設為空。資料儲存在 Firestore，並同步到儀表板與行動應用程式。

如需用戶端設定（Cursor、VS Code、Claude 等），請參閱連線到 Deckbase MCP • 其他連結請參閱資源