Lark MCP 服务器

Lark MCP Server

Lark (飛書) MCP Server - 讓 Claude 直接操作 Lark 文件、Wiki、待辦事項。

最近更新 (v3.34.0 ~ v3.35.0)

v3.35.0 — 程式碼品質重構與 Bug 修復

重構內部實作、移除 dead code、修正 todo_create 時間戳 bug。

• Bug 修復：todo_create 的 due_time 時間戳從毫秒改為秒（Lark API 要求秒級 Unix timestamp）
• 重構：抽出 getAppAccessToken() 消除重複的 app token 取得邏輯
• 重構：抽出 deleteBlockRange() 統一 5 處 inline batch_delete 呼叫
• 簡化：getDocumentRootBlockId 直接回傳 document ID（root block ID 等於 document ID）
• 清理：移除未使用的 PaginationSchema、withRetry、dead wiki fallback 程式碼
• 清理：移除不必要的 export（RetryOptions、getErrorInfo）
• 改善：tasklist_tasks limit 預設改為 10（每個任務需額外 API 呼叫）
• 改善：drive_list 遞迴搜尋新增 maxApiCalls 限制防止過量 API 呼叫

v3.34.0 — 容器 block _children 支援

寫入工具新增 _children 欄位，支援 Callout、Quote 等容器 block 自動建立父 block 並遞迴插入子 block。

基本資訊

安裝

bun install

Claude Code 設定

在 ~/.claude/settings.json 中加入：

{
  "mcpServers": {
    "lark": {
      "command": "bun",
      "args": ["run", "/path/to/lark-mcp-server/src/index.ts"],
      "env": {
        "LARK_APP_ID": "your_app_id",
        "LARK_APP_SECRET": "your_app_secret",
        "LARK_CALLBACK_PORT": "9876"
      }
    }
  }
}

授權

使用任何工具時，若 Token 不存在或已過期，會自動開啟瀏覽器並啟動 OAuth callback server。只需在瀏覽器點「同意」即可完成授權。

Callback port 由環境變數 LARK_CALLBACK_PORT 設定（必填），固定使用該 port。若被佔用會自動殺掉佔用的 process 後重新綁定。

也可手動執行 lark_auth_url 觸發授權流程。lark_auth 保留作為手動備用。

工具列表

認證工具

Wiki 工具

文件工具

待辦事項工具

任務清單工具

子任務工具

注意：子任務的完成和刪除請使用 task_complete 和 task_delete。

任務分組工具

注意：Lark API 限制，只有 Tasklist 中的分組支援透過 tasklist_add_task 加入任務。「我負責的」中的分組只能透過 UI 操作移動任務。

通用參數

所有列表/搜尋工具皆支援以下可選參數：

讀取工具說明：wiki_read 和 doc_read 回傳原始 blocks。需要顯示給用戶時，使用 blocks_to_markdown 轉換。

MCP String Coercion：所有非 string 參數（number / boolean / array）皆支援自動從 string 轉型。MCP protocol 傳參時所有值可能為 string，Schema 會自動處理："3" → 3、"true" → true、"[{...}]" → [{...}]。呼叫端無需手動轉型。

工具參數詳細說明

認證工具

lark_auth

user_me

無參數。回傳當前用戶的 open_id、user_id、name、email、mobile。

user_get

user_list

Wiki 工具

wiki_list_nodes

wiki_read

wiki_update

wiki_prepend / wiki_append

wiki_insert_blocks

wiki_delete_blocks

wiki_create_node

wiki_move_node

功能說明：支援同空間或跨空間移動，子節點會一併移動。需要 wiki:node:move 權限。

文件工具

doc_create

doc_read

doc_prepend

doc_append

doc_update

doc_delete

doc_move

doc_insert_blocks

doc_delete_blocks

doc_move_blocks

doc_search_blocks

doc_indent_block

注意：此為破壞性操作（delete + re-insert），含子節點的 block 會整棵子樹一併搬移。

doc_batch_update_blocks

典型流程：doc_read → 找到 table block → 取得 cell children 的 text block_id → doc_batch_update_blocks 一次更新多個 cell。

drive_list

drive_recent

無必填參數。

blocks_to_markdown

lark_search

使用 /suite/docs-api/search/object API，支援搜尋所有可存取文件（包括我的文件資料庫、共享空間）。

待辦事項工具

todo_list

todo_create

todo_search

task_complete / task_delete

todo_update

todo_add_members / todo_remove_members

