lark-mcp工具全景图:飞书/Lark 375+个OpenAPI中哪些能被AI直接调用
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。