Lark Mcp

Lark MCP

⚠️ 重要提醒

搜索文档/知识库必须配置 OAuth：

• docx_builtin_search → 需要 --oauth
• wiki_v1_node_search → 需要 --oauth

否则返回 99991663 错误。配置方法见 installation.md

---

核心规则

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

# 参数结构
path: {app_token, table_id}   # URL路径参数
params: {page_size, ...}      # 查询参数
data: {fields, ...}           # 请求体
useUAT: false                 # true=用户身份, false=租户身份

常见陷阱

# 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 选择

工具速查

ID 类型

快速示例

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

错误速查

详细文档: troubleshooting.md | installation.md

Bitable 查询示例

常用查询

精确匹配

data:
  filter:
    conjunction: "and"
    conditions:
      - field_name: "状态"
        operator: "is"
        value: ["已完成"]

文本包含

data:
  filter:
    conditions:
      - field_name: "任务名称"
        operator: "contains"
        value: ["关键词"]

数值/日期范围

data:
  filter:
    conditions:
      - field_name: "优先级"
        operator: "isGreater"
        value: ["3"]

空值检查

data:
  filter:
    conditions:
      - field_name: "负责人"
        operator: "isEmpty"
        value: []

多条件

data:
  filter:
    conjunction: "and"  # 或 "or"
    conditions:
      - field_name: "状态"
        operator: "is"
        value: ["待处理"]
      - field_name: "优先级"
        operator: "isGreater"
        value: ["3"]

操作符

消息格式示例

文本

{"text": "消息内容"}

富文本

基础

{
  "post": {
    "zh_cn": {
      "title": "标题",
      "content": [[{"tag": "text", "text": "内容"}]]
    }
  }
}

样式

[
  {"tag": "text", "text": "普通"},
  {"tag": "text", "text": "加粗", "style": ["bold"]},
  {"tag": "a", "text": "链接", "href": "https://example.com"},
  {"tag": "at", "user_id": "ou_xxxxx"}
]

元素

样式

• bold - 加粗
• italic - 斜体
• strikethrough - 删除线

多维表格 (Bitable)

核心规则

# 创建资源用用户身份
useUAT: true

# 过滤条件 value 必须是数组
✅ value: ["已完成"]
❌ value: "已完成"

# 使用 field_name 而非 field_id
field_name: "状态"

URL 解析

https://xxx.feishu.cn/base/bascnxxxxxx?table=tblxxxxxx
                         ↑app_token         ↑table_id

工作流

1. 创建 Base

工具: mcp__lark-mcp__bitable_v1_app_create
data:
  name: "Base名称"
useUAT: true

返回 app_token 和 default_table_id。

2. 创建数据表

工具: mcp__lark-mcp__bitable_v1_appTable_create
path:
  app_token: "bascnxxxxxx"
data:
  table:
    name: "表名"
    fields:
      - field_name: "文本"
        ui_type: "Text"
      - field_name: "单选"
        ui_type: "SingleSelect"
        property:
          options:
            - name: "选项1"
      - field_name: "日期"
        ui_type: "DateTime"
useUAT: true

3. 查询记录

工具: mcp__lark-mcp__bitable_v1_appTableRecord_search
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"
data:
  filter:
    conjunction: "and"
    conditions:
      - field_name: "状态"
        operator: "is"
        value: ["已完成"]

4. 创建记录

工具: mcp__lark-mcp__bitable_v1_appTableRecord_create
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"
data:
  fields:
    文本字段: "值"
    单选字段: "选项名"
    日期字段: 1705276800000
useUAT: true

5. 更新记录

工具: mcp__lark-mcp__bitable_v1_appTableRecord_update
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"
  record_id: "recxxxxxx"
data:
  fields:
    状态: "已完成"
useUAT: true

字段类型

操作符

辅助工具

# 获取数据表列表
工具: mcp__lark-mcp__bitable_v1_appTable_list
path:
  app_token: "bascnxxxxxx"

# 获取字段列表
工具: mcp__lark-mcp__bitable_v1_appTableField_list
path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"

常见错误

群组管理

核心规则

# 必须指定 owner_id，否则群主为机器人
data:
  owner_id: "ou_xxxxx"
  user_id_list: ["ou_xxxxx"]

创建群组

工具: mcp__lark-mcp__im_v1_chat_create
data:
  name: "群名"
  chat_mode: "group"
  chat_type: "private"       # private/public
  owner_id: "ou_xxxxx"
  user_id_list: ["ou_xxxxx"]
params:
  user_id_type: "open_id"

最简参数：

data:
  chat_mode: "group"
params:
  user_id_type: "open_id"

返回 chat_id 格式为 oc_ 开头。

获取群组列表

工具: mcp__lark-mcp__im_v1_chat_list
params:
  page_size: 50

可直接调用，无需参数。返回机器人所在的所有群组。

获取群成员

工具: mcp__lark-mcp__im_v1_chatMembers_get
path:
  chat_id: "oc_xxxxx"
params:
  member_id_type: "open_id"

群组类型

常见错误

通用概念

参数结构

path: {app_token, table_id, chat_id}  # URL路径参数
params: {page_size, user_id_type}     # 查询参数
data: {fields, content, ...}          # 请求体
useUAT: false                         # true=用户身份, false=租户身份

useUAT 选择

ID 类型

分页

params:
  page_size: 50
  page_token: ""  # 首次为空，后续用返回值

响应包含 has_more 和 page_token。

错误码

联系人

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

工具: mcp__lark-mcp__contact_v3_user_batchGetId
data:
  emails: ["user@example.com"]
  mobiles: ["+8613800138000"]
params:
  user_id_type: "open_id"

注意: 手机号格式为 国家码+号码，如 +8613800138000

响应

{
  "user_list": [
    {"email": "user@example.com", "open_id": "ou_xxxxx"}
  ],
  "fail_user_list": [
    {"email": "notexist@example.com", "message": "user not found"}
  ]
}

典型场景

# 1. 通过手机号获取 open_id
工具: mcp__lark-mcp__contact_v3_user_batchGetId
data:
  mobiles: ["+8613800138000"]

# 2. 使用 open_id 添加权限
工具: mcp__lark-mcp__drive_v1_permissionMember_create
data:
  member_type: "openid"
  member_id: "ou_xxxxx"
  perm: "view"

文档操作

核心规则

# 搜索文档必须使用用户身份
useUAT: true

# 参数名注意
docx_builtin_search: search_key  # 不是 query
wiki_v1_node_search: query       # 不是 search_key

搜索文档

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

响应：

{
  "docs_entities": [
    {
      "docs_token": "doxcnxxxxxx",
      "title": "文档标题",
      "docs_type": "docx"
    }
  ]
}

获取文档内容

工具: mcp__lark-mcp__docx_v1_document_rawContent
path:
  document_id: "doxcnxxxxxx"
params:
  lang: 0  # 0=中文, 1=英文
useUAT: true

导入 Markdown

工具: mcp__lark-mcp__docx_builtin_import
data:
  markdown: "# 标题\n\n正文内容..."
  file_name: "文档.md"
useUAT: true

返回文档 URL 和 token。

docs_types 可选值

从 URL 获取 document_id

https://xxx.feishu.cn/docx/doxcnxxxxxx
                          ↑ document_id

常见错误

工作流：导入并分享

# 1. 导入 Markdown
工具: mcp__lark-mcp__docx_builtin_import
data:
  markdown: "# 报告\n\n内容..."

# 2. 添加权限（使用返回的 token）
工具: mcp__lark-mcp__drive_v1_permissionMember_create
path:
  token: "返回的token"
params:
  type: "docx"
data:
  member_type: "email"
  member_id: "user@example.com"
  perm: "view"

消息操作

核心规则

# content 必须是 JSON 字符串
❌ content: {"text": "hello"}
✅ content: '{"text": "hello"}'

# receive_id_type 必须匹配 receive_id 类型
receive_id: "oc_xxxxx"
receive_id_type: "chat_id"

发送消息

工具: mcp__lark-mcp__im_v1_message_create
data:
  receive_id: "oc_xxxxx"
  msg_type: "text"
  content: '{"text": "消息内容"}'
params:
  receive_id_type: "chat_id"

消息类型

富文本元素

content: '{
  "post": {
    "zh_cn": {
      "title": "标题",
      "content": [
        [{"tag": "text", "text": "正文"}],
        [{"tag": "at", "user_id": "ou_xxx", "text": "@张三"}]
      ]
    }
  }
}'

获取消息历史

工具: mcp__lark-mcp__im_v1_message_list
params:
  container_id_type: "chat"
  container_id: "oc_xxxxx"
  page_size: 50

时间范围过滤：

params:
  start_time: "1705276800"  # 秒级时间戳
  end_time: "1705363200"

常见错误

安装配置

快速配置

{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": ["-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "<app_id>", "-s", "<app_secret>"]
    }
  }
}

注意: 不要使用 -t 限制工具，否则只会加载指定工具。

参数

OAuth 配置

以下工具需要用户令牌：

• docx_builtin_search（搜索文档）
• wiki_v1_node_search（搜索知识库）

⚠️ 常见坑

只加 `--oauth` 不够，必须同时加 `--token-mode user_access_token`：