任務清單工具

tasklist_create

tasklist_update

tasklist_get / tasklist_delete / tasklist_tasks

tasklist_add_task

提示：若任務已在該清單中，再次呼叫並指定不同的 section_guid 可直接將任務移至新分組，無需先移除。

tasklist_remove_task

子任務工具

subtask_create

subtask_list

subtask_update

任務分組工具

section_list

section_tasks

section_create

section_delete

Lark Block JSON 格式

寫入工具（doc_create, doc_prepend, doc_append, doc_update, doc_insert_blocks, wiki_prepend, wiki_append, wiki_update, wiki_insert_blocks）接受 Lark Block JSON 陣列。

常用 Block 結構

文字段落：

{ "block_type": 2, "text": { "elements": [{ "text_run": { "content": "Hello" } }] } }

標題（H1-H9）：

{ "block_type": 3, "heading1": { "elements": [{ "text_run": { "content": "Title" } }] } }

無序列表：

{ "block_type": 12, "bullet": { "elements": [{ "text_run": { "content": "Item" } }] } }

有序列表：

{ "block_type": 13, "ordered": { "elements": [{ "text_run": { "content": "Item" } }] } }

待辦事項：

{ "block_type": 17, "todo": { "elements": [{ "text_run": { "content": "Task" } }], "style": { "done": false } } }

程式碼區塊：

{ "block_type": 14, "code": { "elements": [{ "text_run": { "content": "code" } }], "language": 40 } }

引用：

{ "block_type": 15, "quote": { "elements": [{ "text_run": { "content": "quote" } }] } }

分隔線：

{ "block_type": 22, "divider": {} }

Block Type 對照表

Text Element 結構（支援樣式）

{
  "text_run": {
    "content": "文字內容",
    "text_element_style": {
      "bold": true,
      "italic": false,
      "strikethrough": false,
      "inline_code": false
    }
  }
}

讀取與顯示

doc_read 和 wiki_read 回傳原始 blocks。使用 blocks_to_markdown 可將 blocks 轉換為 Markdown 格式顯示給用戶。

表格支援

讀取：支援兩種表格類型：

所需權限 (Scopes)

在 Lark 開發者後台設定以下權限：

• wiki:wiki - Wiki 讀寫
• wiki:node:move - 移動 Wiki 節點
• docx:document - 新版文檔讀寫（doc_append / doc_update 等寫入操作必需）
• drive:drive - 雲端硬碟（含文件操作、搜尋）
• bitable:app - 多維表格讀取（嵌入的 Sheet 表格）
• task:task:read - 讀取待辦事項
• task:task:write - 寫入待辦事項
• task:tasklist:read - 讀取任務清單
• task:tasklist:write - 寫入任務清單
• task:section:write - 任務分組（取得「我負責的」任務）
• contact:contact.base:readonly - 列出部門成員
• contact:user.base:readonly - 讀取用戶基本資訊
• contact:user.email:readonly - 讀取用戶 email
• offline_access - 離線存取（Refresh Token）

專案結構

src/
├── index.ts              # MCP Server 入口
├── constants.ts          # 常數與設定
├── types.ts              # TypeScript 型別定義
├── schemas/              # Zod 驗證 Schema
│   ├── common.ts
│   ├── auth.ts
│   ├── wiki.ts
│   ├── doc.ts
│   └── todo.ts
├── services/
│   └── lark-client.ts    # Lark API 客戶端
├── tools/
│   ├── auth.ts           # 認證工具
│   ├── wiki.ts           # Wiki 工具
│   ├── doc.ts            # 文件工具
│   └── todo.ts           # 待辦事項工具
└── utils/
    ├── errors.ts         # 錯誤處理與錯誤碼定義
    ├── rate-limiter.ts   # API 請求頻率限制
    ├── retry.ts          # 重試機制（指數退避）
    ├── markdown.ts       # Markdown 與 Lark Block 轉換
    ├── oauth-callback.ts # OAuth Callback Server（自動授權）
    └── response.ts       # 回應格式化工具

API 穩定性機制

Rate Limiting

自動限制 API 請求頻率，防止觸發 Lark API 限流（錯誤碼 99991400）：

自動重試

遇到可恢復錯誤時自動重試（指數退避）：

可重試的錯誤：

• 99991400 - Rate Limit
• 99991663 / 99991665 - Token 失效（自動刷新）
• 1770010 - 並發編輯衝突

結構化錯誤訊息

