EthanQC/feishu-user-plugin

**中文** · 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。
用法
安装
cookie 获取（Playwright 自动扫码 / DevTools 手动）、创建飞书应用、各客户端配置详见 docs/AUTH-SETUP.md。
三层鉴权
| 鉴权层 | 凭证 | 覆盖能力 | 工具数 |
|---|---|---|---|
| 用户身份（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 |
三层独立 —— 配置任意一层，对应工具可用。
核心能力
- **以你身份发消息**（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.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] |
| Cursor | .cursor/mcp.json（项目级） | mcpServers.feishu |
| VS Code (Copilot) | .vscode/mcp.json | servers.feishu（注意 servers，非 mcpServers） |