Feishu User Plugin

io.github.zhuzhen-teamPublished by GitHub account zhuzhen-teamv1.4.1Updated Oct 24, 2026

Feishu/Lark MCP server + CLI tool. 85 tools, 3 auth layers. Send as user via cookie+protobuf.

VerifiedSTDIODesktop onlyProductivity & WorkflowFiles & StorageCommunication & Collaboration

Overview

AI-generated overview

Local Feishu/Lark MCP server and CLI with 85 tools that let an assistant send messages as you, read chats, and work with docs, bitable, wiki, drive, calendar…

What you can do
  • Send messages as the user: text, rich-text post, image, file, card and batch sends, plus group and P2P reading with forwarded-message expansion and link extraction
  • Work with documents: read Feishu docs as markdown, create and edit docs, operate bitable records in batches, and manage wiki and drive files
  • Handle collaboration: read and write calendars, manage tasks v2 including members, read OKR and record progress, and look up contacts
  • Receive real-time events through a machine-level WebSocket with exactly-once delivery per event
  • Diagnose and switch between multiple account profiles, with automatic read-path retry across profiles
When to use it
Useful when you want an assistant to act inside Feishu/Lark from an MCP client such as Claude Code, Codex, Cursor, VS Code or Windsurf: sending messages under your own identity, summarizing group or private chats, or reading and editing docs, tables, wiki, calendar and tasks. It is aimed at personal developers or people without admin rights who want user-identity messaging without an approved OAuth scope.
Requirements
Runs locally as an npm package (Node 18 or newer) over stdio, on desktop clients only. Feishu self-built app credentials LARK_APP_ID and LARK_APP_SECRET are needed for most tools; LARK_COOKIE is needed for user-identity sending; LARK_USER_ACCESS_TOKEN and LARK_USER_REFRESH_TOKEN come from the plugin's OAuth command. Only feishu.cn is supported; Lark international is not.
Before you install
The server asks for a Feishu web session cookie (LARK_COOKIE) and app secret (LARK_APP_SECRET), which are powerful credentials; the cookie path relies on the web client's private protocol and may break when Feishu changes it, and cookies expire in roughly 12-24 hours. Tools send messages, create and edit docs, tables, wiki pages, calendar entries and tasks under your identity, so mistakes reach real colleagues. Credentials are stored in a local credentials file.

Installation

In SourceWeft

  1. Open Feishu User Plugin in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

feishu-user-plugin —— 飞书 MCP 服务器 + CLI 工具

[License: MIT] [Node.js] [MCP] [Tools] [npm] [PRs Welcome]

中文 · English · Docs · CHANGELOG · npm

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

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

用户身份发消息有两条路径：飞书官方 OAuth scope im:message.send_as_user（需要创建自建应用 + 管理员审批），或本仓的 cookie + protobuf 路径（cookie 抓出来就跑）。本仓不再是物理性独家，但仍然是"个人开发者 / 没有管理员权限 / 想快速试用户身份发消息"场景的简便选项。

⚠ 注意限定范围：cookie 路径"零应用门槛"只对纯文本 / post 类用户身份发消息严格成立：send_to_user / send_to_group / send_as_user / send_post_as_user / batch_send（text/post 模式）5 个工具。send_image_as_user / send_file_as_user 的发送本身走 cookie，但 image_key / file_key 必须先经 Official API（upload_image / upload_file）上传；send_card_as_user 服务端禁了 cookie 通道，始终走 bot。本仓其他能力（读群消息、操作文档 / 表格 / 知识库 / 云空间 / 日历 / 任务 / OKR / 实时事件等）也仍然需要创建飞书自建应用（LARK_APP_ID + LARK_APP_SECRET），跟官方 MCP / CLI 完全一样。

