EthanQC/feishu-user-plugin
GitHub: EthanQC/feishu-user-plugin
一个通过逆向飞书 Protobuf 协议实现「以用户身份发送消息」的 MCP Server，同时集成官方 API 覆盖文档、表格、Wiki 和云盘功能。
Stars: 0 | Forks: 0
# feishu-user-plugin
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](#tools-33-total)
[](CONTRIBUTING.md)
**All-in-one Feishu/Lark MCP Server -- 33 工具，8 技能，3 层认证，覆盖消息、文档、表格、Wiki 和云盘。**
唯一允许你以**个人身份**（而非机器人）发送消息的 MCP Server，同时集成了完整的官方 Feishu API 用于文档、电子表格、Wiki 等功能。
## 亮点
- **以自己身份发送** -- 消息显示你的真实姓名，而非机器人。支持文本、富文本、图片、文件、表情包和音频。
- **读取所有内容** -- 通过 bot API 读取群聊，通过 OAuth UAT 读取 P2P（私信）。
- **完整 Feishu 套件** -- Docs、Bitable（电子表格）、Wiki、Drive、通讯录 -- 尽在一个插件。
- **3 层认证** -- 基于 Cookie 的用户身份、App 凭证（Official API）和 OAuth UAT（P2P 读取）。各自独立；按需配置。
- **8 个 Claude Code 斜杠命令** -- `/send`, `/reply`, `/search`, `/digest`, `/doc`, `/table`, `/wiki`, `/status`
- **自动会话管理** -- 每 4 小时 Cookie 心跳，UAT 带轮换自动刷新。
- **群聊名称解析** -- 传入群名称而非 `oc_xxx` ID；自动解析。
## 为什么开发这个项目
Feishu 官方 API 有一个硬性限制：**没有 `send_as_user` 权限范围**。即使使用 `user_access_token` (OAuth)，消息仍显示 `sender_type: "app"`。
本项目将三层认证整合到一个插件中：
```
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)
```
**一个插件。囊括 Feishu 所有功能。无需其他 MCP。**
## 快速开始
### 方式 1: npx (推荐)
```
npx feishu-user-plugin
```
无需安装。该包通过 npx 直接运行。
### 方式 2: 克隆并在本地运行
```
git clone https://github.com/EthanQC/feishu-user-plugin.git
cd feishu-user-plugin
npm install
npm start
```
## 创建你的 Feishu 应用
要使用 Official API 工具（文档、表格、wiki、云盘、机器人消息），你需要创建一个 Feishu 应用：
### 步骤 1: 创建应用
1. 前往 [Feishu Open Platform](https://open.feishu.cn/app) 并登录
2. 点击 **创建自建应用** (Create Custom App) -- 你必须选择 **自建应用** (Custom App)，而非市场/第三方类型
3. 填写应用名称和描述，然后创建它
### 步骤 2: 启用机器人能力
1. 在你的应用设置中，前往 **添加应用能力** (Add Capabilities)
2. 启用 **机器人** (Bot)
### 步骤 3: 添加权限 (Scopes)
前往 **权限管理** (Permissions & Scopes) 并添加以下权限范围：
| Scope | Purpose |
|-------|---------|
| `im:message` | 以机器人身份发送消息 |
| `im:message:readonly` | 读取消息历史 |
| `im:chat:readonly` | 列出并读取聊天 |
| `docx:document` | 读取并创建文档 |
| `docx:document:readonly` | 读取文档 |
| `bitable:record` | 读写 Bitable 记录 |
| `wiki:wiki:readonly` | 读取 Wiki 空间和节点 |
| `drive:drive:readonly` | 列出云盘文件和文件夹 |
| `contact:user.id:readonly` | 通过邮箱/手机号查询用户 |
### 步骤 4: 获取应用凭证
1. 前往 **凭证与基础信息** (Credentials & Basic Info)
2. 复制 **App ID** (`cli_xxxxxxxxxxxx`) 和 **App Secret**
3. 将它们设置为环境变量 `LARK_APP_ID` 和 `LARK_APP_SECRET`
### 步骤 5: 发布与审核
1. **创建版本** 并提交审核 (Create version)
2. 让你的组织管理员批准该应用 (Admin review)
3. 批准后，应用即上线
### 步骤 6: 将机器人添加到群聊
将你的机器人添加到你希望它读取消息的群聊中。机器人只能访问它被添加到的聊天。
## 环境变量
| Variable | Required For | Description |
|----------|-------------|-------------|
| `LARK_COOKIE` | 用户身份工具 | Feishu 网页会话 cookie 字符串。`send_to_user`、`send_to_group`、`search_contacts` 等功能需要。 |
| `LARK_APP_ID` | Official API 工具 | 来自 Feishu Open Platform 的 App ID。`read_messages`、docs、tables、wiki、drive 需要此变量。 |
| `LARK_APP_SECRET` | Official API 工具 | 来自 Feishu Open Platform 的 App Secret。与 `LARK_APP_ID` 配合使用。 |
| `LARK_USER_ACCESS_TOKEN` | P2P 聊天读取 | OAuth 用户 token。`read_p2p_messages` 和 `list_user_chats` 需要此变量。通过 `node src/oauth.js` 获取。 |
每一层认证都是独立的。你可以配置：
- **仅 Cookie** -- 用于以自己身份发送消息
- **仅 App 凭证** -- 用于读取 docs、tables、wiki、群聊
- **全部三者** -- 用于获取完整功能集
## 如何获取你的 Cookie
**方式 A: 通过 Playwright MCP 自动化 (推荐，零手动复制)**
首先，如果你还没有安装 Playwright MCP，请先安装：
```
npx @anthropic-ai/claude-code mcp add playwright -- npx @anthropic-ai/mcp-server-playwright
```
然后只需告诉 Claude Code：**"帮我设置我的 Feishu cookie"**
Claude Code 将自动：
1. 通过 Playwright 在浏览器中打开 feishu.cn
2. 向你展示二维码 — 使用 Feishu 移动端应用扫码
3. 通过 `context.cookies()` 提取完整 cookie（包括 HttpOnly）
4. 将其写入你的 `.mcp.json` LARK_COOKIE 字段
5. 提示你重启 Claude Code
**方式 B: 手动 (通过 Network 标签页)**
1. 在浏览器中打开 [feishu.cn/messenger](https://www.feishu.cn/messenger/) 并登录
2. 打开开发者工具 (`F12` 或 `Cmd+Option+I`)
3. 前往 **Network** 标签页 → 勾选 **Disable cache** → 按 `Cmd+R` 重新加载
4. 点击列表中的第一个请求（通常是页面本身）
5. 在右侧面板中，找到 **Request Headers** → **Cookie:** → 右键点击 → **Copy value**
6. 将其设置为环境变量 `LARK_COOKIE`
## 如何设置 P2P 聊天读取 (OAuth)
要使用 `read_p2p_messages` 和 `list_user_chats` 读取私信历史：
1. 你的 Feishu 应用必须是 **自建应用** (Custom App)，而非市场/第三方应用
2. 添加权限范围：`im:message`, `im:message:readonly`, `im:chat:readonly`
3. 在你应用的 **安全设置** (Security Settings) 中，添加 OAuth 重定向 URI：`http://127.0.0.1:9997/callback`
4. **重要**：确保在你的应用版本设置中“对外共享” (external sharing) 处于**禁用**状态 —— 启用它会将应用标记为 b2c/b2b 类型，从而阻止 P2P 聊天访问
5. 运行授权流程：
```
# 如果您克隆了 repo：
node src/oauth.js
# 如果您通过 npx 安装：
cd $(npm root -g)/feishu-user-plugin && node src/oauth.js
# 或者仅为了 OAuth 步骤克隆 repo，然后使用 npx 进行日常使用
```
浏览器窗口将打开以进行 OAuth 授权。Token 会自动保存到 `.env` 并在运行时自动刷新。将生成的 `LARK_USER_ACCESS_TOKEN` 添加到你的 `.mcp.json` env 中。
## MCP 客户端配置
### Claude Code
添加到你的项目 `.mcp.json`（或全局 `~/.claude/.mcp.json`）：
**使用 npx:**
```
{
"mcpServers": {
"feishu": {
"command": "npx",
"args": ["-y", "feishu-user-plugin"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
**使用本地克隆:**
```
{
"mcpServers": {
"feishu": {
"command": "node",
"args": ["/absolute/path/to/feishu-user-plugin/src/index.js"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
然后只需这样说：
- "发消息给 Alice 说会议在下午 3 点"
- "工程群今天聊了什么？"
- "搜索关于 MCP 的文档"
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) 或 `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```
{
"mcpServers": {
"feishu": {
"command": "npx",
"args": ["-y", "feishu-user-plugin"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
### Cursor
添加到项目中的 `.cursor/mcp.json`:
```
{
"mcpServers": {
"feishu": {
"command": "npx",
"args": ["-y", "feishu-user-plugin"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
### VS Code (Copilot)
添加到项目中的 `.vscode/mcp.json`:
```
{
"servers": {
"feishu": {
"type": "stdio",
"command": "npx",
"args": ["-y", "feishu-user-plugin"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
### Windsurf
添加到 `~/.codeium/windsurf/mcp_config.json`:
```
{
"mcpServers": {
"feishu": {
"command": "npx",
"args": ["-y", "feishu-user-plugin"],
"env": {
"LARK_COOKIE": "your-cookie-string",
"LARK_APP_ID": "cli_xxxxxxxxxxxx",
"LARK_APP_SECRET": "your-app-secret"
}
}
}
}
```
## 工具 (共 33 个)
### 用户身份 -- 消息发送 (cookie auth, Protobuf)
以自己身份发送消息，而非机器人。
| Tool | Description |
|------|-------------|
| `send_to_user` | 按名字搜索用户 + 发送文本 -- 一步完成 |
| `send_to_group` | 按名字搜索群组 + 发送文本 -- 一步完成 |
| `send_as_user` | 按 ID 发送文本到任意聊天，支持回复主题 (`root_id` / `parent_id`) |
| `send_image_as_user` | 发送图片（需要上传后的 `image_key`） |
| `send_file_as_user` | 发送文件（需要上传后的 `file_key`） |
| `send_post_as_user` | 发送带标题 + 格式化段落（链接、@提及）的富文本 |
| `send_sticker_as_user` | 发送表情包/emoji |
| `send_audio_as_user` | 发送音频消息 |
### 用户身份 -- 联系人与信息 (cookie auth)
| Tool | Description |
|------|-------------|
| `search_contacts` | 按名字搜索用户、机器人或群聊 |
| `create_p2p_chat` | 创建/获取 P2P（私信）聊天，返回数字 `chat_id` |
| `get_chat_info` | 群组详情：名称、描述、成员数量、群主 |
| `get_user_info` | 通过用户 ID 查找用户显示名称 |
| `get_login_status` | 检查 cookie、app 凭证和 UAT 状态 |
### 用户 OAuth UAT -- P2P 聊天读取
| Tool | Description |
|------|-------------|
| `read_p2p_messages` | 读取 P2P（私信）历史。适用于机器人无法访问的聊天。 |
| `list_user_chats` | 列出用户所在的所有聊天，包括 P2P。 |
### Official API -- IM (Bot Identity)
| Tool | Description |
|------|-------------|
| `list_chats` | 列出机器人已加入的所有聊天 |
| `read_messages` | 读取消息历史（接受聊天名称或 `oc_xxx` ID） |
| `reply_message` | 通过 `message_id` 回复特定消息（以机器人身份） |
| `forward_message` | 将消息转发到另一个聊天 |
### Official API -- Documents
| Tool | Description |
|------|-------------|
| `search_docs` | 按关键字搜索文档 |
| `read_doc` | 读取文档原始文本内容 |
| `create_doc` | 创建新文档 |
### Official API -- Bitable (Spreadsheets)
| Tool | Description |
|------|-------------|
| `list_bitable_tables` | 列出 Bitable 应用中的所有表格 |
| `list_bitable_fields` | 列出表格中的所有字段（列） |
| `search_bitable_records` | 带过滤和排序查询记录 |
| `create_bitable_record` | 创建新记录（行） |
| `update_bitable_record` | 更新现有记录 |
### Official API -- Wiki
| Tool | Description |
|------|-------------|
| `list_wiki_spaces` | 列出所有可访问的 Wiki 空间 |
| `search_wiki` | 按关键字搜索 Wiki/文档 |
| `list_wiki_nodes` | 浏览 Wiki 节点树 |
### Official API -- Drive
| Tool | Description |
|------|-------------|
| `list_files` | 列出文件夹中的文件 |
| `create_folder` | 创建新文件夹 |
### Official API -- Contacts
| Tool | Description |
|------|-------------|
| `find_user` | 通过邮箱或手机号查找用户 |
## Claude Code 斜杠命令 (8 个技能)
此插件在 `skills/feishu-user-plugin/` 中包含 8 个内置技能：
| Skill | Usage | Description |
|-------|-------|-------------|
| `/send` | `/send Alice: meeting at 3pm` | 以自己身份发送消息 |
| `/reply` | `/reply engineering-chat` | 读取最近消息并回复 |
| `/digest` | `/digest engineering-chat 7` | 总结最近聊天消息 |
| `/search` | `/search engineering` | 搜索联系人和群组 |
| `/doc` |doc search MCP` | 搜索、读取或创建文档 |
| `/table` | `/table query appXxx` | 查询或创建 Bitable 记录 |
| `/wiki` | `/wiki search protocol` | 搜索并浏览 Wiki |
| `/status` | `/status` | 检查登录和认证状态 |
安装插件后，技能将自动可用。
## 架构
```
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) │
└──────────────────────────────────────┘
```
## 会话与 Token 生命周期
| Auth Layer | Token | Lifetime | Refresh |
|------------|-------|----------|---------|
| Cookie | `sl_session` | 12h max-age | 通过心跳每 4 小时自动刷新 |
| App Token | `tenant_access_token` | 2h | 由 SDK 自动管理 |
| User OAuth | `user_access_token` | ~2h | 通过 `refresh_token` 自动刷新，保存到 `.env` |
当 Cookie 过期时（约 12-24 小时无心跳后），在 feishu.cn 重新登录并更新 `LARK_COOKIE`。使用 `get_login_status` 主动检查健康状态。
## 项目结构
```
feishu-user-plugin/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── skills/
│ └── feishu-user-plugin/
│ ├── SKILL.md # Main skill definition (trigger, tools, auth)
│ └── references/ # 8 skill reference docs + CLAUDE.md
├── 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
│ ├── test-send.js # Quick CLI test
│ └── test-all.js # Full test suite
├── proto/
│ └── lark.proto # Protobuf message definitions
├── .mcp.json.example # MCP server config template
├── server.json # MCP Registry manifest
├── .env.example # Configuration template
└── package.json
```
## 限制
- 基于 Cookie 的认证需要定期刷新（自动心跳可延长至约 12 小时；之后需手动重新登录）
- 依赖 Feishu 内部 Protobuf 协议 -- 如果 Feishu 更新其 Web 客户端，可能会失效
- 图片/文件/音频发送需要预上传的 key（通过 Official API 或外部桥接上传）
- 无实时消息接收（WebSocket 推送尚未实现）
- 可能违反 Feishu 服务条款 -- 使用风险自负
## 贡献
欢迎提交 Issue 和 PR！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发设置、代码风格和提交指南。
如果 Feishu 更新其协议导致某些功能失效，请 [打开一个 issue](https://github.com/EthanQC/feishu-user-plugin/issues/new?template=bug_report.md) 并提供错误详情。
## 许可证
[MIT](LICENSE)
## 致谢
- [cv-cat/LarkAgentX](https://github.com/cv-cat/LarkAgentX) -- 原始 Feishu 协议逆向工程
- [cv-cat/OpenFeiShuApis](https://github.com/cv-cat/OpenFeiShuApis) -- 底层 API 研究
- [Model Context Protocol](https://modelcontextprotocol.io) -- MCP 标准
标签：API 集成, Claude, Cookie 认证, CVE检测, DNS解析, GNU通用公共许可证, Lark, MCP Server, MITM代理, Model Context Protocol, Node.js, OAuth, Protobuf, RPA, Ruby, 云资产清单, 企业协作, 协议分析, 即时通讯, 多维表格, 开源项目, 文档处理, 权限提升, 消息推送, 用户身份模拟, 知识库, 私聊发送, 自动化办公, 自定义脚本, 逆向工程, 非机器人, 飞书