飞书开源 CLI 火了：lark-openapi-mcp 从安装到接入 AI IDE 的实战教程

(Updated: )

飞书开源 CLI 火了：lark-openapi-mcp 从安装到接入 AI IDE 的实战教程

背景

2026 年 3 月 29 日这波开发圈里讨论很多的“飞书开源 CLI”，我理解大概率指的是飞书官方开源的 lark-openapi-mcp。

它严格来说不只是一个传统 CLI，更准确地说，是一个通过 npx 直接启动的 MCP 服务：把飞书 / Lark OpenAPI 封装成 AI Agent 可调用的工具。你可以把它接到 Cursor、Trae、Claude Desktop，或者任何支持 stdio MCP 的客户端里，让 AI 直接去读文档、发消息、查日历、操作多维表格。

这也是它最近被关注的原因：不是再写一堆胶水代码，而是几乎开箱即用。

一句话先讲明白它是什么

lark-openapi-mcp 做的事情可以概括成一句话：

把飞书开放平台 API 变成 AI IDE / AI Agent 能直接调用的一组工具。

所以它更适合下面这些场景：

  • 让 AI 搜索飞书知识库、读取文档内容
  • 让 AI 发送飞书消息、查群、拉群成员
  • 让 AI 创建日历事件、查询忙闲状态
  • 让 AI 读写多维表格数据
  • 让 AI 创建和维护任务

但它不是一个万能飞书客户端。官方文档已经明确写了两个当前限制：

  • 暂不支持文件上传和下载
  • 暂不支持直接编辑飞书云文档正文，只支持导入和读取

另外，官方 README 也明确标注它目前仍处于 Beta 阶段，接口和行为后续可能还会调整。

先准备什么

上手前你至少要准备这几样：

  1. Node.js
  2. 一个飞书开放平台应用
  3. 应用的 App ID 和 App Secret
  4. 需要什么能力，就给应用开什么权限

如果你打算让 AI 以“用户身份”访问飞书资源，比如读取某个用户自己的文档、发送 IM 消息，那么还要额外配置 OAuth 回调地址：

1
http://localhost:3000/callback

从官方变更记录看，0.4.0 之后最低兼容 Node 版本已经提升到了 Node 20，所以别再拿太老的 Node 环境启动。

最快跑通的方法

如果你只是想先把 MCP 连起来，最简单的做法是在你的 MCP Client 配置里加一段：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "cli_xxx",
        "-s",
        "your_app_secret",
        "-t",
        "preset.default"
      ]
    }
  }
}

这里有几个关键点：

  • npx -y @larksuiteoapi/lark-mcp：直接拉起官方包
  • mcp：启动 MCP 服务
  • -a / -s：传入飞书应用凭证
  • -t preset.default：启用默认预设工具集

如果你只是想先做最小验证，我反而建议从 preset.light 开始，工具更少，AI 更不容易乱选工具：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "cli_xxx",
        "-s",
        "your_app_secret",
        "-t",
        "preset.light"
      ]
    }
  }
}

连上之后，你可以直接让 AI 试下面几类任务：

  • 搜索知识库里和“入职流程”有关的文档
  • 读取某篇飞书文档正文
  • 给某个群发送一条消息
  • 在多维表格里查一条记录

如果你要“用户身份”调用 API

很多人第一次接的时候会踩这个坑：应用身份能跑起来，不代表就能访问用户私有资源。

如果你要让 AI 读“某个用户自己的文档”、发“用户授权范围内”的消息，建议按官方 README 的方式走一遍登录：

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

然后 MCP 配置里加上：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "cli_xxx",
        "-s",
        "your_app_secret",
        "--oauth",
        "--token-mode",
        "user_access_token",
        "-t",
        "preset.default"
      ]
    }
  }
}

这里最重要的是 --token-mode user_access_token。

官方文档已经点得很直白：如果你启用了 --oauth，但仍然保留默认 auto，AI 在推理过程中可能会退回去使用 tenant_access_token，最后表现出来就是“明明配好了，为什么还权限不足”。

预设工具集怎么选

这套工具的一个设计重点，是官方提前帮你打包了几类 preset。

我把最常用的几个翻译成人话：

  • preset.light
    最小可用集，适合先验证链路
  • preset.default
    默认推荐，覆盖消息、文档、数据库和协作类能力
  • preset.doc.default
    更偏文档、知识库、权限协作
  • preset.calendar.default
    更偏日历事件和忙闲状态查询
  • preset.task.default
    更偏任务创建、修改、提醒

如果你知道自己只需要少数工具，也可以混搭：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "mcpServers": {
    "lark-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@larksuiteoapi/lark-mcp",
        "mcp",
        "-a",
        "cli_xxx",
        "-s",
        "your_app_secret",
        "-t",
        "preset.light,im.v1.message.create"
      ]
    }
  }
}

这个思路很实用：先用 preset 控住主要能力，再按需补单个 API。

一个更实用的接入建议

如果你是第一次接飞书 MCP，我建议按这个顺序来：

  1. 先用 preset.light 跑通
  2. 只验证“搜索文档”或“发消息”这一个场景
  3. 再切到 preset.default
  4. 最后再接 OAuth 和 user_access_token

原因很简单：MCP 接入失败，最容易混在一起的变量有四个：

  • 应用权限没开
  • 回调地址没配
  • token 模式配错
  • 工具集开太多导致 AI 选错

按上面的顺序拆开，你定位问题会快很多。

另外两个容易忽略的坑

1. 飞书中国版和国际版域名别混

默认是中国版飞书域名：

1
https://open.feishu.cn

如果你用的是国际版 Lark，需要显式加：

1
2
"--domain",
"https://open.larksuite.com"

而且应用本身也必须创建在对应平台，不能混着用。

2. 非 preset API 现在不建议一上来就猛开

官方 README 里专门提醒了一句：非预设 API 没有经过兼容性测试。

这句话的潜台词就是，理论上能调，不代表当前模型就一定会稳定调对。

如果你是为了“让 AI 现在就能靠谱干活”，优先走官方 preset，比自己胡乱拼一大串 API 名字靠谱得多。

我的结论

如果你问我，这个项目值不值得现在就学？

我的答案是：值得，而且很适合现在就上手。

原因不在于它把飞书所有能力都做完了，而在于它把最麻烦的一层接线工作标准化了。对大多数开发者来说，真正的门槛从“怎么接飞书 API”变成了“我到底要让 AI 干什么”。

如果你正好在折腾 AI IDE、企业内知识库问答、文档自动化、飞书机器人联动，这个项目非常值得你这周就装起来试一下。

参考资料