lark-mcp
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseLark MCP (飞书集成)
Lark MCP (Feishu Integration)
⚠️ 必读:前5条关键规则 + 重要经验
⚠️ Must-read: Top 5 Key Rules + Important Experiences
重要经验:使用用户身份创建资源
yaml
undefinedImportant Experience: Create Resources Using User Identity
yaml
undefined⭐ 关键:使用 useUAT: true 创建用户可访问的资源
⭐ Key: Use useUAT: true to create resources accessible by users
useUAT: true # ✅ 用户身份 - 创建者=当前用户,您可以直接访问
useUAT: false # ❌ 租户身份 - 创建者=飞书助手,您无法直接访问
**经验总结(来自实际测试):**
1. **Bitable 创建权限问题** - 使用 useUAT: false 创建的 Base,创建者是"飞书助手",当前用户无法访问
2. **外部邮箱权限限制** - 通过 API 添加外部邮箱权限会失败(错误码 1063001)
3. **解决方案** - 使用 useUAT: true 创建资源,创建者自动获得 full_access 权限
4. **文档权限** - 同样适用,使用用户身份创建文档
**1. 服务器名称必须精确**
```bash
✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__ (错误:下划线)
❌ lark-mcp__ (错误:缺少前缀)2. 嵌套参数结构
yaml
path: # URL路径参数(必需)
app_token: ...
table_id: ...
params: # URL查询参数(可选)
user_id_type: "open_id"
data: # 请求体(可选)
fields: {...}
useUAT: false # 默认使用租户token3. 消息 content 必须是字符串
bash
❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'4. 过滤条件 value 必须是数组
bash
❌ value: "已完成"
✅ value: ["已完成"]5. ID 类型不能混淆
open_id - 用户ID(推荐)
chat_id - 群聊ID
app_token - 表格应用ID
table_id - 表格ID
record_id - 记录IDuseUAT: true # ✅ User identity - Creator = current user, you can access directly
useUAT: false # ❌ Tenant identity - Creator = Feishu Assistant, you cannot access directly
**Experience Summary (From Actual Testing):**
1. **Bitable Creation Permission Issue** - Bases created with useUAT: false have "Feishu Assistant" as the creator, and the current user cannot access them
2. **External Email Permission Restriction** - Adding external email permissions via API will fail (error code 1063001)
3. **Solution** - Create resources using useUAT: true, and the creator automatically gets full_access permission
4. **Document Permissions** - The same applies, create documents using user identity
**1. Server Name Must Be Exact**
```bash
✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__ (Error: underscore)
❌ lark-mcp__ (Error: missing prefix)2. Nested Parameter Structure
yaml
path: # URL path parameters (required)
app_token: ...
table_id: ...
params: # URL query parameters (optional)
user_id_type: "open_id"
data: # Request body (optional)
fields: {...}
useUAT: false # Use tenant token by default3. Message content Must Be a String
bash
❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'4. Filter Condition value Must Be an Array
bash
❌ value: "Completed"
✅ value: ["Completed"]5. ID Types Cannot Be Confused
open_id - User ID (recommended)
chat_id - Group chat ID
app_token - Bitable app ID
table_id - Table ID
record_id - Record ID快速开始
Quick Start
示例1:查询多维表格记录
Example 1: Query Bitable Records
yaml
工具: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "your_app_token" # 需要替换为实际的 Base 应用 ID(从 URL 获取)
table_id: "your_table_id" # 需要替换为实际的表格 ID(从 URL 获取)
params:
page_size: 20
data:
filter:
conjunction: "and"
conditions:
- field_name: "状态"
operator: "is"
value: ["已完成"]yaml
Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "your_app_token" # Replace with actual Base app ID (obtained from URL)
table_id: "your_table_id" # Replace with actual table ID (obtained from URL)
params:
page_size: 20
data:
filter:
conjunction: "and"
conditions:
- field_name: "Status"
operator: "is"
value: ["Completed"]示例2:发送文本消息到群组
Example 2: Send Text Message to Group
yaml
工具: mcp__lark-mcp__im_v1_message_create
data:
receive_id: "oc_xxxxx" # 需要替换为实际的群组 chat_id
msg_type: "text"
content: '{"text": "消息内容"}'
params:
receive_id_type: "chat_id"yaml
Tool: mcp__lark-mcp__im_v1_message_create
data:
receive_id: "oc_xxxxx" # Replace with actual group chat_id
msg_type: "text"
content: '{"text": "Message content"}'
params:
receive_id_type: "chat_id"示例3:搜索文档
Example 3: Search Documents
yaml
工具: mcp__lark-mcp__docx_builtin_search
data:
search_key: "关键词"
count: 10
useUAT: trueyaml
Tool: mcp__lark-mcp__docx_builtin_search
data:
search_key: "Keywords"
count: 10
useUAT: true工具分类
Tool Categories
多维表格 (Bitable)
Bitable
- - 创建 Base 应用
bitable_v1_app_create - - 列出所有表格
bitable_v1_appTable_list - - 创建新表格
bitable_v1_appTable_create - - 获取字段列表
bitable_v1_appTableField_list - - 查询记录
bitable_v1_appTableRecord_search - - 创建记录
bitable_v1_appTableRecord_create - - 更新记录
bitable_v1_appTableRecord_update
详细指南:reference/bitable.md
- - Create Base app
bitable_v1_app_create - - List all tables
bitable_v1_appTable_list - - Create new table
bitable_v1_appTable_create - - Get field list
bitable_v1_appTableField_list - - Query records
bitable_v1_appTableRecord_search - - Create records
bitable_v1_appTableRecord_create - - Update records
bitable_v1_appTableRecord_update
Detailed Guide: reference/bitable.md
消息 (Messages)
Messages
- - 发送消息
im_v1_message_create - - 获取聊天历史
im_v1_message_list - - 创建群组
im_v1_chat_create - - 获取群组列表
im_v1_chat_list - - 获取群成员
im_v1_chatMembers_get
详细指南:reference/messages.md
- - Send messages
im_v1_message_create - - Get chat history
im_v1_message_list - - Create groups
im_v1_chat_create - - Get group list
im_v1_chat_list - - Get group members
im_v1_chatMembers_get
Detailed Guide: reference/messages.md
文档 (Documents)
Documents
- - 搜索文档
docx_builtin_search - - 导入文档
docx_builtin_import - - 获取文档内容
docx_v1_document_rawContent
详细指南:reference/documents.md
- - Search documents
docx_builtin_search - - Import documents
docx_builtin_import - - Get document content
docx_v1_document_rawContent
Detailed Guide: reference/documents.md
群组 (Groups)
Groups
- - 创建群组
im_v1_chat_create - - 获取成员列表
im_v1_chatMembers_get - - 获取群组列表
im_v1_chat_list
详细指南:reference/groups.md
- - Create groups
im_v1_chat_create - - Get member list
im_v1_chatMembers_get - - Get group list
im_v1_chat_list
Detailed Guide: reference/groups.md
权限 (Permissions)
Permissions
- - 添加协作者权限
drive_v1_permissionMember_create
详细指南:reference/permissions.md
- - Add collaborator permissions
drive_v1_permissionMember_create
Detailed Guide: reference/permissions.md
联系人 (Contacts)
Contacts
- - 通过邮箱/手机号获取用户ID
contact_v3_user_batchGetId
- - Get user ID via email/phone number
contact_v3_user_batchGetId
Wiki (知识库)
Wiki
- - 搜索 Wiki 节点
wiki_v1_node_search - - 获取节点信息
wiki_v2_space_getNode
- - Search Wiki nodes
wiki_v1_node_search - - Get node information
wiki_v2_space_getNode
认证说明
Authentication Instructions
Token 类型
Token Types
- useUAT: true - 用户访问令牌(用户操作)
- useUAT: false - 租户访问令牌(后台操作,默认)
- useUAT: true - User access token (user operations)
- useUAT: false - Tenant access token (backend operations, default)
获取 ID
Obtain IDs
从 URL 获取:
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
↑app_token ↑table_id获取用户 open_id:
yaml
工具: mcp__lark-mcp__contact_v3_user_batchGetId
data:
emails: ["user@example.com"] # 需要替换为实际的用户邮箱
params:
user_id_type: "open_id"Obtain from URL:
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
↑app_token ↑table_idGet user open_id:
yaml
Tool: mcp__lark-mcp__contact_v3_user_batchGetId
data:
emails: ["user@example.com"] # Replace with actual user email
params:
user_id_type: "open_id"user_id_type 参数
user_id_type Parameter
始终使用 (最通用,推荐)。
"open_id"可选值: | |
"open_id""union_id""user_id"Always use (most universal, recommended).
"open_id"Optional values: | |
"open_id""union_id""user_id"核心工作流
Core Workflows
工作流1:创建多维表格并添加记录(用户可访问版本)
Workflow 1: Create Bitable and Add Records (User-accessible Version)
任务进度:
- [ ] 步骤1: 创建 Base 应用(⭐ useUAT: true)
- [ ] 步骤2: 创建表格和字段
- [ ] 步骤3: 插入记录
- [ ] 步骤4: 验证数据步骤1: 创建 Base 应用
yaml
工具: mcp__lark-mcp__bitable_v1_app_create
data:
name: "项目管理" # 可以修改为您需要的名称
time_zone: "Asia/Shanghai"
useUAT: true # ⭐ 重要:使用用户身份,确保您可以直接访问步骤2: 创建表格和字段
yaml
工具: mcp__lark-mcp__bitable_v1_appTable_create
path:
app_token: "bascnxxxxxx" # 需要替换为步骤1返回的实际 app_token
data:
table:
name: "表格名称"
default_view_name: "默认视图"
fields:
- field_name: "姓名"
ui_type: "Text"
- field_name: "年龄"
ui_type: "Number"
- field_name: "状态"
ui_type: "SingleSelect"
property:
options:
- name: "进行中"
- name: "已完成"注意: 创建成功后,响应中会返回 ,保存它用于下一步。
table_id步骤3: 插入记录
yaml
工具: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
app_token: "bascnxxxxxx" # 需要替换为步骤1返回的实际值
table_id: "tblxxxxxx" # 需要替换为步骤2返回的实际值
data:
fields:
姓名: "张三"
年龄: 25
状态: "进行中"步骤4: 验证数据
yaml
工具: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "bascnxxxxxx" # 需要替换为实际的 app_token
table_id: "tblxxxxxx" # 需要替换为实际的 table_id
params:
page_size: 10Task Progress:
- [ ] Step 1: Create Base app (⭐ useUAT: true)
- [ ] Step 2: Create table and fields
- [ ] Step 3: Insert records
- [ ] Step 4: Verify dataStep 1: Create Base app
yaml
Tool: mcp__lark-mcp__bitable_v1_app_create
data:
name: "Project Management" # Can be modified to your required name
time_zone: "Asia/Shanghai"
useUAT: true # ⭐ Important: Use user identity to ensure direct accessStep 2: Create Table and Fields
yaml
Tool: mcp__lark-mcp__bitable_v1_appTable_create
path:
app_token: "bascnxxxxxx" # Replace with actual app_token returned from Step 1
data:
table:
name: "Table Name"
default_view_name: "Default View"
fields:
- field_name: "Name"
ui_type: "Text"
- field_name: "Age"
ui_type: "Number"
- field_name: "Status"
ui_type: "SingleSelect"
property:
options:
- name: "In Progress"
- name: "Completed"Note: After successful creation, the response will return , save it for the next step.
table_idStep 3: Insert Records
yaml
Tool: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
app_token: "bascnxxxxxx" # Replace with actual value returned from Step 1
table_id: "tblxxxxxx" # Replace with actual value returned from Step 2
data:
fields:
Name: "Zhang San"
Age: 25
Status: "In Progress"Step 4: Verify Data
yaml
Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "bascnxxxxxx" # Replace with actual app_token
table_id: "tblxxxxxx" # Replace with actual table_id
params:
page_size: 10工作流2:查询表格并发送消息
Workflow 2: Query Table and Send Messages
任务进度:
- [ ] 步骤1: 查询表格数据
- [ ] 步骤2: 处理查询结果
- [ ] 步骤3: 构造消息
- [ ] 步骤4: 发送到群组步骤1: 查询数据
yaml
工具: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "bascnxxxxxx" # 需要替换为实际的 app_token
table_id: "tblxxxxxx" # 需要替换为实际的 table_id
params:
page_size: 10
data:
filter:
conjunction: "and"
conditions:
- field_name: "状态"
operator: "is"
value: ["待处理"]步骤2: 处理查询结果
查询成功后,响应中包含 数组,每项包含记录的 。
data.itemsfieldsyaml
undefinedTask Progress:
- [ ] Step 1: Query table data
- [ ] Step 2: Process query results
- [ ] Step 3: Construct message
- [ ] Step 4: Send to groupStep 1: Query Data
yaml
Tool: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
app_token: "bascnxxxxxx" # Replace with actual app_token
table_id: "tblxxxxxx" # Replace with actual table_id
params:
page_size: 10
data:
filter:
conjunction: "and"
conditions:
- field_name: "Status"
operator: "is"
value: ["Pending"]Step 2: Process Query Results
After successful query, the response contains the array, each item includes the record's .
data.itemsfieldsyaml
undefined响应结构示例
Example Response Structure
data:
items:
- record_id: "recxxxx"
fields:
任务名称: "完成文档"
状态: "待处理"
**步骤3: 构造消息**
根据查询结果构造消息内容:
```yamldata:
items:
- record_id: "recxxxx"
fields:
Task Name: "Complete Document"
Status: "Pending"
**Step 3: Construct Message**
Construct message content based on query results:
```yaml示例:构造文本消息
Example: Construct text message
message = "找到 " + items.length + " 个待处理任务:\n"
for each item in items:
message += "- " + item.fields["任务名称"] + "\n"
**步骤4: 发送消息**
```yaml
工具: mcp__lark-mcp__im_v1_message_create
data:
receive_id: "oc_xxxxx" # 需要替换为实际的群组 chat_id
msg_type: "text"
content: '{"text": "处理结果:..."}'
params:
receive_id_type: "chat_id"message = "Found " + items.length + " pending tasks:\n"
for each item in items:
message += "- " + item.fields["Task Name"] + "\n"
**Step 4: Send Message**
```yaml
Tool: mcp__lark-mcp__im_v1_message_create
data:
receive_id: "oc_xxxxx" # Replace with actual group chat_id
msg_type: "text"
content: '{"text": "Processing results: ..."}'
params:
receive_id_type: "chat_id"工作流3:搜索文档并获取内容
Workflow 3: Search Documents and Get Content
任务进度:
- [ ] 步骤1: 搜索文档
- [ ] 步骤2: 获取 document_id
- [ ] 步骤3: 提取文档内容
- [ ] 步骤4: 处理文本步骤1: 搜索
yaml
工具: mcp__lark-mcp__docx_builtin_search
data:
search_key: "项目报告"
count: 10
useUAT: true步骤2: 获取 document_id
搜索成功后,从响应中提取第一个文档的 :
document_idyaml
undefinedTask Progress:
- [ ] Step 1: Search documents
- [ ] Step 2: Get document_id
- [ ] Step 3: Extract document content
- [ ] Step 4: Process textStep 1: Search
yaml
Tool: mcp__lark-mcp__docx_builtin_search
data:
search_key: "Project Report"
count: 10
useUAT: trueStep 2: Get document_id
After successful search, extract the of the first document from the response:
document_idyaml
undefined响应结构示例
Example Response Structure
data:
items:
- document_id: "doxcnxxxxxx" # ← 保存这个
title: "项目报告"
...
**步骤3: 获取内容**
```yaml
工具: mcp__lark-mcp__docx_v1_document_rawContent
path:
document_id: "doxcnxxxxxx" # 需要替换为步骤2获取的实际 document_id
params:
lang: 0
useUAT: truedata:
items:
- document_id: "doxcnxxxxxx" # ← Save this
title: "Project Report"
...
**Step 3: Get Content**
```yaml
Tool: mcp__lark-mcp__docx_v1_document_rawContent
path:
document_id: "doxcnxxxxxx" # Replace with actual document_id obtained from Step 2
params:
lang: 0
useUAT: true常见错误排查
Common Error Troubleshooting
错误1: "tool not found"
Error 1: "tool not found"
原因: 服务器名称拼写错误
解决: 确保使用 前缀(注意连字符)
mcp__lark-mcp__Cause: Incorrect server name spelling
Solution: Ensure to use the prefix (note the hyphens)
mcp__lark-mcp__错误2: "invalid request"
Error 2: "invalid request"
原因: 参数嵌套错误
解决: 检查 path/params/data 层级,path 参数通常必需
Cause: Incorrect parameter nesting
Solution: Check the path/params/data hierarchy; path parameters are usually required
错误3: "field not found"
Error 3: "field not found"
原因: 字段名错误或 ID 类型错误
解决:
- 确认 与表格字段名完全一致
field_name - 确认使用正确的 ID 类型(app_token vs table_id)
Cause: Incorrect field name or wrong ID type
Solution:
- Confirm that exactly matches the table field name
field_name - Confirm using the correct ID type (app_token vs table_id)
错误4: "permission denied"
Error 4: "permission denied"
原因: 权限不足或 token 类型错误
解决:
- 检查应用是否有该资源的访问权限
- 用户操作使用
useUAT: true - 后台操作使用
useUAT: false
Cause: Insufficient permissions or wrong token type
Solution:
- Check if the app has access permissions for the resource
- Use for user operations
useUAT: true - Use for backend operations
useUAT: false
错误5: 消息发送失败
Error 5: Message Sending Failed
原因: content 格式错误或 receive_id_type 错误
解决:
- content 必须是 JSON 字符串,不是对象
- 发送到群组使用
receive_id_type: "chat_id" - 发送到用户使用
receive_id_type: "open_id"
Cause: Incorrect content format or wrong receive_id_type
Solution:
- content must be a JSON string, not an object
- Use for sending to groups
receive_id_type: "chat_id" - Use for sending to users
receive_id_type: "open_id"
参数校验清单
Parameter Verification Checklist
使用前检查:
- 服务器名称:
mcp__lark-mcp__tool_name - path 参数必需且正确(app_token, table_id, record_id 等)
- content 是 JSON 字符串(消息相关)
- value 是数组(过滤条件)
- 枚举值精确匹配(user_id_type, operator 等)
- ID 类型正确(open_id vs chat_id vs app_token)
- useUAT 设置正确(用户 true,后台 false)
Check before use:
- Server name:
mcp__lark-mcp__tool_name - path parameters are required and correct (app_token, table_id, record_id, etc.)
- content is a JSON string (for message-related operations)
- value is an array (for filter conditions)
- Enumeration values match exactly (user_id_type, operator, etc.)
- Correct ID type (open_id vs chat_id vs app_token)
- useUAT is set correctly (true for users, false for backend)
实践中遇到的问题
Issues Encountered in Practice
问题1: 创建的 Base 无法访问
Issue 1: Created Base Is Inaccessible
现象:
- 使用 创建 Base 应用
useUAT: false - 创建者显示为"飞书助手"
- 当前用户无法直接访问,权限受限
解决方案:
yaml
useUAT: true # ✅ 用户身份 - 创建者=当前用户,可直接访问
useUAT: false # ❌ 租户身份 - 需要额外设置权限Phenomenon:
- Create Base app with
useUAT: false - Creator shows as "Feishu Assistant"
- Current user cannot access directly due to permission restrictions
Solution:
yaml
useUAT: true # ✅ User identity - Creator = current user, accessible directly
useUAT: false # ❌ Tenant identity - Requires additional permission settings问题2: API 添加权限失败
Issue 2: API Permission Addition Failed
现象:
- 通过 添加邮箱权限
drive_v1_permissionMember_create - 错误码:1063001 (Invalid parameter)
- 无法通过 API 授予外部用户访问权限
根本原因:
- 租户身份创建的资源,API 权限添加有限制
- 外部邮箱权限可能不支持通过 API 操作
最佳实践:
- 优先使用用户身份()创建资源
useUAT: true - 创建者自动获得 权限
full_access - 避免后续复杂的权限配置
Phenomenon:
- Add email permissions via
drive_v1_permissionMember_create - Error code: 1063001 (Invalid parameter)
- Cannot grant external users access via API
Root Cause:
- Resources created with tenant identity have restrictions on API permission additions
- External email permissions may not be supported via API operations
Best Practice:
- Prioritize creating resources using user identity ()
useUAT: true - The creator automatically gets permission
full_access - Avoid complex permission configurations later
问题3: 字段类型不匹配
Issue 3: Field Type Mismatch
现象:
- Bitable 查询时 "field not found"
- 使用了错误的字段 ID 类型
解决方案:
yaml
undefinedPhenomenon:
- "field not found" when querying Bitable
- Used wrong field ID type
Solution:
yaml
undefined从 URL 获取正确的 ID(appxxxxx 和 tblxxxxx 是需要替换的占位符)
Get correct IDs from URL (appxxxxx and tblxxxxx are placeholders to replace)
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
↑app_token ↑table_id
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
↑app_token ↑table_id
查询前先获取字段列表确认字段名
Get field list to confirm field names before querying
工具: mcp__lark-mcp__bitable_v1_appTableField_list
undefinedTool: mcp__lark-mcp__bitable_v1_appTableField_list
undefined问题4: 群主身份问题
Issue 4: Group Owner Identity Problem
现象:
- 使用 创建群组
useUAT: true - 创建者仍显示为应用机器人(app_id)
- 消息发送者 为 "app",不是 "user"
sender_type
根本原因:
- 只是使用用户权限/令牌操作
useUAT: true - 系统记录的"创建者"始终是应用本身
- 这是飞书 API 的设计机制
解决方案:
yaml
undefinedPhenomenon:
- Create groups with
useUAT: true - Creator still shows as app robot (app_id)
- Message sender is "app", not "user"
sender_type
Root Cause:
- only uses user permissions/tokens for operations
useUAT: true - The system-recorded "creator" is always the app itself
- This is a design mechanism of Feishu API
Solution:
yaml
undefined必须明确指定 owner_id
Must explicitly specify owner_id
工具: mcp__lark-mcp__im_v1_chat_create
data:
owner_id: "ou_xxxxx" # 指定用户为群主
user_id_list: ["ou_xxxxx"]
**注意:** 不指定 `owner_id` 时,群主默认为应用机器人。Tool: mcp__lark-mcp__im_v1_chat_create
data:
owner_id: "ou_xxxxx" # Specify user as group owner
user_id_list: ["ou_xxxxx"]
**Note**: If `owner_id` is not specified, the group owner defaults to the app robot.参考文档
Reference Documents
- 多维表格操作指南
- 消息发送指南
- 文档操作指南
- 群组管理指南
- 权限管理指南
- Bitable 查询示例
- 消息格式示例
- Bitable Operation Guide
- Message Sending Guide
- Document Operation Guide
- Group Management Guide
- Permission Management Guide
- Bitable Query Examples
- Message Format Examples