lark-mcp

Lark MCP

⚠️ 重要提醒

搜尋文件/知識庫必須設定 OAuth：

• docx_builtin_search → 需要 --oauth
• wiki_v1_node_search → 需要 --oauth

否則回傳 99991663 錯誤。設定方式見 installation.md

---

核心規則

# 工具命名（連字號，非底線）
✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__tool_name

# 參數結構
path: {app_token, table_id}   # URL路徑參數
params: {page_size, ...}      # 查詢參數
data: {fields, ...}           # 請求主體
useUAT: false                 # true=使用者身份, false=租戶身份

常見陷阱

# content 必須是 JSON 字串
❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'

# 過濾條件 value 必須是陣列
❌ value: "已完成"
✅ value: ["已完成"]

# 建立群組必須指定 owner_id，否則群主為機器人
owner_id: "ou_xxxxx"

# 參數名差異
docx_builtin_search: search_key  # 不是 query
wiki_v1_node_search: query       # 不是 search_key

# token 類型
wiki_v2_space_getNode: 用 wikcn...  # 不能用 doxcn...
docx_v1_document_rawContent: 用 doxcn...

useUAT 選擇

情境	useUAT
建立資源（想讓使用者可存取）	true
搜尋文件/知識庫	true
存取使用者私有資料	true
查詢公開資料	false

工具速查

類別	工具	文件
訊息	im_v1_message_create, im_v1_message_list	im.md
群組	im_v1_chat_create, im_v1_chat_list, im_v1_chatMembers_get	chat.md
多維表格	bitable_v1_app_create, bitable_v1_appTableRecord_search/create/update	bitable.md
文件	docx_builtin_search, docx_v1_document_rawContent, docx_builtin_import	documents.md
知識庫	wiki_v1_node_search, wiki_v2_space_getNode	wiki.md

ID 類型

前綴	類型	來源
ou_	使用者ID	API回傳
oc_	群聊ID	im_v1_chat_list
bascn	多維表格	URL中 base/ 後
tbl	資料表	URL參數 table=
doxcn	文件	搜尋結果或URL
wikcn	知識庫節點	知識庫URL

快速範例

# 發送訊息
工具: mcp__lark-mcp__im_v1_message_create
data:
  receive_id: "oc_xxxxx"
  msg_type: "text"
  content: '{"text": "訊息內容"}'
params:
  receive_id_type: "chat_id"

# 建立群組
工具: mcp__lark-mcp__im_v1_chat_create
data:
  name: "群組名稱"
  chat_mode: "group"
  owner_id: "ou_xxxxx"
  user_id_list: ["ou_xxxxx"]
params:
  user_id_type: "open_id"

# 建立多維表格記錄
工具: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"
data:
  fields:
    文字欄位: "值"
    單選欄位: "選項名稱"
useUAT: true

# 搜尋文件
工具: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "關鍵字"
  count: 10
useUAT: true

錯誤速查

錯誤	原因	解決
tool not found	伺服器名稱錯誤	使用 mcp__lark-mcp__ 前綴
99991663	權限不足	useUAT: true 或設定 OAuth
131005 not found	token 類型錯誤	檢查用 wikcn 還是 doxcn
建立資源無法存取	租戶身份建立	使用 useUAT: true
field not found	欄位名稱錯誤	用 appTableField_list 確認
invalid content	格式錯誤	content 用單引號包裹 JSON

詳細文件: troubleshooting.md | installation.md