// ❌ 错误：只加 --oauth，仍返回 99991663
{"args": ["-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "cli_xxx", "-s", "xxx", "--oauth"]}

// ✅ 正确：必须同时添加
{"args": ["-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "cli_xxx", "-s", "xxx", "--oauth", "--token-mode", "user_access_token"]}

弄好之后需要重启agent工具

配置步骤

1. 终端登录

npx -y @larksuiteoapi/lark-mcp login -a cli_xxx -s xxx

2. 更新配置

{
  "mcpServers": {
    "lark-mcp": {
      "args": [
        "-y", "@larksuiteoapi/lark-mcp", "mcp",
        "-a", "cli_xxx", "-s", "xxx",
        "--oauth",
        "--token-mode", "user_access_token"
      ]
    }
  }
}

3. 配置重定向 URL

飞书开放平台 → 应用 → 安全设置 → 添加：

http://localhost:3000/callback

4. 重启 Claude Code

OAuth 效果

常见问题

预设工具集

获取凭证

1. 访问 飞书开放平台 2. 创建企业自建应用 3. 获取 App ID 和 App Secret 4. 添加所需权限

相关链接

• 飞书开放平台
• MCP 集成文档

权限管理

核心规则

# member_type 必须与 member_id 匹配
member_type: "openid"
member_id: "ou_xxxxx"

member_type: "email"
member_id: "user@example.com"

添加权限

工具: mcp__lark-mcp__drive_v1_permissionMember_create
path:
  token: "doxcnxxxxxx"
data:
  member_type: "openid"
  member_id: "ou_xxxxx"
  perm: "edit"
params:
  type: "docx"
useUAT: true

member_type

权限类型

资源类型

常见错误

故障排查

错误速查

常见问题

tool not found

检查工具名称格式：

✅ mcp__lark-mcp__tool_name
❌ mcp__lark_mcp__tool_name

99991663 Invalid access token

原因: 知识库/文档搜索需要用户令牌

解决: 1. 配置 OAuth（见 installation.md） 2. 或在工具调用中使用 useUAT: true

131005 document is not in wiki

原因: wiki_v2_space_getNode 使用了文档 token

解决: 使用 wikcn 开头的知识库节点 token

知识库节点 token: wikcnxxxxxx  ✅
文档 token: doxcnxxxxxx        ❌

创建的资源无法访问

原因: 使用租户身份创建，创建者是"飞书助手"

解决:

useUAT: true

field not found

原因: 字段名错误或使用了 field_id

解决: 用 bitable_v1_appTableField_list 确认字段名

invalid request

常见原因:

1. content 格式错误

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

2. 过滤 value 不是数组

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

3. 缺少 path 参数

path:
  app_token: "bascnxxxxxx"
  table_id: "tblxxxxxx"

群主显示为机器人

解决: 创建群组时指定 owner_id

data:
  owner_id: "ou_xxxxx"

调试技巧

1. 检查 MCP 服务

工具: mcp__lark-mcp__im_v1_chat_list
params:
  page_size: 1

2. 最小参数测试

先用必需参数测试，再逐步添加可选参数。

3. 查看错误详情

错误响应格式：

{
  "code": 99991663,
  "msg": "具体错误信息"
}

获取帮助

• 飞书开放平台文档
• MCP 集成文档

知识库 (Wiki)

⚠️ 必须配置 OAuth

知识库工具需要用户令牌，否则返回 99991663 错误。

配置方法: 见 installation.md

搜索知识库节点

工具: mcp__lark-mcp__wiki_v1_node_search
data:
  query: "关键词"        # 参数名是 query，不是 search_key
  page_size: 20

响应：

{
  "items": [
    {
      "node_id": "wikcnxxxxxx",
      "obj_token": "doxcnxxxxxx",
      "obj_type": 8,
      "title": "节点标题"
    }
  ]
}

获取节点信息

工具: mcp__lark-mcp__wiki_v2_space_getNode
params:
  token: "wikcnxxxxxx"  # 必须是知识库节点 token

注意: token 必须以 wik 开头，不能用文档 token (doxcn)。

Token 类型

从 URL 获取 token

知识库节点: https://xxx.feishu.cn/wiki/wikcnxxxxxx
                                        ↑ 知识库节点 token

文档: https://xxx.feishu.cn/docx/doxcnxxxxxx
                                ↑ 文档 token（不能用于 wiki_v2_space_getNode）

常见错误

与文档工具配合

# 1. 搜索知识库
工具: mcp__lark-mcp__wiki_v1_node_search
data:
  query: "关键词"

# 2. 用 obj_token 读取文档内容
工具: mcp__lark-mcp__docx_v1_document_rawContent
path:
  document_id: "obj_token值"
useUAT: true