@dsh-feishu/mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@dsh-feishu/mcp 把工作区里最新的季度报告发到飞书群"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
这是第一代方案,线上机器人已被第二代取代。 第二代:dsh-feishu-channel —— 它不再给每条消息 spawn 一个
dsh headless子进程,而是接进 DSH 的原生会话 (inbox 的next-turn/next-step),所以「跑着的时候补一句」能真的插进去,而不是排队。第一代仍然有价值的两个部分:
packages/mcp(43 个工具的 MCP server,任何时候都能单独用) 与packages/dsh-plugin(DSH 里的飞书连接设置页)。services/feishu-bot是现在线上那个bot.py的前身。仓库打扫记录:
dsh-feishu-mcp、dsh-feishu-plugin原本是本仓库packages/mcp、packages/dsh-plugin的构建产物镜像(提交信息里写着 "sync: 从主仓库打包/同步"),内容与主仓库重复,已归档(只读,可恢复)。
它是什么
飞书会话就是 agent 的操作台。在手机上发一句话,它在你的机器上执行,把文件、卡片、 多维表格发回会话——而不是回你一段「建议执行以下命令」。
不需要公网 IP、内网穿透、域名或证书:机器人主动向飞书发起 WebSocket 长连接,不开放入站端口。
它由三个角色组成,各自负责一段:
角色 | 职责 |
| 常驻长连接。身份校验、会话管理、任务队列、进度卡、审批按钮。自身不执行任务 |
agent | 实际执行方。 |
| 只做一件事:把卡片按钮的点击精确投递给正在等待回答的那次 |
Related MCP server: Feishu/Lark OpenAPI MCP
它解决什么问题
你说 | 它做 |
把上周的纳米技术报告发我 | 在工作区找到 3 份 |
建一张读书清单的多维表格 | 建表 → 建 4 个字段 → 写入第一条记录,返回链接 |
跑一下这个季度的文献综述,做完汇报 | 排进队列,进度在同一张卡片里刷新,聊天中只占一个气泡 |
清一下 | 先发审批卡,确认后才执行 |
我在高铁上,帮我看下服务器还活着吗 | 返回 CPU / 内存 / 磁盘 / 服务状态 |
发一张试卷照片,说「帮我批改」 | 图片经 |
换个最会想的模型,慢慢算 |
|
群里三个人同时发话 | 并行执行(默认上限 3 路),同一个人的任务仍按顺序;回复 @ 到人,群静音也收得到 |
选中一张旧图说「你重新做这个」 | 先取回被引用的消息,图片重新下载落盘,模型再看一遍 |
机器人另外承担:白名单认领、每人一份独立会话记忆、任务队列、超时兜底、每日汇报、危险动作拦截。 图片与文件消息的处理见 BOT-ATTACHMENTS.md,群内免 @ 见 BOT-GROUP-MODE.md,并发与引用回溯见 BOT-RUNTIME.md。
安装
前置条件:一个飞书自建应用、一台能运行 DeepSeek Harness 的机器、Node 22+。 应用需要开通的 scope 见权限。
方式一:设置页向导(推荐)
装好插件后,DSH 设置面板左栏会多出「飞书连接」,内含四步向导
(步骤条 1 建应用 → 2 填凭据 → 3 选会话 → 4 自检,完成一步点亮一项):
建应用 —— 直达开放平台的链接,附 11 项权限清单,可一键复制
填凭据 —— App ID / Secret,保存时先校验再落盘,凭据错误不会写坏文件
选会话 —— 「扫描我的会话」列出机器人所在会话,无需手抄 32 位
oc_串自检 —— 九项逐个真调接口:凭据文件、MCP 挂载、应用凭据、机器人身份、会话列表、 目标会话、读聊天记录、上传文件、云空间
自检每项下方一行小字是判定依据:凭据文件末四位、token 剩余秒数、机器人应用名、会话名、
file_key 前几位。九项全绿时底部提示「工具已经挂进 profile,重启 DSH 之后 mcp__feishu__* 就能用了」。
失败项会给出该开通的 scope 与跳转链接,并支持「一次开通全部缺失权限」。
自检不往会话里发任何内容:读历史只读 1 条,上传只传 20 字节且不发送。
方式二:命令行安装
只装 DSH 里的飞书设置页(不装 MCP、不跑安装器)时,直接从本仓库装插件包:
dsh plugin --profile web add "github:yinsang0910-star/dsh-feishu#path:packages/dsh-plugin"#path:packages/dsh-plugin 不能省——仓库根是 pnpm workspace,只有这个子目录是 DSH bundle(dsh.bundle.patch + dsh.client.platform: web,dist/ 已随仓库提交,装完不需要构建)。装完重启 DSH,设置里会多出「飞书」页。
要连机器人一起装,再跑下面的安装器:
pnpm install && pnpm build
node scripts/install.mjs \
--app-id cli_xxxxxxxx \
--app-secret xxxxxxxx \
--chat-id oc_xxxxxxxx安装器执行四步,每步可单独重跑:
校验凭据 —— 实际换取一次
tenant_access_token并列出会话,凭据错误立即报出写密钥文件 ——
~/.config/dsh/feishu.env,权限0600安装 MCP 启动包装 —— 生成
dsh-feishu-mcp脚本(stdio 子进程的环境变量会被清空, 密钥需由包装脚本自行 source)修改 profile —— 幂等地向
cordis.patch.yml写入带哨兵的托管块
重启 DSH 后,让模型报告工具清单:
echo '你有哪些 mcp__feishu__ 工具?只列名字' | dsh --profile headless --json ---uninstall 只回滚第 3、4 步,不改动密钥文件。可选参数:--profile <名字>(默认 headless)、
--dir <安装目录>、--skip-check。
关于建应用的两点
扫码建应用:第 2 步的「扫码创建」走飞书官方
RFC 8628 设备授权流程。
二维码内容是 open.feishu.cn/page/launcher?user_code=...,手机确认后应用自动创建,
App ID 与 Secret 直接写入本机 feishu.env——浏览器全程不接触 secret,也不需要手抄任何一串。
权限仍需手动开通:应用创建后按第 1 步的清单勾选(提供深链与一键复制)。 飞书没有允许第三方代开权限的通道,这一步无法省略。
只挂 MCP,不要机器人
MCP server 已打成自包含单文件(SDK 与 core 都打包在内),不需要 pnpm install,也不从 npm 安装。
Claude Desktop:从 Releases 下载
dsh-feishu-mcp-<版本>.mcpb,双击安装,在配置面板填入 App ID 与 App Secret。
(同一产物也在镜像仓库 dsh-feishu-mcp 的 Releases 中。)
其他 stdio 客户端:
npx github:yinsang0910-star/dsh-feishu-mcp或从 Releases 下载
dsh-feishu-mcp-<版本>.mjs,node dsh-feishu-mcp.mjs 即可运行(1.5 MB,含全部依赖)。
Docker(镜像里不含任何凭据,运行时注入):
docker build -t dsh-feishu-mcp .
docker run --rm -i -e FEISHU_APP_ID=cli_xxx -e FEISHU_APP_SECRET=xxx dsh-feishu-mcp未配置凭据时进程仍会启动并完成握手,tools/list 正常返回 43 个工具,只有真正调用工具才返回「飞书凭据未配置」——目录站与客户端的自检因此不会看到「server 崩了」。
提供 FEISHU_APP_ID / FEISHU_APP_SECRET 即可运行。挂进 DSH 的方式是编辑
~/.dsh/profiles/<profile>/cordis.patch.yml:
- insert:
- id: mcp-feishu
name: '@deepseek-ai/dsh-mcp-client'
config:
transport: stdio
serverName: feishu
command: npx
args: ['-y', 'github:yinsang0910-star/dsh-feishu-mcp']
# feishu_ask 最多阻塞 600s,工具超时必须比它大
toolCallTimeoutMs: 660000
env:
FEISHU_APP_ID: 'cli_xxx'
FEISHU_APP_SECRET: 'xxx'
FEISHU_DEFAULT_CHAT_ID: 'oc_xxx'serverName: feishu 决定工具前缀(mcp__feishu__*),改动它前缀随之改变。
改代码时改为运行本仓库产物:command: node + args: ['/绝对路径/packages/mcp/dist/server.js']。
镜像仓库 yinsang0910-star/dsh-feishu-mcp
由 scripts/publish-mcp-repo.ps1 单向同步,请勿在该仓库直接改代码。
装完之后
建议同时装记忆插件
本项目只保证会话内连续(同一人 + 同一工作目录)。跨会话、跨项目的长期记忆建议交给 dsh-mnemon(作者 @Grivn,MIT)。
不装的症状很具体:今天告诉它「我叫什么、别用术语」,明天开新会话它一样不知道。装了之后
这些写进 ~/.mnemon/runtime/,每次进上下文。
需要注意:机器人在飞书里跑的是 headless profile,桌面端装过的记忆插件对它无效——
headless 默认只挂了 base + headless 两个 bundle。一条命令补齐:
bash services/agent-workspace/install-mnemon.sh # 幂等,已装则只做检查原理、验证方法、三个坑与回滚见 MNEMON.md。
先看一眼指令
/help 返回一张可点击的卡片:切换模型、切换 reasoningEffort、查看状态、管理工作区、
开关群内是否需要 @。完整指令见 BOT-COMMANDS.md。
权限
在飞书开放平台「权限管理」开通以下 scope,修改后需要发布版本才生效:
scope | 用于 |
| 所有发送类工具 |
| 文件 / 图片的上传下载 |
| 列会话、列成员 |
| 读群聊历史( |
| 读单聊历史 |
| 云空间 |
| 读写云文档 |
| 知识库 |
| 多维表格 |
| 邮箱 / 手机 → open_id |
两项不属于 scope 配置:
机器人必须先被拉进群,
feishu_chats只列它已加入的会话。卡片要支持原地更新,发卡时必须带
config.update_multi = true(本项目自带模板默认已带)。
43 个工具
工具名在客户端里带前缀,形如 mcp__feishu__feishu_send_text。参数细节见
TOOL-CONTRACT.md,逐个工具的说明与危险等级见 MCP-TOOLS.md。
分组 | 工具 |
身份 / 卡片 |
|
发消息 |
|
文件 |
|
上下文 |
|
会话与成员 |
|
群与消息管理 |
|
多维表格 |
|
表格 / 文档 / 云空间 / 知识库 |
|
飞书没有「群文件列表」这个端点:群里的文件是挂在消息上的附件,feishu_chat_files 的实现是
翻最近的群消息再筛出 file / media / audio 类型。删除同理——删的是那条消息,所以走 feishu_recall。
另有卡片模板(progressCard / resultCard / askCard / chatListCard)与统一错误翻译:
scope 未开通时,FeishuApiError.missingScopes 把需要开通的项拼进错误文本,模型可据此提示。
设计取舍
为什么不是 @larksuiteoapi/lark-mcp
官方 lark-mcp 覆盖的是广度:把飞书 OpenAPI 按元数据整体暴露给模型。它的定位没问题,但 「把 IM 当作 agent 界面」最要紧的四项能力它不具备:
缺口 | lark-mcp | 本项目 |
发送本地文件 | 没有 |
|
会话上下文 | 只有「列消息」的原始接口 |
|
阻塞式提问 | 标准 MCP 是请求-响应模型,没有「等待人回答」 |
|
卡片原地更新 | 只能发卡,不能改卡,进度只能刷屏 |
|
需求是「用脚本批量调用飞书 OpenAPI」时,lark-mcp 更合适;需求是「让 agent 在飞书里像同事一样干活」时, 缺的正是上面四项。
架构
packages/
├── core/ @yisang0910/core API 客户端 · 类型 · 卡片模板(零第三方 HTTP 依赖)
├── mcp/ @yisang0910/mcp 43 个工具的 MCP server
├── gateway/ @yisang0910/gateway 卡片问答网关(HTTP + 可选长连接)
└── dsh-plugin/ @yisang0910/plugin DSH 设置页(在 Web UI 里填凭据、测连接)
services/
├── feishu-bot/ 飞书长连接机器人 + 一键部署脚本
└── agent-workspace/ 工作区清理器 + 记忆插件安装脚本
docs/ 架构 · 契约 · 工具清单 · 各模块说明改动代码前请遵守两条硬约束:
stdout 只能输出 MCP 的 JSON-RPC。任何
console.log都会破坏协议,日志一律走 stderr。工具 handler 必须整体 try/catch,异常翻译成
fail(...)返回,不得向上抛出。
状态
版本 0.1.0(Release v0.1.0),
实验阶段:接口与工具名仍可能变化,暂不保证向后兼容。
194 个单测(core 117 + gateway 77),CI 执行 typecheck + test + build + 打包冒烟
下载:Release 提供
dsh-feishu-mcp-0.1.0.mcpb(Claude Desktop 双击安装)与dsh-feishu-mcp-0.1.0.mjs(自包含单文件,node直接运行),附SHA256SUMS.txt暂未发布到 npm:npm 的 2FA 政策阻塞了首次发布,原因与出路见 NPM-PUBLISH.md。插件与 MCP 均可直接从 GitHub 安装 (
dsh plugin … add github:…/npx github:…),不依赖 npm已知限制:
feishu_ask轮询存在延迟与配额成本、单文件上限 30 MB、无多实例锁 —— 详见 ARCHITECTURE.md
文档
按阅读顺序排列:
文档 | 讲什么 |
分层、关键取舍、已知限制 | |
写工具前必读的实现契约 | |
43 个工具逐个说明、危险等级、还缺什么 | |
推荐搭配的记忆插件:为什么、怎么装、怎么验 | |
部署到服务器 | |
网关协议与部署 | |
机器人与网关怎么对接 | |
全部指令 + 换模型/换思考强度怎么落地 | |
并发、回复 @ 到人、引用旧消息回溯 | |
图片/文件消息怎么收( | |
群聊不用 @ 也能用( | |
工作区归档规则与清理分级 | |
发布到 npm 的阻塞点与出路 |
另有两份仓库级说明:CONTRIBUTING.md(环境、目录、提交前要跑什么)与 SECURITY.md(凭据放在哪、怎么报告问题、设计上的边界)。
License
MIT
Available Tools
43 toolsfeishu_ask发问并等人回答(会阻塞)A
在飞书里发一张带选项的卡片问一个问题,然后等人回答,把答案拿回来。用在真的缺关键信息、又没法自己查的时候:要用户拍板方案、要一个他没写在文档里的参数、要确认某个动作要不要执行。⚠️ 这个调用会阻塞(默认 120 秒,最多 600 秒),期间什么都做不了,所以不要滥用,一次任务最多问一两个问题;能靠 feishu_recent 从上下文里读出来的、能自己查到的、能用合理默认值继续的,都不要问。回答来源有两条:①点卡片上的选项按钮(需要网关在跑,毫秒级返回);②对方直接打字回一句。两条都走不通才会超时。返回 answered=true 时 text 就是对方的原话;answered=false 表示超时(不是报错),此时应当按默认方案继续或换个问法,不要反复重试。
Inputs: question (required), chat_id, options, timeout_seconds, +1 more.
feishu_bitable_add新增多维表格记录A
往某个数据表里新增一条记录,返回 record_id(后续更新要用)。这是写操作,会真的改用户的表:不确定字段名和类型时,先调 feishu_bitable_fields 看定义、feishu_bitable_records 看现有数据的写法,别凭猜写。fields 的 key 必须是字段名(不是 field_id),值形态要匹配字段类型:文本传字符串、数字传数字、日期传毫秒时间戳、单选传选项字符串、多选/人员/附件/关联传数组。适合:把对话里的结论、待办、采集到的数据落进表。不适合:批量导入几百条(逐条调用会很慢)。
Inputs: fields (required), table_id (required), app_token (required).
feishu_bitable_delete删除多维表格记录ADestructive
按 record_id 删掉一条记录。不可撤销:删了就没了,没有回收站。record_id 必须先通过 feishu_bitable_records 查到,别自己编。一次只能删一条,要删多条就多次调用。如果用户只是想改状态(比如改成「已完成」),用 feishu_bitable_update,别删。
Inputs: confirm (required), table_id (required), app_token (required), record_id (required).
feishu_bitable_fields数据表的字段定义ARead-only
列出某个数据表的全部字段:字段名、field_id、类型码 + 中文类型名,以及这个字段写入时该传的值形态。新增/更新记录之前先调这个:飞书不同字段类型吃的 JSON 形态完全不同(文本传字符串、日期传毫秒时间戳、人员传 [{"id":"ou_xxx"}]、附件传 [{"file_token":"box_xxx"}]),先看类型码再写 fields,能避免 1254001 / 1254045 之类的字段校验报错。字段名就是 feishu_bitable_add / feishu_bitable_update 里 fields 的 key,必须一字不差。只返回文本,不修改数据。
Inputs: table_id (required), app_token (required).
feishu_bitable_records查询多维表格记录ARead-only
读取某个数据表里的记录,每条都带 record_id,并把字段值展开成人话(人员显示名字、附件显示文件名、多选用顿号连接、日期显示原始毫秒值)。适合:核对数据、找要改的那条记录(先查到 record_id 再 update)、给用户汇报表里有什么。record_id 是更新记录的唯一凭据,所以查询结果里一定会带上。limit 默认 50、最大 500;has_more=true 时把返回的 page_token 传回来继续翻页。只返回文本,不修改数据。
Inputs: table_id (required), app_token (required), limit, page_token.
feishu_bitable_tables多维表格里的数据表ARead-only
列出一张飞书多维表格(Base)里包含哪些数据表,返回每张表的 table_id 与表名。这是所有 bitable 操作的入口:后续查字段、查记录、加记录都要 table_id,而 table_id 只能从这里拿到(用户一般只给 app_token 或一条 Base 链接)。app_token 就是 Base 链接里 /base/ 后面那一串(如 HMr9bcTJcabU8KsD6UGcwVWln9e)。只返回文本,不修改任何数据,可放心在探索阶段调用。不适合:已有 table_id 只是要看字段(用 feishu_bitable_fields);要看记录内容(用 feishu_bitable_records)。
Inputs: app_token (required).
feishu_bitable_update更新多维表格记录A
按 record_id 更新某条记录的部分字段(只覆盖 fields 里出现的字段,其余字段不动)。写操作,会真的改用户的表:record_id 必须先通过 feishu_bitable_records 查到,别自己编。值形态的规矩和 feishu_bitable_add 一样:文本传字符串、数字传数字、日期传毫秒时间戳、单选传选项字符串、多选/人员/附件/关联传数组。适合:修正一条错数据、推进状态、补填附件。不适合:整表批量改(逐条调用)。
Inputs: fields (required), table_id (required), app_token (required), record_id (required).
feishu_chat_announcement读 / 改群公告A
群公告是群顶部那条所有人都能看到的说明。action=get 读现有内容;action=set 改写(mode=replace 整段替换,mode=append 接在末尾)。改公告需要机器人是群主或管理员。
Inputs: action (required), chat_id (required), mode, content.
feishu_chat_create建一个群A
新建群并把指定的人拉进来。机器人建完就是群主,后续能改群名、发消息、置顶。成员要用 open_id(ou_ 开头);不确定 id 先用 feishu_user_lookup 查。
Inputs: name (required), description, member_open_ids.
feishu_chat_dissolve解散一个群ADestructive
解散群。不可撤销:群和群里的消息都会消失,机器人必须是群主。执行前先跟人确认一遍群名和群 id。
Inputs: chat_id (required), confirm (required).
feishu_chat_files列群里发过的文件ARead-only
列出群里发过的文件(对应飞书群聊顶部的「文件」标签页),带消息 id、文件名、大小、发送时间。飞书没有独立的「群文件列表」接口,文件是挂在消息上的,所以这里翻最近的群消息再筛出来。要删某个文件:拿这里的 message_id 去调 feishu_recall。
Inputs: chat_id (required), pages, keyword, page_size.
feishu_chats机器人所在的会话ARead-only
列出机器人当前所在的所有会话(群 + 单聊),返回 chat_id 与名字,供后续发送/读历史时当 target 用。只返回文本,不会往飞书里发任何消息,所以可以放心在探索阶段调用。不确定"该往哪个群发"、或者需要 chat_id 但手上只有群名时,先调这个。人数只在飞书真的返回了 member_count 时才显示;需要确切成员名单请改用 feishu_members。with_members=true 会额外对每个群发一次成员请求(前 5 个名字),会话多时会明显变慢。
Inputs: limit, with_members.
feishu_chat_update改群信息(群名 / 描述 / 谁能拉人)A
改群名、群描述,或调整「谁能邀请成员 / 谁能分享群名片 / 谁能 @所有人」。只传要改的字段,其它保持不动。
Inputs: chat_id (required), name, description, at_all_permission, +2 more.
feishu_doc_append往文档末尾追加正文A
在已有文档最后追加若干段落(每个字符串一段)。配合 feishu_doc_create 建空文档后往里写。只能追加纯文本段落:加粗、表格、图片、标题层级这些富文本结构目前不支持。要改文档中间的内容请用 feishu_doc_blocks 找到块再处理(尚未开放块级编辑)。
Inputs: paragraphs (required), document_id (required).
feishu_doc_blocks读文档结构化块ARead-only
按块(block)读一篇云文档的结构:每块有 block_id、block_type 与内容。和 feishu_doc_read 的区别:doc_read 给的是拼接好的纯文本,适合通读;doc_blocks 保留段落/标题/表格/图片块的分块结构,适合定位「第几段」「哪个表格」以及后续按 block_id 做精细操作。飞书文档的块类型是数字编码(如 2=文本、3-11=各级标题、31=表格),本工具会把能识别的文字内容抽出来,识别不了的块只给类型码。
Inputs: document_id (required), max_pages, page_size.
feishu_doc_create新建飞书文档A
在云空间里新建一个空的 docx 文档,返回 document_id,后续可用 feishu_doc_read 读回校验。使用场景:需要把结果沉淀成一份飞书文档、并且希望它在云空间里可被同事打开时。只建空文档,不写正文内容;需要正文请建完后再用其它编辑能力写。前置条件(重要):当前应用缺 docx:document:create,调用大概率返回 99991672。真失败了不要重试、也不要换参数硬试,去开放平台开通 docx:document:create 并重新发布版本。folder_token 不填等于建在应用自己的根目录(通常同事看不到,建议显式给一个已共享的文件夹)。
Inputs: title (required), folder_token.
feishu_doc_read读飞书文档正文ARead-only
读取一个 docx 文档的纯文本正文(不含图片、表格结构、评论),用于总结、摘录、问答。使用场景:手上已有 document_id,想看文档写了什么。document_id 从哪来:feishu_drive_list 里 docx 条目的 token;或者知识库场景下 feishu_wiki_node 返回的 obj_token(注意是 obj_token,不是 node_token)。前置条件(重要):应用目前有 docs:doc,但没有 docx:document:readonly,读已有文档很可能返回 99991672;拿到这个错误时,需要在开放平台开通 docx:document(或只读版)并重新发布版本后才生效。不要用它读电子表格(用表格工具)或多维表格(用 feishu_bitable_* 工具)。只读,不改文档。
Inputs: document_id (required), max_chars.
feishu_download把用户发来的附件下载到本地A
下载某条飞书消息里的附件(文件或图片)到本地磁盘,返回绝对路径,之后就能用 bash/脚本处理它。典型链路:用户发来一个 docx → 本工具下载 → 本地解析/改写 → feishu_send_file 发回。不传 file_key 时会自动从消息 content 里取(file_key 或 image_key);落盘名优先用消息里自带的名字,没有就用 _<fileKey前8位>.<后缀>,同名文件自动加 -1 后缀不覆盖。
Inputs: message_id (required), kind, dest_dir, file_key.
feishu_drive_list列云空间文件ARead-only
列出云空间(我的空间)里某个文件夹下的文件,返回类型、名字、token、修改时间。使用场景:模型只知道"有个文档/表格",需要先找到它的 token 时;或者要盘点某个目录里都有什么。folder_token 不填等于根目录。返回的 token 就是下一步要用的钥匙:docx 类型的 token 传给 feishu_doc_read 读正文;bitable 类型的 token 传给 feishu_bitable_tables 看表结构。前置条件:应用需要有云空间读取权限(drive:drive 或 drive:drive.metadata:readonly),且目标文件夹已共享给该应用。只读操作,不会修改云空间任何内容。
Inputs: limit, folder_token.
feishu_file_delete删云空间里的文件(不是群消息附件)ADestructive
删除云空间(我的空间/共享空间)里的文件、文档、表格、多维表格或空文件夹。注意:群聊里发的文件是消息附件,那个用 feishu_recall 删消息;这里的 file_token 是云文档体系里的 token(来自 feishu_drive_list),两者不通用。
Inputs: file_token (required), type.
feishu_forward转发一条消息到别的会话A
把某条消息原样转发到另一个群或某个人(不经过改写,卡片/图片/文件都保持原样)。适合:把结果同步给另一个群、把用户发的图转给负责人。
Inputs: to (required), message_id (required), to_type.
feishu_members会话成员名单ARead-only
列出某个会话(群/单聊)里的成员,返回名字 + open_id。适合:确认某人在不在群里、拿到 open_id 用于 @ 或私聊、核对群规模。不适合:只是想看有哪些群(用 feishu_chats);想读聊天内容(用上下文相关工具)。chat_id 不填时用 FEISHU_DEFAULT_CHAT_ID;两者都没有会直接报错说明。只返回文本,不往飞书发消息。
Inputs: limit, chat_id.
feishu_merge_forward把多条消息合并成一份记录转发A
把 2~50 条消息打包成一张「会话记录」卡片发到别处,适合「把这段讨论转给另一个人看」。和 feishu_forward 的区别:forward 是一条一条转,merge_forward 是合成一份带来源的摘要。
Inputs: receive_id (required), message_ids (required), receive_id_type.
feishu_permission_member文档/文件夹的协作者(加人、看谁有权限、移除)A
管云文档的协作者。action=add 把一个人加进协作者(perm=view 可读 / edit 可编辑 / full_access 可管理);action=list 看现在有哪些人、各自什么权限;action=remove 移除一个人。member_type=openid 时 member_id 传 open_id(ou_ 开头),先 feishu_user_lookup 拿到。注意 token 是云文档 token,不是消息附件。
Inputs: token (required), action (required), perm, type, +2 more.
feishu_pin置顶 / 取消置顶一条消息A
把一条消息钉在群顶部(公告性质的关键结论),或取消置顶。适合:把最终结论、规范文件、长期有效的清单钉住。
Inputs: message_id (required), unpin.
feishu_reaction给消息加表情回应 / 查看 / 撤掉A
表情回应是飞书里最轻的「我看到了 / 收到 / 干完了」信号,不占聊天版面。action=add 加一个(emoji_type 用飞书的表情名,如 SMILE、THUMBSUP、DONE、OK、HEART);action=list 看这条消息上有谁回应了什么(返回 reaction_id,撤掉时要用);action=remove 撤掉一个(只能撤机器人自己加的)。
Inputs: action (required), message_id (required), emoji_type, reaction_id.
feishu_recall撤回一条消息ADestructive
撤回机器人自己发出去的消息(飞书只允许撤回 24 小时内的、且只能撤回自己发的)。也用于「删掉群里那个旧文件」——文件是挂在消息上的,删了消息文件就一起没了。不是自己发的消息会失败,这不是权限问题而是飞书规则。
Inputs: message_id (required).
feishu_recent读会话最近的聊天(模型的上文)ARead-only
拉取某个飞书会话最近的消息,按时间正序(早→晚)拍平成文本,让模型知道「刚才聊了什么、谁在说」。典型用法:被叫醒后、要回复之前、要接着上文改文件之前,先调一次这个再动手;也用来确认某个人刚才发的那句话的 message_id,好配合 feishu_reply / feishu_download 用。默认会过滤掉机器人自己发的消息(对模型是噪音),需要看自己说过什么时传 include_bot=true。format=compact 只有「时间 发送人:内容」,适合快速读;format=full 额外带 message_id / msg_type / sender_id,适合接下来要针对某条消息做操作。要「发问并等人回答」不要用这个(轮询要自己写),用 feishu_ask。
Inputs: limit, format, chat_id, include_bot, +1 more.
feishu_reply引用回复某条消息A
在会话里对某条消息做引用回复(飞书会把它挂在原消息下面)。适合:用户点名提问、需要保留"回的是哪一条"的上下文、在刷屏群里避免歧义。不适合:只是想发一条新消息(用 feishu_send_text);需要排版或要后续刷新(用卡片相关工具,回复接口只发纯文本)。
Inputs: text (required), message_id (required).
feishu_send_card发一张交互卡片A
发一张飞书交互卡片(JSON 卡片结构,原样提交,不做模板加工)。适合:需要排版的内容(分块、分隔线、备注脚注)、要展示多字段状态、以及之后需要原地刷新的那类消息。不适合:只有一两句话的短提示(用 feishu_send_text 更直接)。想让卡片后续可被 feishu_update_card 更新,必须在卡片里写 config.update_multi = true。最小可用卡片示例:{ "config": { "wide_screen_mode": true, "update_multi": true }, "header": { "template": "blue", "title": { "tag": "plain_text", "content": "构建结果" } }, "elements": [ { "tag": "div", "text": { "tag": "lark_md", "content": "状态:通过\n耗时:42s" } }, { "tag": "hr" }, { "tag": "note", "elements": [ { "tag": "plain_text", "content": "由 dsh-feishu 发送" } ] } ] }
Inputs: card (required), target.
feishu_send_file把本地文件发进会话A
把本地磁盘上的文件上传并发到飞书会话(文档、压缩包、日志、报表、生成的代码包都行)。这是本项目最核心的工具:任何"我在本地做好了,给你看看"的场景都走它。单个文件上限 30MB,超了会直接报错并给出替代方案。要一次发多个文件,把第一个放 path,其余放 paths;caption 非空时会先发一条纯文本说明再发文件,适合"这是刚才跑出来的结果,重点看第 3 页"。纯图片想直接预览的改用 feishu_send_image;只是想说话不要用这个,用 feishu_send_text。
Inputs: path (required), name, paths, target, +1 more.
feishu_send_image把本地图片发进会话A
把本地图片以"图片消息"发到飞书会话,收到的人可以直接在聊天里看到缩略图、点开大图。只在需要预览时用;要发 PDF、压缩包、代码等非图片文件请用 feishu_send_file。支持 png / jpg / jpeg / gif / webp / bmp,单张上限 10MB。截图、图表、设计稿的效果图都适合走这条。
Inputs: path (required), target, caption.
feishu_send_info_card发一张信息卡A
把"标签 + 值"这类结构化信息渲染成一张飞书卡片发出去。适合汇报状态、列出项目、展示统计;不适合长文本(那用 feishu_send_text)。
Inputs: title (required), fields (required), footer, target.
feishu_send_text发一条纯文本A
往指定会话发一条纯文本消息。适合短结论、一句话提示、快速确认、临时回复。不适合:超过约 30 行的长内容、需要排版/表格/多段落层级的内容 —— 那些改用 feishu_send_card(卡片能分块、加分隔线、加备注,可读得多)。也不适合需要后续原地刷新的场景:文本发出去就改不了,要更新请用卡片 + feishu_update_card。
Inputs: text (required), target.
feishu_sheet_create新建电子表格A
在飞书云空间里新建一张空的电子表格(Sheets),返回 spreadsheet_token 与可分享的链接。写操作,会在用户的云文档里真的建一个文件。适合:用户要"建个表记录一下"这类从零开始的场景。不适合:已经有表格只是要写数据(应该拿现有 spreadsheet_token 去读写,而不是新建)。folder_token 不填就建在"我的空间"根目录;要建进某个文件夹,先用云空间相关工具拿到文件夹 token。建完可以接着用 feishu_send_text 把链接发给用户。
Inputs: title (required), folder_token.
feishu_sheet_meta看电子表格有哪些工作表ARead-only
列出表格里每个工作表的 sheet_id、标题、行列数。写值前先看这个:飞书的写入接口要 sheet_id,而表格链接里给的是 spreadsheet_token,两者不是一回事。feishu_sheet_write 不带 sheet 前缀时会自动取第一个工作表,所以简单场景可以跳过这一步。
Inputs: spreadsheet_token (required).
feishu_sheet_read读电子表格单元格ARead-only
按 A1 区间读一个电子表格的值,返回二维数组(行 × 列)。区间写法:Sheet1!A1:D20(带表名更稳),或 A1:D20(默认第一个工作表)。读整列可以用 Sheet1!A:A。只能读值和公式结果,读不到样式、批注、合并单元格信息。配合 feishu_sheet_create 新建表;写入目前没有开放(飞书的写入接口要求先拿到 sheet_id,需要先读一次拿元数据,暂未支持)。
Inputs: range (required), spreadsheet_token (required).
feishu_sheet_write往电子表格写值 / 追加行ADestructive
把二维数组写进表格。range 写 "Sheet1!A1:B2"(带表名)或只写 "A1:B2"(默认第一个工作表)。mode=overwrite 覆盖区间内原有的值;mode=append 接在已有数据末尾往下追加(不覆盖)。values 是行 × 列:[[1,"甲"],[2,"乙"]] 表示两行两列。空字符串写空格,null 会留空。只写值,改不了样式、合并单元格、公式(写进去的字符串会被当文本)。
Inputs: range (required), values (required), spreadsheet_token (required), mode.
feishu_update_card原地更新已发出的卡片A
把已发出的卡片整张替换成新内容,聊天里不新增消息气泡 —— 这是"不刷屏"的关键手段。典型用法:先发一张进度卡,之后反复 update 同一个 message_id 推进进度 / 换成结果卡。限制:只有发出时带 config.update_multi = true 的卡片才能更新,否则飞书会报错;也不能更新别人发的消息,只能用自己发出的 message_id。不适合:想让用户看到历史过程的每一步(每次都会覆盖,只留最新一版);需要保留每步记录就用 feishu_send_text 逐条追加。
Inputs: card (required), message_id (required).
feishu_user_lookup查飞书用户ARead-only
用邮箱、手机号或 open_id 查飞书用户,返回 open_id 与名字。使用场景:手上只有同事邮箱/手机号,需要 open_id 才能私聊或 @ 他;或者拿到 open_id 后想确认这人是谁。用法优先级:给了 open_id 就查这一个人的详情(名字、邮箱、手机号最全);否则按 emails / mobiles 批量查(两个都给会各查一次);都不给会直接报错说明用法。重要:查到记录但 open_id 为空,说明该邮箱/手机号不在本企业通讯录(或不在应用可见范围内),这不是 bug,也不能拿它当发送目标。拿到 open_id 后可以直接作为 feishu_send_text 的 target 单聊这个人。前置条件:应用需要通讯录权限(如 contact:user.id:readonly),且用户在应用可见范围内。只读。
Inputs: emails, mobiles, open_id.
feishu_whoami我是谁 / 默认往哪发ARead-only
返回机器人身份(open_id、名字)与当前默认会话配置。在发任何消息之前不确定目标会话时,先调这个。如果 default_chat_id 为空,说明必须先指定 target 才能发送。
Inputs: no named parameters.
feishu_wiki_node查知识库节点ARead-only
知识库节点查询:给 token 就查这个节点(node_token 或 obj_token 都行),给 space_id 而不给 token 就列出该空间的根节点。使用场景:从知识库链接里拿到一段 token,需要知道它对应哪篇文档/哪张表;或者要遍历某个空间有哪些内容。关键点:返回里的 obj_token 才是真正文档/表格的 token——读内容、读表要用 obj_token;node_token 只用于继续在 wiki 里翻节点,传给 feishu_doc_read 会失败。前置条件:应用需被加入该知识库并有 wiki 读权限。只读,不改节点。
Inputs: token, space_id.
feishu_wiki_spaces列知识库空间ARead-only
列出机器人能看到的飞书知识库(wiki)空间,返回 space_id 与名字。使用场景:要按知识库找文档时,先拿空间列表,再用 feishu_wiki_node(传 space_id)列出根节点。前置条件:应用需要被加入知识库(知识库设置 → 成员/应用),否则返回空列表——空列表不代表接口坏了,而是这个应用还没被加入任何知识库,需要在知识库设置里添加此应用。只读,不改知识库结构。
Inputs: limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 43 tools
Descriptions explicitly cross-reference siblings with "不适合…请用 X" guidance, so send_text/send_card/send_info_card/send_file/send_image/reply are mostly separable, as are forward vs merge_forward and doc_read vs doc_blocks. Remaining soft spots: send_info_card vs send_card (one is a label/value convenience wrapper over the other), and doc_read vs doc_blocks both read the same document.
Everything is snake_case with a feishu_ prefix, but the verb/noun ordering and verbs themselves are inconsistent: feishu_send_text and feishu_sheet_create put the action first, feishu_bitable_tables and feishu_doc_read are resource-first, and creation is variously create (sheet/doc/chat) vs add (bitable) vs send (message). Several tools drop the action entirely (feishu_forward, feishu_pin, feishu_whoami, feishu_recent, feishu_ask, feishu_recall), and some multiplex actions via parameters (feishu_reaction, feishu_chat_announcement) while others spawn separate tools.
43 tools is large and heavy for a single MCP server; messaging, chat admin, drive, docs, sheets, bitable, wiki and permissions are all packed in. The breadth is real, but an agent picking from 43 similarly-named feishu_* tools pays a real selection cost, and some near-duplicates (send_card vs send_info_card, sheet_meta vs sheet_read) inflate the count.
Coverage is unusually broad: full CRUD on bitable records, sheet read/write/create/meta, doc read/create/append, drive listing, wiki navigation, chat lifecycle, permissions and reactions. Gaps are acknowledged rather than hidden — no block-level doc editing, no adding/removing members from an existing group, and no message search or message edit.
Maintenance
Related MCP Connectors
Group chat for AI agents: 15 tools for messages, replies, approvals, joining and agent email.
Let your AI agents hand work to each other, share files, and use apps you approve.
The agent-native cloud: database, functions, AI, storage, computers. 53 tools. OAuth or API key.
Build and run agents and automations across hundreds of apps using natural language.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceA toolkit that enables AI assistants to directly call Feishu/Lark API interfaces for automation scenarios like document processing, conversation management, and calendar scheduling.867MIT- -licenseNot gradedqualityNot gradedmaintenanceA tool designed to help users connect AI Agents with the Feishu/Lark platform, encapsulating Feishu/Lark Open Platform API interfaces as MCP tools for document processing, conversation management, calendar scheduling and more.33,913 npm-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with Feishu/Lark platform APIs for automation scenarios including message management, document operations, calendar scheduling, group management, and Bitable operations through natural language.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control Feishu (Lark) through structured tools for messaging, calendar, tasks, and documents.3MIT