# 飞书 MCP 服务器 [![npm version](https://img.shields.io/npm/v/feishu-mcp?color=blue&label=npm)](https://www.npmjs.com/package/feishu-mcp) [![MIT License](https://img.shields.io/badge/license-MIT-green)](./LICENSE) 为 [Cursor](https://cursor.sh/)、[Windsurf](https://codeium.com/windsurf)、[Cline](https://cline.bot/) 和其他 AI 驱动的编码工具提供访问、编辑和结构化处理飞书文档的能力，**并支持飞书任务管理和用户信息查询**，基于 [Model Context Protocol](https://modelcontextprotocol.io/introduction) 服务器实现。 **现已支持 `feishu-tool` 独立 CLI 工具**，可在终端或脚本中直接调用所有飞书工具，无需启动 MCP 服务器。配合 [Feishu-Skill](https://github.com/cso1z/Feishu-Skill) 可让 Claude Code 等 AI Agent 自动选择最合适的方式操作飞书。 本项目让 AI 编码工具能够： - **文档处理**：直接获取、理解、创建和编辑飞书文档，显著提升文档处理的智能化和效率 - **任务管理**：列取、创建、更新、删除飞书任务，支持子任务和成员管理（需 user 认证） - **用户信息**：按名称搜索或按 ID 批量获取飞书用户，便于任务分配和文档协作（需 user 认证） **完整覆盖飞书文档的真实使用流程，助你高效利用文档资源：** 1. **文件夹目录获取**：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。 2. **内容获取与理解**：支持结构化、分块、富文本等多维度内容读取，AI 能精准理解文档上下文。 3. **智能创建与编辑**：可自动创建新文档、批量生成和编辑内容，满足多样化写作需求。 4. **高效检索与搜索**：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。 5. **任务管理与用户查询**：支持飞书任务 CRUD 及用户信息搜索，便于在文档中关联任务和人员。 本项目让你在飞书文档的日常使用流程中实现智能获取、编辑和搜索，并扩展任务与用户管理能力，提升内容处理效率和体验。 ### 💡项目推荐： 使用 Claude Code 推荐配合 [claude-ip-guard](https://github.com/cso1z/claude-ip-guard) —— 自动检测 IP 地理位置并拦截受限地区访问，防止因网络切换导致 Claude 封号。 ### 🎬 使用演示视频 你可以通过以下视频了解 MCP 的实际使用效果和操作流程： 飞书 MCP 使用演示 飞书 MCP 使用演示 > ⭐ **Star 本项目，第一时间获取最新功能和重要更新！** 关注项目可以让你不错过任何新特性、修复和优化，助你持续高效使用。你的支持也将帮助我们更好地完善和发展项目。⭐ --- ## 🛠️ 工具功能详情 | 功能类别 | 工具名称 | 描述 | 使用场景 | 状态 | |---------|--------------------------------------|-------------|--------------------------|-------| | **文档管理** | `create_feishu_document` | 创建新的飞书文档 | 从零开始创建文档 | ✅ 已完成 | | | `get_feishu_document_info` | 获取文档基本信息 | 验证文档存在性和权限 | ✅ 已完成 | | | `get_feishu_document_blocks` | 获取文档块结构 | 了解文档层级结构 | ✅ 已完成 | | **内容编辑** | `batch_create_feishu_blocks` | 批量创建多个块 | 高效创建连续内容 | ✅ 已完成 | | | `update_feishu_block_text` | 更新块文本内容 | 修改现有内容 | ✅ 已完成 | | | `delete_feishu_document_blocks` | 删除文档块 | 清理和重构文档内容 | ✅ 已完成 | | **文件夹管理** | `get_feishu_folder_files` | 获取文件夹文件列表 | 浏览文件夹内容 | ✅ 已完成 | | | `create_feishu_folder` | 创建新文件夹 | 组织文档结构 | ✅ 已完成 | | **搜索功能** | `search_feishu_documents` | 搜索文档 | 查找特定内容 | ✅ 已完成 | | **工具功能** | `get_feishu_document_info` | 获取wiki文档信息 | 将Wiki链接转为文档ID、创建wiki子节点 | ✅ 已完成 | | | `get_feishu_image_resource` | 获取图片资源 | 下载文档中的图片 | ✅ 已完成 | | | `get_feishu_whiteboard_content` | 获取画板内容 | 获取画板中的图形元素和结构(流程图、思维导图等) | ✅ 已完成 | | **高级功能** | `create_feishu_table` | 创建和编辑表格 | 结构化数据展示 | ✅ 已完成 | | | 流程图插入 | 支持流程图和思维导图 | 流程梳理和可视化 | ✅ 已完成 | | | 流程图插入(画板形式) | 支持流程图和思维导图 | 流程梳理和可视化 | ✅ 已完成 | | 图片插入 | `upload_and_bind_image_to_block` | 支持插入本地和远程图片 | 修改文档内容 | ✅ 已完成 | | | 公式支持 | 支持数学公式 | 学术和技术文档 | ✅ 已完成 | | | | | | | | **任务管理** | `list_feishu_tasks` | 列取我负责的任务 | 查看待办/已完成任务 | ✅ 已完成 | | | `create_feishu_task` | 批量创建任务（含子任务） | 新建任务、拆分子任务 | ✅ 已完成 | | | `update_feishu_task` | 更新任务 | 修改内容、成员、提醒 | ✅ 已完成 | | | `delete_feishu_task` | 批量删除任务 | 清理任务 | ✅ 已完成 | | **用户信息** | `get_feishu_users` | 按名称搜索或按 ID 批量获取用户 | 查找成员、任务分配 | ✅ 已完成 | ### 🎨 支持的样式功能（基本支持md所有格式） - **文本样式**：粗体、斜体、下划线、删除线、行内代码 - **文本颜色**：灰色、棕色、橙色、黄色、绿色、蓝色、紫色 - **对齐方式**：左对齐、居中、右对齐 - **标题级别**：支持1-9级标题 - **代码块**：支持多种编程语言语法高亮 - **列表**：有序列表（编号）、无序列表（项目符号） - **图片**：支持本地图片和网络图片 - **公式**：在文本块中插入数学公式，支持LaTeX语法 - **mermaid图表**：支持流程图、时序图、思维导图、类图、饼图等等 - **表格**：支持创建多行列表格，单元格可包含文本、标题、列表、代码块等多种内容类型 - **飞书文档画板**：支持飞书文档的画板创建，提供更加更为丰富和多样化的内容。 --- ## 📈 一周计划：提升工具效率 - ~~**精简工具集**：21个工具 → 13个工具，移除冗余，聚焦核心功能~~ 0.0.15 ✅ - ~~**优化描述**：7000+ tokens → 3000+ tokens，简化提示，节省请求token~~ 0.0.15 ✅ - ~~**批量增强**：新增批量更新、批量图片上传，单次操作效率提升50%~~ 0.0.15 ✅ - **流程优化**：减少多步调用，实现一键完成复杂任务 - ~~**支持多种凭证类型**：包括 tenant_access_token和 user_access_token，满足不同场景下的认证需求~~ (飞书应用配置发生变更) 0.0.16 ✅。 - ~~**支持cursor用户登录**：方便在cursor平台用户认证 不做了,没必要 ❌~~ - ~~**支持mermaid图表**：流程图、时序图等等，丰富文档内容~~ 0.1.11 ✅ - ~~**支持表格创建**：创建包含各种块类型的复杂表格，支持样式控制~~ 0.1.2 ✅ - ~~**支持飞书多用户user认证**：一人部署，可以多人使用~~ 0.1.3 ✅ - ~~**支持user_access_token自动刷新**：无需频繁授权，提高使用体验~~ 0.1.6 ✅ - ~~**支持授权范围校验**：对应用授权进行验证，以确保其符合当前工具的要求。如未满足条件，将提供友好的指引，以便用户更顺畅地使用~~ 0.1.7 ✅ - ~~**支持创建画板内容**：与Mermaid图表相比，画板能够展示更为丰富和多样化的内容，提供更为友好和愉悦的视觉体验~~ (飞书应用配置发生变更) 0.1.7 ✅ - **提取环境变量中的 feishuAppId 和 feishuAppSecret**：将飞书配置从环境变量中分离出来，以便在诸如 cursor 等客户端中进行设置，从而支持一个服务共享给多个团队使用。 - ~~**支持知识库和我的文档库**：实现知识库、我的文档库 节点遍历、节点创建、文件创建、搜索等功能~~ (飞书应用配置发生变更) 0.1.8 ✅ - **版本更新通知**：在发布新版本时，及时向用户提供相关提示与说明。 - ~~**stdio模式user认证问题**：修复stdio模式下飞书user认证失败问题~~ 0.1.9 ✅ - ~~**权限检查功能可配置化**：将权限检查功能作为可配置选项，支持通过环境变量 `FEISHU_SCOPE_VALIDATION` 或命令行参数 `--feishu-scope-validation` 控制，默认启用，满足不同用户的使用场景~~ 0.2.0 ✅ - ~~**优化缓存目录:把token等缓存保存到系统级的配置目录~~ 0.2.2 ✅ 感谢 [Molunerfinn](https://github.com/Molunerfinn)、[leeeezx](https://github.com/leeeezx)、[Master-cai](https://github.com/Master-cai) 三位朋友的建议及代码贡献 - ~~**优化mcpTool相关代码**：重新构建代码结构，以便为未来添加更多功能奠定基础~~ 0.2.3 ✅ - ~~**支持任务管理**：列取、创建、更新、删除飞书任务，支持子任务和成员管理~~ 0.2.4 ✅ - ~~**支持用户信息查询**：按名称搜索或按 ID 批量获取用户，便于任务分配和文档协作~~ 0.2.4 ✅ - ~~**Tool API 层抽取**：新建 Tool API 层，与 tool 层一一对应，统一参数校验、数据转换、错误映射等~~ ✅ - ~~**兼容 CLI 模式**：支持 `feishu-tool ''` 命令行调用，便于脚本与自动化场景~~ 0.2.6 ✅ - ~~**完成 Skill**：提供 [Feishu-Skill](https://github.com/cso1z/Feishu-Skill)，指导 Claude Code 等 AI Agent 在合适场景下使用 feishu-mcp CLI~~ 0.2.6 ✅ --- ## 🔧 飞书配置教程 **⚠️ 重要提示：在开始使用之前，必须先完成飞书应用配置，否则无法正常使用本工具。** 关于如何创建飞书应用和获取应用凭证的说明可以在[官方教程](https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app)找到。 **详细的飞书应用配置步骤**：有关注册飞书应用、配置权限、添加文档访问权限的详细指南，请参阅 [手把手教程 FEISHU_CONFIG.md](FEISHU_CONFIG.md)。 --- ## 🏃‍♂️ 快速开始 ### 方式一：使用 NPM 快速运行 ```bash npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type= --enabled-modules= ``` ### 方式二：本地运行 1. **克隆仓库** ```bash git clone https://github.com/cso1z/Feishu-MCP.git cd Feishu-MCP ``` 2. **配置环境变量(复制一份.env.example保存为.env文件)** 3. **编辑 .env 文件** 在项目根目录下找到并用任意文本编辑器打开 `.env` 文件，填写你的飞书应用凭证： ```env FEISHU_APP_ID=cli_xxxxx FEISHU_APP_SECRET=xxxxx PORT=3333 FEISHU_AUTH_TYPE=tenant/user FEISHU_ENABLED_MODULES=document,task ``` 4. **运行服务器** 方式一：本地运行 - **安装依赖** ```bash pnpm install ``` - **启动服务** ```bash pnpm run dev ``` 方式二：使用 Docker Compose - **启动服务** ```bash docker-compose up -d ``` - **查看日志** ```bash docker-compose logs -f ``` --- ## 🖥️ feishu-tool CLI 工具 从 `0.2.5` 版本起，`feishu-mcp` npm 包随附 `feishu-tool` 独立 CLI，可在终端、Shell 脚本或 AI Agent 中直接调用所有飞书工具，**无需启动 MCP 服务器**。 ### 安装 ```bash # 全局安装（推荐） npm install -g feishu-mcp@latest ``` ### 配置 ```bash # 1. 查看 CLI 概览（子命令 + 可用工具集） feishu-tool --help # 2. 查看初始化指南（获取 App ID / Secret 的步骤说明） feishu-tool guide # 3. 写入凭证 feishu-tool config set FEISHU_APP_ID cli_xxxxx # 4. 查看当前配置（确认写入正确） feishu-tool config # 5. 查看某个工具的详细参数 feishu-tool help create_feishu_document # 6. 调用工具 feishu-tool create_feishu_document '{"title": "测试文档"}' ``` > 完整参数说明请参阅 [Feishu-Skill 文档](https://github.com/cso1z/Feishu-Skill)。 --- ## ⚙️ 项目配置 ### 环境变量配置 | 变量名 | 必需 | 描述 | 默认值 | |--------|------|--------------------------------------------------------------------|-------| | `FEISHU_APP_ID` | ✅ | 飞书应用 ID | - | | `FEISHU_APP_SECRET` | ✅ | 飞书应用密钥 | - | | `PORT` | ❌ | 服务器端口 | `3333` | | `FEISHU_AUTH_TYPE` | ❌ | 认证凭证类型，使用 `user`（用户级,使用时是用户的身份操作飞书文档，需OAuth授权），使用 `tenant`（应用级，默认） | `tenant` | | `FEISHU_SCOPE_VALIDATION` | ❌ | 是否启用权限检查，设置为 `false` 可关闭权限检查（适用于仅使用部分功能的场景） | `true` | | `FEISHU_ENABLED_MODULES` | ❌ | 启用模块：`document`、`task`、`calendar`、`member`、`all`。task/calendar/member 需 user 认证 | `document` | | `FEISHU_USER_KEY` | ❌ | `stdio` 模式的用户标识，可通过命令行参数 `--user-key` 覆盖 | `stdio` | ### 功能模块说明 | 模块 | 说明 | 认证要求 | |------|------|----------| | `document` | 文档、文件夹、搜索等 | tenant / user | | `task` | 任务 CRUD | 仅 user | | `calendar` | 日历（开发中） | 仅 user | | `member` | 用户信息查询 | 仅 user | | `all` | 启用全部模块 | user 时全部加载 | ### 配置文件方式（适用于 Cursor、Cline 等） ``` { "mcpServers": { "feishu-mcp": { "command": "npx", "args": ["-y", "feishu-mcp@latest", "--stdio"], "env": { "FEISHU_APP_ID": "<你的飞书应用ID>", "FEISHU_APP_SECRET": "<你的飞书应用密钥>", "FEISHU_AUTH_TYPE": "", "FEISHU_ENABLED_MODULES": "document,task", "FEISHU_USER_KEY": "<你的用户标识>" } }, "feishu_local": { "url": "http://localhost:3333/sse?userKey=123456" } } } ``` **⚠️ 重要提示** : `http://localhost:3333/sse?userKey=123456` 中userKey表示连接用户的标识，是非常重要的配置，请填写并尽可能随机 --- ## 📝 使用贴士（重要） 1. ### **推荐指定文件夹**： 新建文档时，建议主动提供飞书文件夹 token（可为具体文件夹或根文件夹），这样可以更高效地定位和管理文档。如果不确定具体的子文件夹，可以让LLM自动在你指定的文件夹下查找最合适的子目录来新建文档。 > **如何获取文件夹 token？** > 打开飞书文件夹页面，复制链接（如 `https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx`），token 就是链接最后的那一串字符（如 `xxxxxxxxxxxxxxxxxxxxxx`，请勿泄露真实 token）。 2. ### **图片上传路径说明**： 本地运行 MCP 时，图片路径既支持本地绝对路径，也支持 http/https 网络图片；如在服务器环境，仅支持网络图片链接（由于cursor调用mcp时参数长度限制，暂不支持直接上传图片文件本体，请使用图片路径或链接方式上传）。 3. ### **公式使用说明**： 在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：`1+2=3`、`\frac{a}{b}`、`\sqrt{x}`等。支持在同一文本块中包含多个公式和普通文本。 4. ### **使用飞书user认证**： user认证与tenant认证在增加权限时是有区分的，所以**在初次由tenant切换到user时需要注意配置的权限**；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，**该值是用户的唯一标识 所以最好在设置时越随机越好** 5. ### **强烈建议使用user认证**： tenant认证有诸多限制，比如文件访问权限、飞书openapi兼容(不支持搜索wiki文档)、文档创建编辑记录等方面都不如user认证。 6. ### **任务与用户信息功能**： 想用 AI 帮你管理飞书任务（列出待办、创建任务、分配负责人）或查找同事信息？需要两步：① 使用 **user 认证**（tenant 模式下不提供这些能力）；② 在配置中设置 `FEISHU_ENABLED_MODULES=document,task`。启用 task 后，用户查询功能会自动可用，无需额外配置。 --- ## 🚨 故障排查 ### 权限问题排查 先对照配置问题查看： [手把手教程 FEISHU_CONFIG.md](FEISHU_CONFIG.md)。 #### 问题确认 1. **检查应用权限**：确保应用已获得必要的文档访问权限 2. **验证文档授权**：确认目标文档已授权给应用或应用所在的群组 3. **检查可用范围**：确保应用发布版本的可用范围包含文档所有者 #### 权限验证与排查 1. 获取token：[自建应用获取 app_access_token](https://open.feishu.cn/api-explorer?apiName=app_access_token_internal&project=auth&resource=auth&version=v3) 2. 使用第1步获取的token，验证是否有权限访问该文档：[获取文档基本信息](https://open.feishu.cn/api-explorer?apiName=get&project=docx&resource=document&version=v1) ### 常见问题 - **找不到应用**：检查应用是否已发布且可用范围配置正确 - **权限不足**：参考[云文档常见问题](https://open.feishu.cn/document/ukTMukTMukTM/uczNzUjL3czM14yN3MTN) - **知识库访问问题**：参考[知识库常见问题](https://open.feishu.cn/document/server-docs/docs/wiki-v2/wiki-qa) --- ## 📚 开发者 Wiki 详细的开发文档和技术指南，为学习者和贡献者提供全面的指导： - **[Wiki 首页](https://github.com/cso1z/Feishu-MCP/wiki)** - 完整的文档索引和快速导航 - **[架构设计](https://github.com/cso1z/Feishu-MCP/wiki/架构设计)** - 整体架构和技术栈说明 - **[核心模块详解](https://github.com/cso1z/Feishu-MCP/wiki/核心模块详解)** - 各模块的实现细节和代码示例 - **[认证与授权](https://github.com/cso1z/Feishu-MCP/wiki/认证与授权机制)** - Token 管理和多用户支持机制 - **[开发者指南](https://github.com/cso1z/Feishu-MCP/wiki/开发者指南)** - 环境搭建、开发流程、调试技巧 - **[API 参考](https://github.com/cso1z/Feishu-MCP/wiki/API-参考文档)** - 所有工具函数的详细文档 - **[最佳实践](https://github.com/cso1z/Feishu-MCP/wiki/最佳实践)** - 代码规范、性能优化、安全实践 - **[MCP 协议实现](https://github.com/cso1z/Feishu-MCP/wiki/MCP-协议实现)** - MCP 协议详解和传输层实现 --- ## 💖 支持项目 如果这个项目帮助到了你，请考虑： - ⭐ 给项目一个 Star - 🐛 报告 Bug 和问题 - 💡 提出新功能建议 - 📖 改进文档 - 🔀 提交 Pull Request 你的支持是我们前进的动力！ ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=cso1z/feishu-mcp&type=Timeline)](https://www.star-history.com/#cso1z/feishu-mcp&Timeline)