feishu-user-plugin

License: MIT Node.js MCP Tools npm PRs Welcome

飞书 / Lark MCP 服务器，覆盖 IM、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、实时事件。84 tools · 3 auth layers · 9 MCP prompts · MIT licensed · Node ≥18。

兼容 Claude Code、Codex、Cursor、Windsurf、VS Code、Claude Desktop、OpenClaw 等 MCP 客户端。

与其他飞书 MCP 的区别：基于 cookie + protobuf 协议路径，支持以用户本人身份发消息——飞书官方开放 API 没有 send_as_user 权限点，机器人 token 发出的消息一律标 sender_type: "app"。

三层鉴权

鉴权层	凭证	覆盖能力	工具数
用户身份（cookie + protobuf）	`LARK_COOKIE`	以用户身份发文本 / 图片 / 文件 / 富文本 / @ / 批量	8
官方 API（机器人）	`LARK_APP_ID` + `LARK_APP_SECRET`	群消息读写、文档、多维表格、知识库、云空间、日历、任务 v2、OKR、联系人、实时事件 WS	70+
用户 OAuth UAT	`LARK_USER_ACCESS_TOKEN` + `LARK_USER_REFRESH_TOKEN`	P2P 私聊读取、用户 chat 列表；写入文档 / Bitable / 日历资源时以用户为 owner	2 显式 + 全工具 UAT-first

三层独立 —— 配置任意一层，对应工具可用。

安装

npx feishu-user-plugin setup --app-id <APP_ID> --app-secret <APP_SECRET>
npx feishu-user-plugin oauth         # 拿用户 OAuth UAT
# 重启 Claude Code / Codex

cookie 获取：跟 Claude Code 说一句"帮我设置飞书 cookie"会自动经 Playwright 扫码登录抓取；手动方式在 feishu.cn DevTools Network 标签从请求头 Cookie 整行复制（不要用 document.cookie 或 Application > Cookies 标签—— HttpOnly 的 session / sl_session 拿不到）。

没有 APP_ID / SECRET 见下面创建飞书应用。

用法

你：帮我以我身份给王小明发：今天的代码 review 我看完了，有 3 个 nit
Claude：[调用 send_to_user]  Sent

你：总结"工程组"群今天 9 点之后的讨论，发个日报到 #日报频道
Claude：[read_messages → 总结 → send_to_group]  Sent

创建飞书应用

LARK_APP_ID / LARK_APP_SECRET 是用 Official API（70+ 工具）的前置条件：

飞书开放平台登录 → 创建自建应用（不能选商店应用 / 第三方应用，否则 P2P 读取会被锁）
添加应用能力 → 启用机器人
权限管理 → 添加 scope：
- 消息：im:message、im:message:readonly、im:chat:readonly
- 文档：docx:document、bitable:record、wiki:wiki:readonly、drive:drive:readonly
- 联系人：contact:user.base:readonly
- 按需：okr:okr:readonly、calendar:calendar:readonly、task:task、drive:drive、docs:document.media:upload、wiki:wiki 等
凭证与基础信息 → 复制 App ID（cli_xxx）+ App Secret
创建版本 → 提交审核 → 管理员审批
把 bot 加到要读消息的群里

工具索引（84 个）

完整工具列表 + 参数 + 跨域注意事项见 CLAUDE.md。

工具	说明
`send_to_user`	按名搜用户 + 发文本，一步完成
`send_to_group`	按名搜群 + 发文本，一步完成
`send_as_user`	按 chat ID 发文本，支持回复线程（`root_id` / `parent_id`）
`send_image_as_user`	以用户身份发图（v1.3.9）
`send_file_as_user`	以用户身份发文件（需先 `upload_file`）
`send_post_as_user`	富文本：标题 + 段落 + @ + 超链
`send_card_as_user`	飞书交互卡片（机器人通道；cookie 通道服务端关闭，仅 bot 路径可用）
`batch_send`	一次发多条到不同 chat（text / image / file / post）

用户身份 —— 联系人 / 信息（cookie，5 个）

工具	说明
`search_contacts`	搜用户 / bot / 群
`create_p2p_chat`	创建或获取 P2P chat
`get_chat_info`	群详情（接受 `oc_xxx` 或 numeric）
`get_user_info`	用户名 / 头像查询
`get_login_status`	三层鉴权健康检查（实际跑一次 UAT 调用，不只看配置）

用户 OAuth UAT —— P2P 读取（2 个）

工具	说明
`read_p2p_messages`	读私聊历史（外部群自动 fallback）
`list_user_chats`	用户加入的所有群（仅群，不含 P2P；P2P 用 `search_contacts` → `create_p2p_chat`）

官方 API —— IM（15 个）

