Lark MCP (飞书集成)

⚠️ 必读：前5条关键规则 + 重要经验

重要经验：使用用户身份创建资源

# ⭐ 关键：使用 useUAT: true 创建用户可访问的资源
useUAT: true   # ✅ 用户身份 - 创建者=当前用户，您可以直接访问
useUAT: false  # ❌ 租户身份 - 创建者=飞书助手，您无法直接访问

经验总结（来自实际测试）：

1. Bitable 创建权限问题 – 使用 useUAT: false 创建的 Base，创建者是”飞书助手”，当前用户无法访问
2. 外部邮箱权限限制 – 通过 API 添加外部邮箱权限会失败（错误码 1063001）
3. 解决方案 – 使用 useUAT: true 创建资源，创建者自动获得 full_access 权限
4. 文档权限 – 同样适用，使用用户身份创建文档

1. 服务器名称必须精确

✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__ (错误：下划线)
❌ lark-mcp__ (错误：缺少前缀)

2. 嵌套参数结构

path:           # URL路径参数（必需）
  app_token: ...
  table_id: ...
params:         # URL查询参数（可选）
  user_id_type: "open_id"
data:           # 请求体（可选）
  fields: {...}
useUAT: false   # 默认使用租户token

3. 消息 content 必须是字符串

❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'

4. 过滤条件 value 必须是数组

❌ value: "已完成"
✅ value: ["已完成"]

5. ID 类型不能混淆

open_id   - 用户ID（推荐）
chat_id   - 群聊ID
app_token - 表格应用ID
table_id  - 表格ID
record_id - 记录ID

快速开始

示例1：查询多维表格记录

工具: 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: ["已完成"]

示例2：发送文本消息到群组

工具: 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"

示例3：搜索文档

工具: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "关键词"
  count: 10
useUAT: true

工具分类

多维表格 (Bitable)

• bitable_v1_app_create – 创建 Base 应用
• 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

消息 (Messages)

• im_v1_message_create – 发送消息
• im_v1_message_list – 获取聊天历史
• im_v1_chat_create – 创建群组
• im_v1_chat_list – 获取群组列表
• im_v1_chatMembers_get – 获取群成员

详细指南：reference/messages.md

文档 (Documents)

• docx_builtin_search – 搜索文档
• docx_builtin_import – 导入文档
• docx_v1_document_rawContent – 获取文档内容

详细指南：reference/documents.md

群组 (Groups)

• im_v1_chat_create – 创建群组
• im_v1_chatMembers_get – 获取成员列表
• im_v1_chat_list – 获取群组列表

详细指南：reference/groups.md

权限 (Permissions)

• drive_v1_permissionMember_create – 添加协作者权限

详细指南：reference/permissions.md

联系人 (Contacts)

• contact_v3_user_batchGetId – 通过邮箱/手机号获取用户ID

Wiki (知识库)

• wiki_v1_node_search – 搜索 Wiki 节点
• wiki_v2_space_getNode – 获取节点信息

认证说明

Token 类型

• useUAT: true – 用户访问令牌（用户操作）
• useUAT: false – 租户访问令牌（后台操作，默认）

获取 ID

从 URL 获取：

https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
                         ↑app_token    ↑table_id

获取用户 open_id：

工具: mcp__lark-mcp__contact_v3_user_batchGetId
data:
  emails: ["user@example.com"]  # 需要替换为实际的用户邮箱
params:
  user_id_type: "open_id"

user_id_type 参数

始终使用 "open_id"（最通用，推荐）。

可选值："open_id" | "union_id" | "user_id"

核心工作流

工作流1：创建多维表格并添加记录（用户可访问版本）

任务进度：
- [ ] 步骤1: 创建 Base 应用（⭐ useUAT: true）
- [ ] 步骤2: 创建表格和字段
- [ ] 步骤3: 插入记录
- [ ] 步骤4: 验证数据

步骤1: 创建 Base 应用

工具: mcp__lark-mcp__bitable_v1_app_create
data:
  name: "项目管理"  # 可以修改为您需要的名称
  time_zone: "Asia/Shanghai"
useUAT: true  # ⭐ 重要：使用用户身份，确保您可以直接访问

步骤2: 创建表格和字段

工具: 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: 插入记录

工具: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
  app_token: "bascnxxxxxx"  # 需要替换为步骤1返回的实际值
  table_id: "tblxxxxxx"     # 需要替换为步骤2返回的实际值
data:
  fields:
    姓名: "张三"
    年龄: 25
    状态: "进行中"

步骤4: 验证数据

工具: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
  app_token: "bascnxxxxxx"  # 需要替换为实际的 app_token
  table_id: "tblxxxxxx"     # 需要替换为实际的 table_id
params:
  page_size: 10

工作流2：查询表格并发送消息

