feishu-user-mcp

feishu-user-mcp

All-in-one Feishu/Lark MCP Server -- 33 tools, 8 skills, 3 auth layers for messaging, docs, tables, wiki, and drive.

The only MCP server that lets you send messages as your personal identity (not a bot), while also integrating the full official Feishu API for documents, spreadsheets, wikis, and more.

Highlights

• Send as yourself -- Messages show your real name, not a bot. Supports text, rich text, images, files, stickers, and audio.
• Read everything -- Group chats via bot API, P2P (direct messages) via OAuth UAT.
• Full Feishu suite -- Docs, Bitable (spreadsheets), Wiki, Drive, Contacts -- all in one plugin.
• 3 auth layers -- Cookie-based user identity, app credentials (Official API), and OAuth UAT (P2P reading). Each is independent; configure only what you need.
• 8 slash commands for Claude Code -- /send, /reply, /search, /digest, /doc, /table, /wiki, /status
• Auto session management -- Cookie heartbeat every 4h, UAT auto-refresh with token rotation.
• Chat name resolution -- Pass a group name instead of oc_xxx ID; it resolves automatically.

Why This Exists

Feishu's official API has a hard limitation: there is no send_as_user scope. Even with user_access_token (OAuth), messages still show sender_type: "app".

This project combines three auth layers into one plugin:

User Identity (cookie):     You -> Protobuf -> Feishu (messages appear as YOU)
Official API  (app token):  You -> REST API -> Feishu (docs, tables, wiki, drive)
User OAuth    (UAT):        You -> REST API -> Feishu (read P2P chats, list all chats)

One plugin. Everything Feishu. No other MCP needed.

Quick Start

Option 1: npx (recommended)

npx feishu-user-mcp

No installation needed. The package runs directly via npx.

Option 2: Clone and run locally

git clone https://github.com/EthanQC/feishu-user-mcp.git
cd feishu-user-mcp
npm install
npm start

Create Your Feishu App

To use the Official API tools (docs, tables, wiki, drive, bot messaging), you need to create a Feishu app:

Step 1: Create the App

• Go to Feishu Open Platform and log in
• Click Create Custom App (创建自建应用) -- you must choose Custom App (自建应用), NOT marketplace/third-party types
• Fill in the app name and description, then create it

Step 2: Enable Bot Capability

• In your app settings, go to Add Capabilities (添加应用能力)
• Enable Bot (机器人)

Step 3: Add Permissions (Scopes)

Go to Permissions & Scopes (权限管理) and add the following scopes:

Scope	Purpose
im:message	Send messages as bot
im:message:readonly	Read message history
im:chat:readonly	List and read chats
docx:document	Read and create documents
docx:document:readonly	Read documents
bitable:record	Read and write Bitable records
wiki:wiki:readonly	Read wiki spaces and nodes
drive:drive:readonly	List Drive files and folders
contact:user.id:readonly	Look up users by email/mobile

Add more scopes as needed depending on which tools you use.

Step 4: Get App Credentials

• Go to Credentials & Basic Info (凭证与基础信息)
• Copy the App ID (cli_xxxxxxxxxxxx) and App Secret
• Set them as LARK_APP_ID and LARK_APP_SECRET in your environment

Step 5: Publish and Approve

• Create a version and submit it for review (创建版本)
• Have your organization admin approve the app (管理员审核)
• After approval, the app is live

Step 6: Add Bot to Group Chats

Add your bot to the group chats where you want it to read messages. The bot can only access chats it has been added to.

Environment Variables

Variable	Required For	Description
LARK_COOKIE	User identity tools	Feishu web session cookie string. Needed for send_to_user, send_to_group, search_contacts, etc.
LARK_APP_ID	Official API tools	App ID from Feishu Open Platform. Needed for read_messages, docs, tables, wiki, drive.
LARK_APP_SECRET	Official API tools	App Secret from Feishu Open Platform. Used together with LARK_APP_ID.
LARK_USER_ACCESS_TOKEN	P2P chat reading	OAuth user token. Needed for read_p2p_messages and list_user_chats. Obtained via node src/oauth.js.

Each auth layer is independent. You can configure:

• Cookie only -- for sending messages as yourself
• App credentials only -- for reading docs, tables, wiki, group chats
• All three -- for the full feature set

How to Get Your Cookie

Option A: With Playwright MCP (recommended)

