Skip to main content
Glama
deenesjakoruzh
EthanQC

feishu-user-plugin

by EthanQC
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

feishu-user-plugin

License: MIT Node.js MCP Tools npm PRs Welcome

中文 · 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"。

三层鉴权

鉴权层

凭证

覆盖能力

工具数

用户身份（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

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

Related MCP server: lark-hermes-mcp

安装

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 个）

工具

说明

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

致谢

Install Server
A
license - permissive license
B
quality
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
2dResponse time
–Release cycle
1Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

  • Feishu/Lark OpenAPI MCP

    KAIpany
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A 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.
    7,855

  • lark-hermes-mcp

    WilliamMo101
    A
    license
    B
    quality
    F
    maintenance
    An MCP server that exposes Feishu/Lark capabilities as function tools to MCP-compatible agents like Hermes and Claude Desktop. It provides 57 tools for messaging, document management, calendar operations, and task management through both hand-written fallback tools and bridged OpenClaw SDK functionality.
    53
    1
    MIT

  • reasonix-feishu-mcp

    Monc618
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server for Feishu/Lark API integration, enabling AI agents to send messages, manage groups, create and edit documents and spreadsheets, and search knowledge bases.
    MIT

View all related MCP servers

Related MCP Connectors

  • RogerRat

    Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.

  • Banco MCP

    Brazilian Open Finance MCP — 30+ banks (Itaú, Nubank, etc.) to Claude/Cursor. Read-only.

  • better-notion-mcp

    Markdown-first MCP server for Notion API with 8 composite tools and 39 actions.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/EthanQC/feishu-user-plugin'

If you have feedback or need assistance with the MCP directory API, please join our Discord server