工具	说明
`list_chats`	列 bot 加入的所有 chat
`read_messages`	读群消息（接受 chat 名 / `oc_xxx` / numeric；外部群自动 UAT fallback；merge_forward 自动展开）
`send_message_as_bot`	机器人发消息
`reply_message`	机器人回复
`forward_message`	转发到其他 chat（自动识别 receive_id_type）
`delete_message`	撤回 / 删除 bot 消息
`update_message`	编辑已发消息（仅支持 text / interactive）
`add_reaction` / `delete_reaction`	表情回应
`pin_message`	置顶
`create_group` / `update_group`	建群 / 改群
`list_members` / `manage_members`	群成员 list / add / remove（注意 `member_id_type` 与 ID 类型匹配）
`download_message_resource`	下载消息附件（image / file，> 2 MiB 必须 `save_path`）

官方 API —— 文档（7 个）

工具	说明
`search_docs`	关键词搜文档
`read_doc`	结构化 JSON
`read_doc_markdown`	v1.3.9 直接返回 markdown，~60% token 节省（适合 RAG / 总结）
`get_doc_blocks`	块树
`create_doc`	创建文档（可选 `wiki_space_id` 直接落知识库）
`manage_doc_block`	块 create / update / delete（image_path / file_path / image_token / file_token 快捷）
`download_doc_image`	下载文档内嵌图片

官方 API —— 多维表格 Bitable（6 个，v1.3.7 整合）

工具	actions	说明
`manage_bitable_app`	create / copy / get_meta	应用级（创建可指定 `wiki_space_id` 直接落 Wiki）
`manage_bitable_table`	list / create / update / delete	数据表 CRUD
`manage_bitable_field`	list / create / update / delete	字段（update 必须传 `type` 即使只改名）
`manage_bitable_view`	list / create / delete	视图（grid / kanban / gallery / form / gantt / calendar）
`manage_bitable_record`	search / get / create / update / delete	记录 CRUD（数组：单条或最多 500）
`upload_bitable_attachment`	—	上传附件，返回 `file_token`

官方 API —— 知识库 Wiki（9 个）

工具	说明
`list_wiki_spaces`	列空间（UAT-first）
`search_wiki`	搜知识库
`list_wiki_nodes`	列节点
`get_wiki_node`	节点 → obj_token 解析（接受 wiki node token 或 obj_token）
`create_wiki_node`	创建节点（doc / sheet / bitable / mindnote / file / docx / slides）
`update_wiki_node`	改名（内容编辑用 docx / bitable 工具）
`move_wiki_node`	移动
`copy_wiki_node`	深拷贝
`delete_wiki_node`	删除 wiki 节点指针（底层 drive 资源用 `manage_drive_file(action=delete)` 删）

官方 API —— 云空间 Drive（5 个）

工具	说明
`list_files`	列文件夹内文件
`create_folder`	建文件夹
`manage_drive_file`	copy / move / delete（必须传 `type`）
`upload_image` / `upload_file`	上传图片 / 文件，返回 key
`upload_drive_file`	上传到 Drive 文件夹（可选 `wiki_space_id` 直接挂 Wiki 节点）

官方 API —— OKR（6 个）

工具	说明
`list_user_okrs`	列指定用户的 OKR（必须传 user_id）
`get_okrs`	批量取详情（objectives + key results + progress + alignments）
`list_okr_periods`	列周期（季度 / 年度）
`create_okr_progress_record`	添加进展记录（v1.3.7，需 `okr:okr.content:write`）
`list_okr_progress_records`	列进展记录（从 `get_okrs` 提取 triples）
`delete_okr_progress_record`	删进展记录

官方 API —— 日历（8 个，写入 v1.3.7）

工具	说明
`list_calendars`	列日历（primary + 共享 + 订阅）
`list_calendar_events`	列事件（指定时间窗）
`get_calendar_event`	事件详情（参与人 / 地点 / 会议链接 / 附件）
`create_calendar_event`	建事件（需 `calendar:calendar.event:write`）
`update_calendar_event`	改事件
`delete_calendar_event`	删事件（可选 `meeting_chat_id` 同时解散关联会议群）
`respond_calendar_event`	RSVP（accept / decline / tentative）
`get_freebusy`	多人 freebusy 查询

官方 API —— 任务 v2（7 个，v1.3.7 新域）

标识符是 task_guid（不是 v1 的 numeric task_id），需 task:task scope。

工具	说明
`list_tasks`	列当前用户任务
`get_task`	详情
`create_task`	建任务（summary 必填）
`update_task`	改任务（必传 `update_fields=[...]`，飞书只 patch 列出字段）
`complete_task`	完成 / 取消完成
`delete_task`	删
`manage_task_members`	add / remove 成员（assignee / follower）