錯誤回應包含詳細資訊與建議：

Error: API request failed

**Error Code**: 99991668
**Description**: Resource access denied
**Message**: no permission to access resource
**Endpoint**: /wiki/v2/spaces/xxx
**Suggestion**: Ensure you have permission to access this resource.

更新日誌

v3.35.0

程式碼品質重構與 Bug 修復 — 重構內部實作、修正 bug、移除 dead code。

• todo.ts：due_time 時間戳修正 getTime() → Math.floor(getTime() / 1000)（毫秒→秒）
• lark-client.ts：抽出 getAppAccessToken() 共用函數，消除 exchangeCodeForToken / refreshAccessToken 重複邏輯
• lark-client.ts：抽出 deleteBlockRange() 共用函數，統一 doc.ts / wiki.ts 共 8 處 inline 呼叫
• lark-client.ts：getDocumentRootBlockId 簡化為直接回傳 document ID
• lark-client.ts：移除 fetchUserTenantDomain 中無作用的 Wiki 空間 fallback 程式碼
• lark-client.ts：移除 existsSync import，改用 try/catch 處理
• schemas/common.ts：移除未使用的 PaginationSchema / PaginationInput
• schemas/todo.ts：tasklist_tasks limit 預設 20 → 10，最大 50
• tools/wiki.ts：drive_list 遞迴搜尋新增 maxApiCalls（50）限制
• utils/retry.ts：移除未使用的 withRetry 函數及 RetryOptions 的 export
• utils/errors.ts：移除 getErrorInfo 的 export

v3.34.0

容器 block _children 支援 — 寫入工具新增 _children 欄位，支援 Callout、Quote 等容器 block 自動建立父 block 並遞迴插入子 block。

• lark-client.ts：insertBlocks 新增 _children 分支，遇到時先 flush、建立父 block、再遞迴插入子 block
• tools/doc.ts：doc_create、doc_update、doc_insert_blocks 的 description 補充 _children 用法
• tools/doc.ts：hasTable → hasNestedBlocks，語意更準確

v3.33.0

tasklist_tasks 新增 completed 過濾 — 新增 completed (boolean, optional) 參數，可依完成狀態過濾清單中的任務。

• schemas/todo.ts：TasklistTasksSchema 加入 completed: coerceBoolean.optional()
• tools/todo.ts：handler 將 completed 傳入 API request params

v3.32.0

新增 doc_indent_block 工具 — 支援文件區塊縮排/取消縮排，透過 delete + re-insert 遞迴搬移整棵 block tree。

• lark-client.ts：新增 insertSingleBlock() helper（回傳新 block ID）
• schemas/doc.ts：新增 DocIndentBlockSchema
• tools/doc.ts：新增 doc_indent_block tool

v3.31.0

RateLimiter 改為 queue-based — 修復 tasklist_tasks 大量任務時約 30% 回傳 (failed to fetch) 的問題。

• rate-limiter.ts：RateLimiter 從 timestamp-based 改為 promise-chain-based，並發呼叫自動排隊依序執行
• constants.ts：RATE_LIMIT_INTERVAL_MS 350 → 340ms

v3.30.0

新增 MCP String Coercion Helpers — 解決 Claude Code 透過 MCP protocol 呼叫工具時，所有參數值皆為 string 導致 Zod strict schema 驗證失敗（Expected array, received string 等）的問題。

修改內容：

• common.ts：新增 coerceNumber、coerceBoolean、coerceArray(itemSchema) 三個 preprocess helpers，ListPaginationSchema / SearchPaginationSchema 的 limit、offset 改用 coerceNumber
• doc.ts：blocks → coerceArray()、start_index / end_index / target_index / index → coerceNumber.pipe()、case_sensitive → coerceBoolean
• wiki.ts：blocks → coerceArray()、start_index / end_index / index → coerceNumber.pipe()
• todo.ts：members → coerceArray(z.string())、completed → coerceBoolean、limit（SectionList / SectionTasks）→ coerceNumber.pipe()

使用重點：

• 呼叫端傳入 "3" 或 3 皆可，Schema 自動轉為正確型別
• array 參數可傳 JSON string（如 "[{\"block_type\":2}]"）或原生 array，兩者皆接受
• boolean 參數接受 "true" / "false" string 或原生 true / false
• 轉型失敗時仍會拋出原始 Zod validation error，不會靜默吞錯
• 僅影響 input schema，output schema 不變

License

MIT