lark-mcp

Lark MCP

⚠️ Important reminder

Searching documents/knowledge bases requires OAuth configuration：

• docx_builtin_search → requires --oauth
• wiki_v1_node_search → requires --oauth

otherwise returns error 99991663. For configuration method, see installation.md

---

Core rules

# 工具命名（连字符，非下划线）
✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__tool_name

Parameter structure

path: {app_token, table_id} # URL path parameters params: {page_size, ...} # query parameters data: {fields, ...} # request body useUAT: false # true=user identity, false=tenant identity

## 常见陷阱

```yaml
# 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 selection

Scenario	useUAT
Create resource (want users to be able to access it)	true
Search documents/knowledge bases	true
Access user private data	true
Query public data	false

Tool quick reference

Category	Tool	Document
Message	im_v1_message_create, im_v1_message_list	im.md
Group	im_v1_chat_create, im_v1_chat_list, im_v1_chatMembers_get	chat.md
Bitable	bitable_v1_app_create, bitable_v1_appTableRecord_search/create/update	bitable.md
Document	docx_builtin_search, docx_v1_document_rawContent, docx_builtin_import	documents.md
Knowledge base	wiki_v1_node_search, wiki_v2_space_getNode	wiki.md

ID type

Prefix	Type	Source
ou_	User ID	API return
oc_	Group chat ID	im_v1_chat_list
bascn	Bitable	In URL base/ after
tbl	Data table	URL parameter table=
doxcn	Document	Search results or URL
wikcn	Knowledge base node	Knowledge base URL

Quick example

# 发送消息
工具: 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

Error quick reference

Error	Cause	Solution
tool not found	Server name error	Use mcp__lark-mcp__ prefix
99991663	Insufficient permissions	useUAT: true or configure OAuth
131005 not found	token type error	Check whether to use wikcn or doxcn
Created resource cannot be accessed	Created with tenant identity	Use useUAT: true
field not found	Field name error	Use appTableField_list to confirm
invalid content	Format error	content wraps JSON in single quotes

Detailed documentation: troubleshooting.md | installation.md