与官方对比（飞书 2026 年也发了 MCP + CLI）

  • larksuite/lark-openapi-mcp —— 官方 OpenAPI MCP，⚠ Beta + 最后更新 2025-08（9 个月前），README 明文不支持文件上传下载、不支持文档编辑；1271 个 endpoint 工具但 preset.default 仅 ~20，其余"未做兼容性测试"
  • larksuite/cli —— 官方 CLI（9.9k stars，活跃），17 业务域 200+ commands + 24 AI Agent Skills，已支持 +messages-send --as user（走 OAuth scope im:message.send_as_user），但 CLI 形态而不是 MCP，Codex / Cursor / Windsurf 等用它要 shell out

什么时候用本仓：

  • 想以用户身份发消息 / 读 P2P 私聊但不想 / 不能创建飞书自建应用（个人开发者 / 没管理员权限）—— cookie 路径零门槛
  • 用 MCP 协议（Codex / Cursor / Windsurf / VS Code 等）+ 不需要邮件 / 审批 / HR / 会议纪要等本仓未覆盖的域
  • 多 MCP 客户端共存且需要"实时事件全机精确投递一次"（v1.3.9+ 机器级 WS SSOT）

什么时候用官方：需要邮件 / 审批 / 考勤 / HR / 招聘 / 会议纪要等业务系统域；或已有飞书应用 + 管理员批了 OAuth scope，偏好官方长期稳定路径。

完整诚实对比见 docs/COMPARISON.md。

用法

你：帮我以我身份给王小明发：今天的代码 review 我看完了，有 3 个 nitClaude：[调用 send_to_user]  Sent
你：总结"工程组"群今天 9 点之后的讨论，发个日报到 #日报频道Claude：[read_messages → 总结 → send_to_group]  Sent

安装

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

cookie 获取（Playwright 自动扫码 / DevTools 手动）、创建飞书应用、各客户端配置详见 docs/AUTH-SETUP.md。

三层鉴权

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

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

核心能力

  • 以你身份发消息（8）：text / image / file / 富文本 post / 卡片 / 批量；差异化锚点 —— 飞书官方 API 没有 send_as_user
  • 读群与 P2P 私聊（17）：群消息 / 私聊 / merge_forward 自动展开 / URL + 飞书文档链接自动提取 / 外部群自动 fallback 到 UAT
  • 文档生态（27）：飞书文档（含 read_doc_markdown 省 ~60% token）/ 多维表格（500 条批量）/ 知识库（含 write CRUD）/ 云空间
  • 协作工具（21）：日历（读+写）/ 任务 v2（含成员管理）/ OKR（读+进展记录）/ 联系人
  • 实时事件（2）：机器级 SSOT WS，每条事件全机精确投递一次
  • 诊断与多账号（4）：N 个 profile 自动切换，写路径不切（避免错号建资源）

完整工具列表 + 跨域 caveat + 用法 patterns 见 docs/TOOLS.md。

9 个 MCP prompts（slash commands）

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

客户端配置

环境变量统一，配置文件位置和顶层键不同：

客户端配置文件顶层键
Claude Code~/.claude.json（推荐全局）/ .mcp.jsonmcpServers.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]
Cursor.cursor/mcp.json（项目级）mcpServers.feishu
VS Code (Copilot).vscode/mcp.jsonservers.feishu（注意 servers，非 mcpServers）
OpenClaw~/.openclaw/openclaw.jsonmcp.servers.feishu-user-plugin
Windsurf~/.codeium/windsurf/mcp_config.jsonmcpServers.feishu
bash
npx feishu-user-plugin setup                       # Claude Codenpx feishu-user-plugin setup --client codex        # Codexnpx feishu-user-plugin setup --client both         # 都写

各客户端完整 JSON 模板见 README.en.md MCP Client Configuration；详细安装与凭证流程见 docs/AUTH-SETUP.md。

多账号

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

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

读路径工具失败码 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 时自动跨 profile retry。写路径不自动切（避免错号创建资源）。单调用覆盖：传 via_profile: "<name>" 钉到指定 profile。

