feishu-user-plugin

feishu-user-plugin

中文 · English · Docs · CHANGELOG · npm

飞书 / 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"。

三层鉴权

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

安装

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+ 工具）的前置条件：

1. 飞书开放平台 登录 → 创建自建应用（不能选商店应用 / 第三方应用，否则 P2P 读取会被锁）
2. 添加应用能力 → 启用机器人
3. 权限管理 → 添加 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 等
4. 凭证与基础信息 → 复制 App ID（cli_xxx）+ App Secret
5. 创建版本 → 提交审核 → 管理员审批
6. 把 bot 加到要读消息的群里

工具索引（84 个）

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

用户身份 —— 消息（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 新域）

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

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

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

9 个 MCP prompts（slash commands）

客户端配置

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

统一 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"
  }
}

安放位置：

自动化设置：

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 生命周期

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

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