If you have Playwright MCP configured, let Claude Code handle it automatically — you just scan the QR code to log in:

// Playwright can access HttpOnly cookies that document.cookie cannot
const cookies = await context.cookies('https://www.feishu.cn');
const cookieStr = cookies.map(c => c.name + '=' + c.value).join('; ');

Option B: Manual (via Network tab)

• Open feishu.cn/messenger in your browser and log in
• Open DevTools (F12 or Cmd+Option+I)
• Go to the Network tab → check Disable cache → press Cmd+R to reload
• Click the first request in the list (usually the page itself)
• In the right panel, find Request Headers → Cookie: → right-click → Copy value
• Set it as LARK_COOKIE in your environment

⚠️ Do NOT use document.cookie in the Console or copy from Application → Cookies tab individually — neither method captures HttpOnly cookies (session, sl_session), which are required for authentication.

The server automatically refreshes the session via heartbeat every 4 hours. The sl_session cookie has a 12-hour max-age.

How to Set Up P2P Chat Reading (OAuth)

To read direct message history with read_p2p_messages and list_user_chats:

• Your Feishu app must be a Custom App (自建应用), NOT marketplace/third-party
• Add scopes: im:message, im:message:readonly, im:chat:readonly
• In your app's Security Settings (安全设置), add the OAuth redirect URI: http://127.0.0.1:9997/callback
• Important: Make sure "对外共享" (external sharing) is disabled in your app version settings — enabling it marks the app as b2c/b2b type, which blocks P2P chat access
• Run the authorization flow:

# If you cloned the repo:
node src/oauth.js

# If you installed via npx:
cd $(npm root -g)/feishu-user-mcp && node src/oauth.js
# Or clone the repo just for the OAuth step, then use npx for daily use

A browser window will open for OAuth consent. The token is saved to .env automatically and auto-refreshes at runtime. Add the resulting LARK_USER_ACCESS_TOKEN to your .mcp.json env.

MCP Client Configuration

Claude Code

Add to your project's .mcp.json (or ~/.claude/.mcp.json for global):

Using npx:

{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": ["-y", "feishu-user-mcp"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Using a local clone:

{
  "mcpServers": {
    "feishu": {
      "command": "node",
      "args": ["/absolute/path/to/feishu-user-mcp/src/index.js"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Then just say things like:

• "Send a message to Alice saying the meeting is at 3pm"
• "What did the engineering group chat about today?"
• "Search for docs about MCP"

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": ["-y", "feishu-user-mcp"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": ["-y", "feishu-user-mcp"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "feishu": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "feishu-user-mcp"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "feishu": {
      "command": "npx",
      "args": ["-y", "feishu-user-mcp"],
      "env": {
        "LARK_COOKIE": "your-cookie-string",
        "LARK_APP_ID": "cli_xxxxxxxxxxxx",
        "LARK_APP_SECRET": "your-app-secret"
      }
    }
  }
}

Tools (33 total)

User Identity -- Messaging (cookie auth, Protobuf)

Send messages as yourself, not as a bot.

Tool	Description
send_to_user	Search user by name + send text -- one step
send_to_group	Search group by name + send text -- one step
send_as_user	Send text to any chat by ID, supports reply threading (root_id / parent_id)
send_image_as_user	Send image (requires image_key from upload)
send_file_as_user	Send file (requires file_key from upload)
send_post_as_user	Send rich text with title + formatted paragraphs (links, @mentions)
send_sticker_as_user	Send sticker/emoji
send_audio_as_user	Send audio message

User Identity -- Contacts & Info (cookie auth)

Tool	Description
search_contacts	Search users, bots, or group chats by name
create_p2p_chat	Create/get P2P (direct message) chat, returns numeric chat_id
get_chat_info	Group details: name, description, member count, owner
get_user_info	User display name lookup by user ID
get_login_status	Check cookie, app credentials, and UAT status

User OAuth UAT -- P2P Chat Reading

Tool	Description
read_p2p_messages	Read P2P (direct message) history. Works for chats the bot cannot access.
list_user_chats	List all chats the user is in, including P2P.

Official API -- IM (Bot Identity)

Tool	Description
list_chats	List all chats the bot has joined
read_messages	Read message history (accepts chat name or oc_xxx ID)
reply_message	Reply to a specific message by message_id (as bot)
forward_message	Forward a message to another chat

Official API -- Documents

Tool	Description
search_docs	Search documents by keyword
read_doc	Read raw text content of a document
create_doc	Create a new document

Official API -- Bitable (Spreadsheets)

Tool	Description
list_bitable_tables	List all tables in a Bitable app
list_bitable_fields	List all fields (columns) in a table
search_bitable_records	Query records with filter and sort
create_bitable_record	Create a new record (row)
update_bitable_record	Update an existing record

Official API -- Wiki

Tool	Description
list_wiki_spaces	List all accessible wiki spaces
search_wiki	Search wiki/docs by keyword
list_wiki_nodes	Browse wiki node tree

Official API -- Drive

Tool	Description
list_files	List files in a folder
create_folder	Create a new folder

Official API -- Contacts

Tool	Description
find_user	Find user by email or mobile number

Claude Code Slash Commands (8 skills)

This repo includes 8 ready-to-use slash commands in .claude/commands/:

Skill	Usage	Description
/send	/send Alice: meeting at 3pm	Send message as yourself
/reply	/reply engineering-chat	Read recent messages and reply
/digest	/digest engineering-chat 7	Summarize recent chat messages
/search	/search engineering	Search contacts and groups
/doc	/doc search MCP	Search, read, or create documents
/table	/table query appXxx	Query or create Bitable records
/wiki	/wiki search protocol	Search and browse wiki
/status	/status	Check login and auth status

To use these skills, copy .claude/commands/ into your project.

Architecture

                               Cookie + Proto   ┌──────────────────────────────────────┐
                             ────────────────── >│  internal-api-lark-api.feishu.cn     │
┌──────────────┐                                 │  /im/gateway/ (Protobuf over HTTP)   │
│  MCP Client  │                                 └──────────────────────────────────────┘
│  (Claude,    │  App Token (REST) ┌──────────────────────────────────────┐
│   Cursor,    │ ────────────────->│  open.feishu.cn/open-apis/           │
│   VS Code)   │                   │  (Official REST API)                 │
│              │                   └──────────────────────────────────────┘
│              │  User OAuth (REST)┌──────────────────────────────────────┐
│              │ ────────────────->│  open.feishu.cn/open-apis/           │
└──────────────┘                   │  (UAT -- P2P chat reading)           │
                                   └──────────────────────────────────────┘

Session & Token Lifecycle

Auth Layer	Token	Lifetime	Refresh
Cookie	sl_session	12h max-age	Auto-refreshed every 4h via heartbeat
App Token	tenant_access_token	2h	Auto-managed by SDK
User OAuth	user_access_token	~2h	Auto-refreshed via refresh_token, saved to .env

When the cookie expires (after ~12-24h without heartbeat), re-login at feishu.cn and update LARK_COOKIE. Use get_login_status to check health proactively.

Project Structure

feishu-user-mcp/
├── src/
│   ├── index.js          # MCP server entry point (33 tools)
│   ├── client.js         # User identity client (Protobuf gateway)
│   ├── official.js       # Official API client (REST, UAT)
│   ├── utils.js          # ID generators, cookie parser
│   ├── oauth.js          # OAuth flow for user_access_token
│   ├── oauth-auto.js     # Automated OAuth with Playwright
│   ├── test-send.js      # Quick CLI test
│   └── test-all.js       # Full test suite
├── proto/
│   └── lark.proto        # Protobuf message definitions
├── .claude/
│   └── commands/         # 8 Claude Code slash commands
├── server.json           # MCP Registry manifest
├── .env.example          # Configuration template
└── package.json

Limitations

• Cookie-based auth requires periodic refresh (auto-heartbeat extends to ~12h; manual re-login needed after that)
• Depends on Feishu's internal Protobuf protocol -- may break if Feishu updates their web client
• Image/file/audio sending requires pre-uploaded keys (upload via Official API or external bridge)
• No real-time message receiving (WebSocket push not yet implemented)
• May violate Feishu's Terms of Service -- use at your own risk

Contributing

Issues and PRs welcome! See CONTRIBUTING.md for development setup, code style, and submission guidelines.

If Feishu updates their protocol and something breaks, please open an issue with the error details.

License

MIT

Acknowledgments

• cv-cat/LarkAgentX -- Original Feishu protocol reverse-engineering (Python)
• cv-cat/OpenFeiShuApis -- Underlying API research
• Model Context Protocol -- The MCP standard