插件层 —— 诊断与多账号（4 个）

工具	说明
`get_login_status`	三层鉴权健康检查
`list_profiles`	列可用 profile（默认 + LARK_PROFILES_JSON / credentials.json）
`switch_profile`	切 profile（缓存的 client 实例下次调用重建）
`manage_profile_hints`	查 / 改 / 清自动切换缓存（list / set / clear）

插件层 —— 实时事件（2 个，v1.3.9）

工具	说明
`get_new_events`	拉取增量事件（peek=true 不推进 cursor；filter by event_type / chat_id / since_seconds / profile）
`manage_ws_status`	info / reconnect / claim / rotate / reconfig（诊断 / 重连 / 抢锁 / 强制 events.jsonl 轮转 / 不重启重新订阅）

9 个 MCP prompts（slash commands）

Prompt	说明
`/send`	以用户身份发消息
`/reply`	读最近消息然后回
`/digest`	群 / P2P 最近消息总结
`/search`	搜联系人 / 群
`/doc`	搜 / 读 / 建文档
`/table`	操作多维表格
`/wiki`	搜知识库
`/drive`	列云空间 / 建文件夹
`/status`	检查三层鉴权状态

客户端配置

环境变量配置一致，配置文件路径和顶层键不同。

统一 env 块：

{
  "command": "npx",
  "args": ["-y", "feishu-user-plugin"],
  "env": {
    "LARK_COOKIE": "your-cookie-string",
    "LARK_APP_ID": "cli_xxxxxxxxxxxx",
    "LARK_APP_SECRET": "your-app-secret",
    "LARK_USER_ACCESS_TOKEN": "your-uat",
    "LARK_USER_REFRESH_TOKEN": "your-refresh-token"
  }
}

安放位置：

