飞书 MCP 服务器

为 Cursor、Windsurf、Cline 和其他 AI 驱动的编码工具提供访问、编辑和结构化处理飞书文档的能力，基于 Model Context Protocol 服务器实现。

本项目让 AI 编码工具能够直接获取和理解飞书文档的结构化内容，显著提升文档处理的智能化和效率。

完整覆盖飞书文档的真实使用流程，助你高效利用文档资源：

1. 文件夹目录获取：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。

2. 内容获取与理解：支持结构化、分块、富文本等多维度内容读取，AI 能精准理解文档上下文。

3. 智能创建与编辑：可自动创建新文档、批量生成和编辑内容，满足多样化写作需求。

4. 高效检索与搜索：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。

本项目让你在飞书文档的日常使用流程中实现智能获取、编辑和搜索，提升内容处理效率和体验。

🎬 使用演示视频

你可以通过以下视频了解 MCP 的实际使用效果和操作流程：

⭐ Star 本项目，第一时间获取最新功能和重要更新！ 关注项目可以让你不错过任何新特性、修复和优化，助你持续高效使用。你的支持也将帮助我们更好地完善和发展项目。⭐

🛠️ 工具功能详情

🎨 支持的样式功能（基本支持md所有格式）

• 文本样式：粗体、斜体、下划线、删除线、行内代码

• 文本颜色：灰色、棕色、橙色、黄色、绿色、蓝色、紫色

• 对齐方式：左对齐、居中、右对齐

• 标题级别：支持1-9级标题

• 代码块：支持多种编程语言语法高亮

• 列表：有序列表（编号）、无序列表（项目符号）

• 图片：支持本地图片和网络图片

• 公式：在文本块中插入数学公式，支持LaTeX语法

• mermaid图表：支持流程图、时序图、思维导图、类图、饼图等等

• 表格：支持创建多行列表格，单元格可包含文本、标题、列表、代码块等多种内容类型

📈 一周计划：提升工具效率

• 精简工具集 0.0.15 ✅

• 优化描述 0.0.15 ✅

• 批量增强 0.0.15 ✅

• 流程优化：减少多步调用，实现一键完成复杂任务

• 支持多种凭证类型 (飞书应用配置发生变更) 0.0.16 ✅。

• 支持cursor用户登录：方便在cursor平台用户认证

• 支持mermaid图表 0.1.11 ✅

• 支持表格创建 0.1.2 ✅

🔧 飞书配置教程

⚠️ 重要提示：在开始使用之前，必须先完成飞书应用配置，否则无法正常使用本工具。

关于如何创建飞书应用和获取应用凭证的说明可以在官方教程找到。

详细的飞书应用配置步骤：有关注册飞书应用、配置权限、添加文档访问权限的详细指南，请参阅 手把手教程 FEISHU_CONFIG.md。

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

方式二：使用 Smithery 平台

已发布到 Smithery 平台，可访问： https://smithery.ai/server/@cso1z/feishu-mcp

方式三：本地运行

🌿 分支说明

本项目采用主分支（main）+功能分支（feature/xxx）协作模式：

• main
  稳定主线分支，始终保持可用、可部署状态。所有已验证和正式发布的功能都会合并到 main 分支。

• multi-user-token

  多用户隔离与按用户授权的 Feishu Token 获取功能开发分支。该分支支持 userKey 参数、按用户获取和缓存 Token、自定义 Token 服务等高级特性，适用于需要多用户隔离和授权场景的开发与测试。

  ⚠️ 该分支为 beta 版本，功能更新相较 main 分支可能会有延后。如有相关需求请在 issue 区留言，我会优先同步最新功能到该分支。

1. 克隆仓库

   git clone https://github.com/cso1z/Feishu-MCP.git cd Feishu-MCP

2. 安装依赖

   pnpm install

3. 配置环境变量(复制一份.env.example保存为.env文件)

   macOS/Linux:

   cp .env.example .env

   Windows:

   copy .env.example .env

4. 编辑 .env 文件 在项目根目录下找到并用任意文本编辑器打开 .env 文件，填写你的飞书应用凭证：

   FEISHU_APP_ID=cli_xxxxx FEISHU_APP_SECRET=xxxxx PORT=3333

5. 运行服务器

   pnpm run dev

⚙️ 项目配置

环境变量配置

注意：

• 只有本地运行服务时支持 user 凭证，否则需配置 FEISHU_TOKEN_ENDPOINT，自行实现 token 获取与管理（可参考 callbackService、feishuAuthService）。

• FEISHU_TOKEN_ENDPOINT 接口参数：client_id, client_secret, token_type（可选，tenant/user）；返回参数：access_token, needAuth, url（需授权时）, expires_in（单位:s）。

命令行参数

配置文件方式（适用于 Cursor、Cline 等）

📝 使用贴士（重要）

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}等。支持在同一文本块中包含多个公式和普通文本。

🚨 故障排查

权限问题排查

先对照配置问题查看： 手把手教程 FEISHU_CONFIG.md。

问题确认

1. 检查应用权限：确保应用已获得必要的文档访问权限

2. 验证文档授权：确认目标文档已授权给应用或应用所在的群组

3. 检查可用范围：确保应用发布版本的可用范围包含文档所有者

权限验证与排查

1. 获取token：自建应用获取 app_access_token

2. 使用第1步获取的token，验证是否有权限访问该文档：获取文档基本信息

常见问题

• 找不到应用：检查应用是否已发布且可用范围配置正确

• 权限不足：参考云文档常见问题

• 知识库访问问题：参考知识库常见问题

💖 支持项目

如果这个项目帮助到了你，请考虑：

• ⭐ 给项目一个 Star

• 🐛 报告 Bug 和问题

• 💡 提出新功能建议

• 📖 改进文档

• 🔀 提交 Pull Request

你的支持是我们前进的动力！

Star History