Lark MCP (飞书集成)

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

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

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

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

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

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

...

lark-mcp

SKILL.md