客户端	配置文件	顶层键
Claude Code	`~/.claude.json`（推荐全局） / `.mcp.json`	`mcpServers.feishu-user-plugin`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)	`mcpServers.feishu`
Codex	`~/.codex/config.toml`	`[mcp_servers.feishu-user-plugin]`（TOML）
Cursor	`.cursor/mcp.json`（项目级）	`mcpServers.feishu`
VS Code (Copilot)	`.vscode/mcp.json`	`servers.feishu`（注意是 `servers`，不是 `mcpServers`）
OpenClaw	`~/.openclaw/openclaw.json`	`mcp.servers.feishu-user-plugin`
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers.feishu`

自动化设置：

npx feishu-user-plugin setup                       # 默认写 Claude Code (~/.claude.json)
npx feishu-user-plugin setup --client codex        # Codex (~/.codex/config.toml)
npx feishu-user-plugin setup --client both         # Claude Code + Codex 都写
npx feishu-user-plugin setup --activate            # 激活当前 profile

各客户端完整 JSON 模板见 README.en.md MCP Client Configuration 段。

多账号（v1.3.8 / v1.3.9）

~/.feishu-user-plugin/credentials.json 支持多 profile（默认 + 任意附加），单台机器一处配置覆盖多个飞书账号 / 多个企业。

npx feishu-user-plugin list-profiles
npx feishu-user-plugin switch-profile <name>
npx feishu-user-plugin keepalive --all       # 跨 profile keepalive

读路径工具（read_* / list_* / get_* / search_* / download_*）失败码 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 时自动跨 profile retry。写路径不自动切（避免错号创建资源）。

单调用覆盖：传 via_profile: "<name>" 钉到指定 profile，传 via_profile: "auto" 给写路径开自动切换。

详见 CLAUDE.md "Multi-profile auto-switch" 段。

实时事件（v1.3.9 机器级 SSOT）

机器上单进程持有 WS owner 锁（~/.feishu-user-plugin/ws-owner.lock，O_CREAT|O_EXCL，30s stale），所有 MCP 进程共享 ~/.feishu-user-plugin/events.jsonl（10 MB 软 / 20 MB 硬限自动轮转），events.cursor.json 是全机所有 harness 共享的 drain cursor —— 每条事件全机恰好一次。

mcp call manage_ws_status --action info        # 谁在持锁、当前订阅、events.jsonl 大小
mcp call manage_ws_status --action claim --force true   # 跨进程抢锁

默认订阅 ["im.message.receive_v1"]。要订阅其他事件（审批 / 日历 / vc / etc），编辑 credentials.json::profiles[<active>].events，然后 manage_ws_status(action=reconfig) 不重启重新订阅。

仅支持 feishu.cn —— Lark 国际版（lark.com）的 WSClient 当前不支持。

工程细节

Token 生命周期

鉴权层	Token	有效期	续期
Cookie	`sl_session`	12h max-age	4h 心跳自动刷新
App	`tenant_access_token`	2h	SDK 自动管理
User OAuth	`user_access_token`	~2h	refresh_token 自动刷新，写回 credentials.json
Refresh Token	—	7 天	`keepalive` cron 防过期

crontab -e
# 0 */4 * * * npx feishu-user-plugin keepalive >> /tmp/feishu-keepalive.log 2>&1

UAT 刷新失败 invalid_grant —— refresh token 过期 / 被撤销，重跑 npx feishu-user-plugin oauth 然后重启 Claude Code / Codex。

凭证存储（v1.3.7+）

单一可信源 ~/.feishu-user-plugin/credentials.json（mode 0600），多 harness 共享。schema 见 docs/CREDENTIALS-FORMAT.md。

npx feishu-user-plugin migrate              # dry-run
npx feishu-user-plugin migrate --confirm    # 真写

自动 sync hooks

阶段	触发文件	作用
pre-commit	`CLAUDE.md` staged	同步到 `AGENTS.md` + skill 引用
pre-commit	`package.json` / `plugin.json` / `SKILL.md` staged	三角等价检查（version 必须一致）
pre-commit	`src/server.js` / `src/tools/*` staged	工具个数 + README 84 tools 徽章必须一致
pre-commit	`src/*` staged	smoke test
post-merge (main)	任意	自动开 team-skills sync PR

CI（.github/workflows/validate.yml）每个 PR 跑同样的 gate。

已知限制

Cookie 寿命：12-24 小时无心跳过期，需重新登录 feishu.cn 拿 cookie
协议变化：cookie + protobuf 层依赖飞书 web 客户端的协议，飞书更新可能失效（机器人能力不受影响）
卡片：cookie 通道发卡片服务端不可用，机器人通道可发
Lark 国际版：实时事件 WS 不支持
未实现：search_messages（v1.3.10 计划）、md → wiki 同步（v1.3.10 主线）

完整 ROADMAP 见 ROADMAP.md。

贡献

Issues / PR 欢迎。提交前先看 CONTRIBUTING.md。

飞书改协议导致功能挂掉 —— 开 issue 带错误日志即可。

License

MIT

致谢

cv-cat/LarkAgentX —— 早期飞书 web 协议研究（Python）
cv-cat/OpenFeiShuApis —— 底层 API 研究
Model Context Protocol —— MCP 标准 + Anthropic / PulseMCP / GitHub / Stacklok 共维 registry

feishu-user-plugin

feishu-user-plugin

三层鉴权

安装

用法

创建飞书应用

工具索引（84 个）

用户身份 —— 联系人 / 信息（cookie，5 个）

用户 OAuth UAT —— P2P 读取（2 个）

官方 API —— IM（15 个）

官方 API —— 文档（7 个）

官方 API —— 多维表格 Bitable（6 个，v1.3.7 整合）

官方 API —— 知识库 Wiki（9 个）

官方 API —— 云空间 Drive（5 个）

官方 API —— OKR（6 个）

官方 API —— 日历（8 个，写入 v1.3.7）

官方 API —— 任务 v2（7 个，v1.3.7 新域）

插件层 —— 诊断与多账号（4 个）

插件层 —— 实时事件（2 个，v1.3.9）

9 个 MCP prompts（slash commands）

客户端配置

多账号（v1.3.8 / v1.3.9）

实时事件（v1.3.9 机器级 SSOT）

工程细节

Token 生命周期

凭证存储（v1.3.7+）

自动 sync hooks

已知限制

贡献

License

致谢

Resources

Tools

Latest Blog Posts

MCP directory API

feishu-user-plugin

三层鉴权

安装

用法

创建飞书应用

工具索引（84 个）

用户身份 —— 消息（cookie protobuf，8 个）

用户身份 —— 联系人 / 信息（cookie，5 个）

用户 OAuth UAT —— P2P 读取（2 个）

官方 API —— IM（15 个）

官方 API —— 文档（7 个）

官方 API —— 多维表格 Bitable（6 个，v1.3.7 整合）

官方 API —— 知识库 Wiki（9 个）

官方 API —— 云空间 Drive（5 个）

官方 API —— OKR（6 个）

官方 API —— 日历（8 个，写入 v1.3.7）

官方 API —— 任务 v2（7 个，v1.3.7 新域）

插件层 —— 诊断与多账号（4 个）

插件层 —— 实时事件（2 个，v1.3.9）

9 个 MCP prompts（slash commands）

客户端配置

多账号（v1.3.8 / v1.3.9）

实时事件（v1.3.9 机器级 SSOT）

工程细节

Token 生命周期

凭证存储（v1.3.7+）

自动 sync hooks

已知限制

贡献

License

致谢

Resources

Tools

Latest Blog Posts

MCP directory API