详见 docs/TOOLS.md "多 profile auto-switch"。

实时事件

机器上单进程持有 WS owner 锁，所有 MCP 进程共享 events.jsonl，每条事件全机恰好一次。

bash
mcp call manage_ws_status --action infomcp call manage_ws_status --action claim --force true

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

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

已知限制

  • Cookie 寿命：12-24 小时无心跳过期，需重新登录 feishu.cn 拿 cookie
  • 协议变化：cookie + protobuf 层依赖飞书 web 客户端的协议，飞书更新可能失效（机器人能力不受影响）
  • 卡片：cookie 通道发卡片服务端不可用，机器人通道可发
  • Lark 国际版：实时事件 WS 不支持
  • 已删除：md → wiki 双向同步（飞书 wiki block schema 离散度高，无损往返不现实）、Mermaid → 飞书画板（依赖 wiki 主线一并删）。详见 ROADMAP.md 的"已删除"段

文档

文档角色
docs/TOOLS.md工具详细 + 跨域 caveat + 用法 patterns
docs/AUTH-SETUP.md安装 / 三层鉴权 / Cookie 抓取 / OAuth Scopes
docs/TROUBLESHOOTING.md错误码与诊断
docs/RELEASING.md发版流程 + team-skills 同步 + 公告规则
docs/REFACTOR-NOTES.md文件职责矩阵
docs/CREDENTIALS-FORMAT.md凭证 schema
docs/TESTING-METHODOLOGY.md测试方法
CONTRIBUTING.md贡献流程（中英双语）
ROADMAP.md路线图（forward-only）
CHANGELOG.md历史变更

完整 docs/ 索引：docs/README.md。

贡献

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

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

隐私 / Privacy

本地运行的 MCP 服务器，凭证留在用户本机，不上报遥测，不与插件作者后台通信。完整文本见 PRIVACY.md。

  • 收集：插件本身不收集任何数据；LARK_COOKIE / LARK_APP_ID / LARK_APP_SECRET / LARK_USER_ACCESS_TOKEN / LARK_USER_REFRESH_TOKEN 全部由用户主动配置，来源于用户自己的飞书 / Lark 账号
  • 处理：仅处理用户通过 MCP 工具调用主动请求的消息 / 文档 / 多维表格 / 知识库 / 云空间 / 日历 / 任务 / OKR / 联系人，不留存、不分析
  • 存储：~/.feishu-user-plugin/credentials.json（mode 0600）；可选事件日志 ~/.feishu-user-plugin/events.jsonl（10 MB / 20 MB 自动轮转）
  • 第三方：仅与用户自己的飞书租户和用户运行的 AI 客户端通信，无 CDN / 分析 / 错误上报
  • 保留：完全用户控制；rm -rf ~/.feishu-user-plugin && npm uninstall -g feishu-user-plugin 即清空
  • 联系：GitHub Issues，安全问题在 issue 标题前加 [security]

A locally-run MCP server. Credentials stay on the user's machine; no telemetry, no phone-home. Full text at PRIVACY.md.

  • Collected: nothing by the plugin itself; the five LARK_* envs are supplied by the user from their own Feishu / Lark account
  • Processed: only the messages / docs / bitable / wiki / drive / calendar / tasks / OKR / contacts the user explicitly requests via MCP tool calls
  • Stored: ~/.feishu-user-plugin/credentials.json (mode 0600); optional event log at ~/.feishu-user-plugin/events.jsonl
  • Third-party: only the user's own Feishu tenant and the AI client the user runs (Claude Code / Codex / Cursor / etc.)
  • Retention: entirely user-controlled; rm -rf ~/.feishu-user-plugin && npm uninstall -g feishu-user-plugin removes everything
  • Contact: GitHub Issues; security disclosures with [security] prefix in the title

License

MIT

致谢

Source: README.md at commit 171e92f

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v1.4.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts