lark-mcp

Lark MCP

⚠️ Important Notes

Searching documents/knowledge base requires OAuth:

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

Otherwise, error 99991663 is returned. See installation.md for configuration.

---

Core Rules

# Tool naming (hyphen, not underscore)
✅ 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

Common Pitfalls

# content must be a JSON string
❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'

# Filter condition value must be an array
❌ value: "已完成"
✅ value: ["已完成"]

# Creating a group requires owner_id, otherwise the bot becomes the group owner
owner_id: "ou_xxxxx"

# Parameter name differences
docx_builtin_search: search_key  # not query
wiki_v1_node_search: query       # not search_key

# Token types
wiki_v2_space_getNode: use wikcn...  # not doxcn...
docx_v1_document_rawContent: use doxcn...

useUAT Selection

Scenario	useUAT
Creating resources (user-accessible)	true
Searching documents/knowledge base	true
Accessing user private data	true
Querying public data	false

Tool Quick Reference

Category	Tool	Docs
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
Wiki	wiki_v1_node_search, wiki_v2_space_getNode	wiki.md

ID Types

Prefix	Type	Source
ou_	User ID	API response
oc_	Chat ID	im_v1_chat_list
bascn	Bitable	After base/ in URL
tbl	Table	URL parameter table=
doxcn	Document	Search results or URL
wikcn	Wiki node	Wiki URL

Quick Examples

# Send message
Tool: mcp__lark-mcp__im_v1_message_create
data:
  receive_id: "oc_xxxxx"
  msg_type: "text"
  content: '{"text": "Message content"}'
params:
  receive_id_type: "chat_id"

# Create group
Tool: mcp__lark-mcp__im_v1_chat_create
data:
  name: "Group name"
  chat_mode: "group"
  owner_id: "ou_xxxxx"
  user_id_list: ["ou_xxxxx"]
params:
  user_id_type: "open_id"

# Create Bitable record
Tool: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"
data:
  fields:
    Text field: "value"
    Single select field: "option name"
useUAT: true

# Search document
Tool: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "keyword"
  count: 10
useUAT: true

Error Quick Reference

Error	Cause	Solution
tool not found	Wrong server name	Use mcp__lark-mcp__ prefix
99991663	Insufficient permissions	useUAT: true or configure OAuth
131005 not found	Wrong token type	Check if using wikcn or doxcn
Created resource inaccessible	Created with tenant identity	Use useUAT: true
field not found	Wrong field name	Use appTableField_list to confirm
invalid content	Format error	Wrap content JSON in single quotes

Detailed docs: troubleshooting.md | installation.md