任务进度：
- [ ] 步骤1: 查询表格数据
- [ ] 步骤2: 处理查询结果
- [ ] 步骤3: 构造消息
- [ ] 步骤4: 发送到群组

步骤1: 查询数据

工具: 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.items 数组，每项包含记录的 fields。

# 响应结构示例
data:
  items:
    - record_id: "recxxxx"
      fields:
        任务名称: "完成文档"
        状态: "待处理"

步骤3: 构造消息

根据查询结果构造消息内容：

# 示例：构造文本消息
message = "找到 " + items.length + " 个待处理任务：\n"
for each item in items:
  message += "- " + item.fields["任务名称"] + "\n"

步骤4: 发送消息

工具: 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"

工作流3：搜索文档并获取内容

任务进度：
- [ ] 步骤1: 搜索文档
- [ ] 步骤2: 获取 document_id
- [ ] 步骤3: 提取文档内容
- [ ] 步骤4: 处理文本

步骤1: 搜索

工具: mcp__lark-mcp__docx_builtin_search
data:
  search_key: "项目报告"
  count: 10
useUAT: true

步骤2: 获取 document_id

搜索成功后，从响应中提取第一个文档的 document_id：

# 响应结构示例
data:
  items:
    - document_id: "doxcnxxxxxx"  # ← 保存这个
      title: "项目报告"
      ...

步骤3: 获取内容

工具: mcp__lark-mcp__docx_v1_document_rawContent
path:
  document_id: "doxcnxxxxxx"  # 需要替换为步骤2获取的实际 document_id
params:
  lang: 0
useUAT: true

常见错误排查

错误1: “tool not found”

原因: 服务器名称拼写错误 解决: 确保使用 mcp__lark-mcp__ 前缀（注意连字符）

错误2: “invalid request”

原因: 参数嵌套错误 解决: 检查 path/params/data 层级，path 参数通常必需

错误3: “field not found”

原因: 字段名错误或 ID 类型错误 解决:

• 确认 field_name 与表格字段名完全一致
• 确认使用正确的 ID 类型（app_token vs table_id）

错误4: “permission denied”

原因: 权限不足或 token 类型错误 解决:

• 检查应用是否有该资源的访问权限
• 用户操作使用 useUAT: true
• 后台操作使用 useUAT: false

错误5: 消息发送失败

原因: content 格式错误或 receive_id_type 错误 解决:

• content 必须是 JSON 字符串，不是对象
• 发送到群组使用 receive_id_type: "chat_id"
• 发送到用户使用 receive_id_type: "open_id"

参数校验清单

使用前检查：

• 服务器名称：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）

实践中遇到的问题

问题1: 创建的 Base 无法访问

现象：

• 使用 useUAT: false 创建 Base 应用
• 创建者显示为”飞书助手”
• 当前用户无法直接访问，权限受限

解决方案：

useUAT: true   # ✅ 用户身份 - 创建者=当前用户，可直接访问
useUAT: false  # ❌ 租户身份 - 需要额外设置权限

问题2: API 添加权限失败

现象：

• 通过 drive_v1_permissionMember_create 添加邮箱权限
• 错误码：1063001 (Invalid parameter)
• 无法通过 API 授予外部用户访问权限

根本原因：

• 租户身份创建的资源，API 权限添加有限制
• 外部邮箱权限可能不支持通过 API 操作

最佳实践：

• 优先使用用户身份（useUAT: true）创建资源
• 创建者自动获得 full_access 权限
• 避免后续复杂的权限配置

问题3: 字段类型不匹配

现象：

• Bitable 查询时 “field not found”
• 使用了错误的字段 ID 类型

解决方案：

# 从 URL 获取正确的 ID（appxxxxx 和 tblxxxxx 是需要替换的占位符）
https://xxx.feishu.cn/base/appxxxxx?table=tblxxxxx
                         ↑app_token    ↑table_id

# 查询前先获取字段列表确认字段名
工具: mcp__lark-mcp__bitable_v1_appTableField_list

问题4: 群主身份问题

现象：

• 使用 useUAT: true 创建群组
• 创建者仍显示为应用机器人（app_id）
• 消息发送者 sender_type 为 “app”，不是 “user”

根本原因：

• useUAT: true 只是使用用户权限/令牌操作
• 系统记录的”创建者”始终是应用本身
• 这是飞书 API 的设计机制

解决方案：

# 必须明确指定 owner_id
工具: mcp__lark-mcp__im_v1_chat_create
data:
  owner_id: "ou_xxxxx"  # 指定用户为群主
  user_id_list: ["ou_xxxxx"]

注意： 不指定 owner_id 时，群主默认为应用机器人。

参考文档

• 多维表格操作指南
• 消息发送指南
• 文档操作指南
• 群组管理指南
• 权限管理指南
• Bitable 查询示例
• 消息格式示例