Feishu User MCP

Feishu user plugin - Feishu MCP server+CLI tool

 ](https://nodejs.org)   ](https://www.npmjs.com/package/feishu-user-plugin) 

Feishu/Lark MCP server, covering IM, documents, multi-dimensional tables, knowledge base, cloud space, calendar, task v2, OKR, real-time events.85 Tools · 3-layer Authentication · 9 MCP prompts · MIT licensed · Node ≥ 18.

Compatible with MCP clients such as Claude Code, Codex, cursor, Windsurf, VS Code, Claude Desktop, OpenClaw, etc.

There are two paths for sending messages as a user identity:Feishu Official OAuth Scope im:message.send_as_user(requires creating a self built application and administrator approval), or for this warehouse Cookie+protobuf path(Zero application threshold, run immediately after capturing cookies). This warehouse is no longer physically exclusive, but it is still a convenient option for "individual developers/no administrator privileges/want to quickly try" scenarios.

Compared with the official version (Feishu also released MCP+CLI in 2026)

• larksuite/lark-openapi-mcp ——Official OpenAPI MCP,⚠ Beta +Last updated on August 2025 (9 months ago), README plaintext does not support file upload and download, nor does it support document editing; 1271 endpoint tools, but only~20 presets are available for default, and the rest have not undergone compatibility testing
• larksuite/cli ——Official CLI (9.9k stars, active), 17 business domains, 200+commands+24 AI Agent Skills,Supported +messages-send --as user（走 OAuth scope im:message.send_as_user）But CLI form instead of MCP， Using Codex/Cursor/Windsurf requires shell out

When should I use this warehouse：

• I want to send messages/read P2P private chats as a user, butDo not want/cannot create Feishu self built application(Individual developer/No administrator privileges) - Zero threshold for cookie path
• Using MCP protocol (Codex/Cursor/Windsurf/VS Code, etc.)+no need for email/approval/HR/meeting minutes and other domains not covered by our warehouse
• Coexistence of multiple MCP clients and the need for "precise delivery of real-time events across the entire machine" (v1.3.9+machine level WS SSOT)

When to use the officialBusiness system domains such as email/approval/attendance/HR/recruitment/meeting minutes are required; Or there may be an existing Feishu application and an administrator approved OAuth scope, with a preference for official long-term stable paths.

See for a complete and honest comparison docs/COMPARISON.md.

usage

你：帮我以我身份给王小明发：今天的代码 review 我看完了，有 3 个 nit
Claude：[调用 send_to_user]  Sent

你：总结"工程组"群今天 9 点之后的讨论，发个日报到 #日报频道
Claude：[read_messages → 总结 → send_to_group]  Sent

Install

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

Cookie retrieval (Playwright automatic scanning/VNet manual), creation of Feishu application, detailed configuration of each client docs/AUTH-SETUP.md.

Three layer authentication

Three layer independence - configure any layer, corresponding tools are available.

core competency

• Send a message as you(8) : text/image/file/rich text post/card/batch; Differentiated anchor point - Feishu official API does not have it send_as_user
• Reading groups and P2P private chats(17) : Group messages/private chats/ merge_forward Auto expand/URL+Feishu document link automatic extraction/External group automatic fallback to UAT
• Document Ecology(27): Feishu documents (including read_doc_markdown Province~60% token)/Multi dimensional table (500 pieces in bulk)/Knowledge base (including write CRUD)/Cloud space
• Collaboration tool(21): Calendar (read+write)/Task v2 (including member management)/OKR (read+progress record)/Contact person
• real-time event(2) Machine level SSOT WS, delivering each event precisely once on the entire machine
• Diagnosis and Multiple Accounts(4) N profiles automatically switch, write path not switched (to avoid creating resources with incorrect numbers)

Complete tool list+cross domain caveat+usage patterns see docs/TOOLS.md.

9 个 MCP prompts（slash commands）

Client configuration

Unified environment variables, different configuration file locations and top-level keys:

npx feishu-user-plugin setup                       # Claude Code
npx feishu-user-plugin setup --client codex        # Codex
npx feishu-user-plugin setup --client both         # 都写

Please refer to the complete JSON templates for each client README.en.md MCP Client ConfigurationPlease refer to the detailed installation and certification process docs/AUTH-SETUP.md.

multiple accounts

~/.feishu-user-plugin/credentials.json Support multiple profiles (default+arbitrary attachment), with a single machine configured to cover multiple Feishu accounts/enterprises.

npx feishu-user-plugin list-profiles
npx feishu-user-plugin switch-profile 
npx feishu-user-plugin keepalive --all       # 跨 profile keepalive

Read path tool failure code 91403 / 1254301 / 1254000 / 99991672 / HTTP 403 Automatically cross profile retry. Do not automatically switch paths when writing (to avoid creating resources with incorrect numbers). Monotonic coverage: transmission via_profile: "" Pin to the specified profile.

see details docs/TOOLS.md "多 profile auto-switch".

real-time event

A single process on the machine holds a WS owner lock, which is shared by all MCP processes events.jsonlEach event happens exactly once on the entire machine.

mcp call manage_ws_status --action info
mcp call manage_ws_status --action claim --force true

Default subscription ["im.message.receive_v1"]To subscribe to approval/calendar/VC and other events, edit credentials.json::profiles[].eventsAnd then manage_ws_status(action=reconfig) Do not restart and re subscribe.

WSClient that only supports feishu.cn - Lark International Edition (Lark. com) is currently not supported.

Known limitations

• Cookie lifespan12-24 hours without heartbeat expiration, need to log in to feishu.cn again to retrieve cookies
• Protocol changesThe cookie+protobuf layer depends on the protocol of the Feishu web client, and Feishu updates may become invalid (robot capabilities are not affected)
• cardThe cookie channel cannot send cards to the server, but the robot channel can send them
• Lark International EditionReal time event WS is not supported
• unrealized：search_messages、 Md → wiki synchronization (see details) ROADMAP.md）

document

Complete docs/index:docs/README.md.

contribution

Issues/PRs are welcome. Check before submitting CONTRIBUTING.md.

Fei Shu changed the protocol and caused the function to crash - simply open an issue with an error log.

Privacy/Privacy

The MCP server running locally retains credentials on the user's local machine, does not report telemetry, and does not communicate with the plugin author's backend. The complete text can be found at PRIVACY.md.

• collectThe plugin itself does not collect any data;LARK_COOKIE / LARK_APP_ID / LARK_APP_SECRET / LARK_USER_ACCESS_TOKEN / LARK_USER_REFRESH_TOKEN All user initiated configurations are sourced from their own Feishu/Lark accounts
• handleOnly process messages/documents/multidimensional tables/knowledge bases/cloud spaces/calendars/tasks/OKRs/contacts actively requested by users through MCP tools, without retention or analysis
• storage：~/.feishu-user-plugin/credentials.json（mode 0600）； Optional event log ~/.feishu-user-plugin/events.jsonl(10 MB/20 MB automatic rotation)
• third partyOnly communicate with the user's own Feishu tenant and the AI client running by the user, without CDN/analysis/error reporting
• retain: Full user control;rm -rf ~/.feishu-user-plugin && npm uninstall -g feishu-user-plugin Clear immediately
• contact：Add security issues before the issue title [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: ; security disclosures with [security] prefix in the title

License

MIT

Acknowledgments

• cv-cat/LarkAgentX ——Research on Early Feishu Web Protocol (Python)
• cv-cat/OpenFeiShuApis ——Research on the underlying API
• Model Context Protocol ——MCP standard+Anthropic/PulseMCP/GitHub/Stacklok co maintained registry