feishu-user-plugin

Purpose

feishu-user-plugin is a Feishu / Lark MCP server + CLI tool, with the goal of letting Claude Code, Codex, scripts, etc. directly take over Feishu workflows. It is officially positioned as covering IM, Docs, Bitable, Wiki, Drive, Calendar, Tasks v2, OKR, and real-time events, providing about 85 tools, 3 layers of authentication, 9 MCP prompts, MIT license, and requiring Node ≥18.

Compatible with MCP clients such as Claude Code, Codex, Cursor, Windsurf, VS Code, Claude Desktop, and OpenClaw.

Main capabilities

Send messages as the user themselves (8): text / image / file / rich-text post / card / batch. According to official materials, there are two paths for sending messages as a user: the official Feishu OAuth scope im:message.send_as_user(requires creating a custom app + admin approval), or this repo's cookie + protobuf path (it runs once the cookie is extracted).

Read groups and P2P private chats (17): group messages / private chats / automatic merge_forward expansion / automatic extraction of URLs and Feishu document links / automatic fallback to UAT for external groups.

Document ecosystem (27): Feishu Docs (including read_doc_markdown, officially claimed to save about 60% tokens) / Bitable (batch of 500) / Wiki (including write CRUD) / Drive.

Collaboration tools (21): Calendar (read + write) / Tasks v2 (including member management) / OKR (read + progress records) / Contacts.

Real-time events (2): machine-level SSOT WS, each event delivered exactly once across the whole machine.

Diagnostics and multi-account (4): automatic switching across N profiles, write paths do not switch (to avoid creating resources under the wrong account).

There are also 9 MCP prompts (slash commands).

Usage and authentication

The three layers of authentication are mutually independent — configure any one layer and the corresponding tools become available.

• cookie path: official materials clearly define the scope — the "zero app barrier" strictly holds only for plain text / post-type messages sent as the user, namely send_to_user / send_to_group / send_as_user / send_post_as_user / batch_send(text/post mode) 5 tools.send_image_as_user / send_file_as_user sending itself goes through cookie, but image_key / file_key must first be uploaded via the Official API (upload_image / upload_file);send_card_as_user the server has disabled the cookie channel and always goes through bot.
• Official API: other capabilities in this repo (reading group messages, operating Docs / Sheets / Wiki / Drive / Calendar / Tasks / OKR / real-time events, etc.) still require creating a Feishu custom app (LARK_APP_ID + LARK_APP_SECRET).
• OAuth: corresponds to the official im:message.send_as_user scope path.

Cookie acquisition methods include Playwright automatic QR code scanning or manual DevTools; for creating a Feishu app and configuring each client, see its docs/AUTH-SETUP.md.

Multi-account:~/.feishu-user-plugin/credentials.json supports multiple profiles; one configuration on a single machine can cover multiple Feishu accounts / multiple enterprises. Read-path tools automatically retry across profiles on failure codes 91403 / 1254301 / 1254000 / 99991672 / HTTP 403; write paths do not switch automatically, to avoid creating resources under the wrong account; a single call can use via_profile: "<name>" to pin to a specified profile.

Real-time events: a single process on the machine holds the WS owner lock, all MCP processes share events.jsonl, and each event occurs exactly once across the whole machine. By default it subscribes to ["im.message.receive_v1"]; to subscribe to other events such as approvals / calendar / vc, you need to edit credentials.json::profiles[<active>].events, then use manage_ws_status(action=reconfig) Resubscribe without restarting.

Applicable scenarios

According to the official documentation, the applicable scenarios include: sending messages as a user, reading P2P private chats but not wanting or being able to create a Feishu custom app (individual developers / those without admin permissions); using the MCP protocol (Codex / Cursor / Windsurf / VS Code, etc.) and not needing domains not covered by this repository such as email / approval / HR / meeting minutes; multiple MCP clients coexisting and requiring "real-time events delivered exactly once across the entire machine." When business system domains such as email / approval / attendance / HR / recruiting / meeting minutes are needed, or when there is already a Feishu app + an admin has approved the OAuth scope and the official long-term stable path is preferred, the official recommendation is to use the official solution.

Limitations

• Only feishu.cn is supported — the WSClient of Lark International (lark.com) is currently not supported, and real-time event WS does not support Lark International.
• Cookie lifetime: expires after 12–24 hours without a heartbeat, requiring logging in to feishu.cn again to obtain a cookie.
• Protocol changes: the cookie + protobuf layer depends on the Feishu web client protocol, and Feishu updates may cause it to stop working (bot capabilities are unaffected).
• Cards: sending cards via the cookie channel is unavailable on the server side, while the bot channel can send them.
• Removed: md → wiki bidirectional sync, Mermaid → Feishu whiteboard; see the "Removed" section of ROADMAP.md for official details.
• The official larksuite/lark-openapi-mcp is described as Beta and last updated 2025-08; the README explicitly states that file upload/download and document editing are not supported; the official CLI already supports messages-send --as user, but in CLI form rather than MCP.

Privacy

The official documentation states that this plugin is a locally running MCP server, credentials remain on the user's local machine, no telemetry is reported, and there is no communication with the plugin author's backend. The plugin itself does not collect any data;LARK_COOKIE / LARK_APP_ID / LARK_APP_SECRET / LARK_USER_ACCESS_TOKEN / LARK_USER_REFRESH_TOKEN is entirely configured by the user, sourced from the user's own Feishu / Lark account. It only processes data actively requested by the user through MCP tool calls, and does not retain or analyze it. Credentials are stored in ~/.feishu-user-plugin/credentials.json(mode 0600), with optional event logs ~/.feishu-user-plugin/events.jsonl(automatic rotation at 10 MB / 20 MB). It only communicates with the user's own Feishu tenant and the AI client run by the user, with no CDN / analytics / error reporting. How to clear:rm -rf ~/.feishu-user-plugin && npm uninstall -g feishu-user-plugin。