lark-mcp工具全景图:飞书/Lark 375+个OpenAPI中哪些能被AI直接调用

原创2026-10-25 12:05:192,207 阅读

lark-mcp工具全景图:飞书/Lark 375+个OpenAPI中哪些能被AI直接调用

lark-mcp 是飞书/Lark 官方推出的 OpenAPI MCP(Model Context Protocol)工具,它把飞书开放平台的海量 OpenAPI 封装成 AI 可以直接调用的 MCP 工具,让你的 AI 助手能一键完成发消息、建日程、读写多维表格、管理文档等自动化操作。这篇文章带你摸清它的"工具全景图":61 个业务域、1200+ 个可调用工具、8 个精选预设,以及哪些 API 开箱即用、哪些需要手动开启。

先搞懂:lark-mcp 是怎么让 AI 调 OpenAPI 的?

传统方式下,想让 AI 操作飞书,你得自己写胶水代码:处理鉴权、拼请求、解析响应。lark-mcp 的思路是——把每个 OpenAPI 封装成一个带参数 Schema 的 MCP 工具,注册给 MCP 客户端(Cursor、Trae、Claude Desktop 等)。AI 拿到自然语言指令后,自己选择工具、填参数,MCP 服务负责真正调用飞书 API。

它的核心机制在源码中很清晰:mcp-tool.ts 中的 LarkMcpTool 类负责初始化工具列表,而 filter-tools.ts 中的 filterTools 函数则决定了"哪些工具最终暴露给 AI"——这正是后文"按需开启 API"的底层逻辑。

对新手来说,最实用的结论是:你不需要关心 1200+ 个工具,默认预设已经帮你挑好了最常用的 19 个。

工具全景:61 个业务域、1288 个工具

完整的工具清单收录在 tools-zh.md,按业务域(domain)组织,共 61 个业务域、1288 个 MCP 工具。每个工具名都遵循 业务域.版本号.资源.动作 的命名规则,比如 im.v1.message.create 就是"消息域 v1 版本的创建消息"接口,看名字就能猜到它干什么。

按工具数量排名的"大户"业务域:

业务域 工具数 能做什么
corehr(人事) 229 员工入转调离、组织管理等人事核心流程
hire(招聘) 178 职位、候选人、面试全流程
task(任务) 74 任务创建、成员管理、提醒
contact(通讯录) 70 部门、用户、角色、用户组管理
mail(邮箱) 67 邮件收发与账号管理
im(即时消息) 66 群聊、消息收发、群成员
vc(音视频) 55 视频会议与妙记
drive(云空间) 52 文件、文件夹、权限管理
bitable(多维表格) 46 数据表、字段、记录、视图
calendar(日历) 41 日程创建、忙闲查询、参与人
attendance(考勤) 37 打卡、排班、班次、统计
apaas(应用引擎) 37 自定义应用的数据与流程操作

除了这些高频场景,清单里还覆盖了审批(approval)、云文档(docx)、知识库(wiki)、飞书词典(baike)、智能门禁(acs)、薪酬(compensation/payroll)、绩效(performance)、OKR、搜索(search)、翻译(translation)、语音转文字(speech_to_text)等长尾能力。完整列表请直接查阅 tools-zh.md(英文版为 tools-en.md)。

💡 注意:并非每个工具都适合 AI 直接调用。部分 API 未做兼容性测试,官方建议优先使用预设中的工具,效果最稳定。

8 个预设工具集:开箱即用的"精选套餐"

面对 1288 个工具,官方在 constants.ts 中定义了 8 个预设(preset),每个预设是一组经过验证的工具组合,通过 -t 参数一键启用:

预设名 工具数 适用场景
preset.default(默认) 19 消息 + 文档 + 多维表格 + 通讯录,大多数人直接用这个
preset.light 10 最小化配置,只保留发消息、读文档等核心能力
preset.im.default 5 专注群聊创建、成员管理与消息收发
preset.base.default 7 多维表格的基础数据管理
preset.base.batch 7 多维表格批量读写,适合数据处理
preset.doc.default 6 文档读取、导入、搜索与协作权限
preset.task.default 4 创建/修改任务、加成员、设提醒
preset.calendar.default 5 创建日程、查忙闲、查主日历

每个预设包含哪些工具,可对照 presets-zh.md 中的对照表(带 ✓ 标记即为该预设包含的工具)。预设名也可以和单个工具混着写,例如 preset.calendar.default,im.v1.chat.search,灵活度很高。

最快上手:只改一个参数的 3 步接入

第 1 步:创建飞书应用。登录飞书开放平台,在开发者后台创建应用,拿到 App ID 和 App Secret,并按需为应用开通 API 权限。

第 2 步:安装 Node.js(LTS 版本),用 node -v 验证即可。

第 3 步:在 MCP 客户端配置中加一段 JSON(以 Cursor 为例):

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

启动后 AI 即可调用默认预设的 19 个工具。想换预设,只需加一个参数:

"-t", "preset.im.default"

完整的命令行参数(包括传输模式 -m、语言 -l、命名格式 -c 等)见 cli-zh.md;更详细的分场景配置见 configuration-zh.md。

进阶:用应用身份还是用户身份调 API?

这是新手最容易踩的坑。lark-mcp 支持两种令牌模式:

  • 应用身份(tenant_access_token,默认):代表"机器人应用"本身,适合群消息推送、公共文档操作。
  • 用户身份(user_access_token):代表"某个具体的人",适合读个人文档、以本人名义发消息、操作自己的日历。

想用用户身份,先执行一次 OAuth 登录(令牌会加密保存在本地,后续复用):

npx -y @larksuiteoapi/lark-mcp login -a cli_xxxx -s yyyyy

然后在配置中加上 --oauth 和 --token-mode user_access_token。令牌模式的选择逻辑同样由 filterTools 过滤——某些工具只允许特定身份调用,选错模式会直接报权限不足。相关实现可参考 is-token-valid.ts 与 storage-manager.ts。

常见限制与排错(避坑清单)

以下是官方 FAQ(faq-zh.md)中最高频的几个问题:

现象 原因与解决
提示 token 超过上限 工具太多占满了模型上下文。用 -t 只开需要的工具,或换上下文更长的模型
调用 API 提示权限不足 开发者后台未开通对应权限,或 --scope 授权范围不够,需重新 login
文件/图片上传下载失败 当前版本暂不支持文件上传下载
云文档无法直接编辑 云文档目前仅支持导入和读取,不能直接改内容
user_access_token 报错 令牌通常 2 小时过期,重新执行 login 即可

另外还有一个隐藏彩蛋:仓库里附带了开发文档检索 MCP(recall-mcp/README_ZH.md),可以帮 AI 快速检索飞书开放平台的开发文档,和 OpenAPI MCP 搭配使用,一个负责"查文档"、一个负责"跑接口"。

总结:一张表带走

  • 工具池有多大:61 个业务域、1288 个工具,全量清单见 tools-zh.md
  • 默认能用什么:preset.default 的 19 个工具,覆盖消息、文档、表格、通讯录四大高频场景
  • 怎么换菜单:MCP 配置里加 -t 参数指定预设或单个工具名
  • 身份怎么选:机器人操作用应用身份,碰个人数据就 login + --oauth 走用户身份
  • 已知边界:暂不支持文件上传下载与云文档直接编辑;非预设 API 未经兼容性测试

飞书官方 OpenAPI MCP 把"调接口"这件事变成了"说句话"的事——工具清单已经铺好,你只需要挑对预设,剩下的交给 AI。

登录后查看全文
lark-openapi-mcp