飞书 MCP 服务器

为 Cursor、Windsurf 和 Cline 提供基于 Model Context Protocol 的服务器实现，以访问、编辑和结构化飞书文档。

该项目使AI编码工具能够直接访问并理解飞书文档中的结构化内容，显著提高文档处理的智能性和效率。

全面覆盖飞书文档的实际使用过程，帮助您高效利用文档资源：

1. 获取文件夹目录快速访问和浏览飞书文档文件夹中的所有文档，便于整体管理和搜索。
2. 内容获取与理解支持多维度的内容读取，如结构化、分块和富文本，并且AI可以准确理解文档上下文。
3. 智能创建与编辑自动创建新文档，批量生成和编辑内容，满足多样化的写作需求。
4. 高效搜索与检索内置关键词搜索功能，帮助您在大量文档中快速找到目标信息。

该项目让您在日常使用飞书文档的过程中实现智能检索、编辑和搜索，提高内容处理效率和体验。

🎬 使用演示视频

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

<a href="https://www.bilibili.com/video/BV1z7MdzoEfu/?vd_source=94c14da5a71aeb01f665f159dd3d89c8"> <img src="image/demo.png" alt="飞书 MCP 使用演示" width="300"/> </a> <a href="https://www.bilibili.com/video/BV18z3gzdE1w/?vd_source=94c14da5a71aeb01f665f159dd3d89c8"> <img src="image/demo_1.png" alt="飞书 MCP 使用演示" width="300"/> </a>

⭐ 给项目点赞，第一时间获得最新特性和重要更新！ 关注项目可以帮助您不遗漏任何新特性、修复和优化，帮助您持续高效地使用。您的支持也将帮助我们更好地改进和发展项目。⭐

---

🛠️ 工具功能详情

功能类别	工具名称	描述	使用场景	状态
文档管理	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	搜索文档	查找特定内容	✅ 完成
工具功能	convert_feishu_wiki_to_document_id	维基链接转换	将维基链接转换为文档ID	✅ 完成
	get_feishu_image_resource	获取图像资源	从文档下载图像	✅ 完成
	get_feishu_whiteboard_content	获取绘图板内容	获取绘图板中的图形元素和结构（流程图、思维导图等）	✅ 完成
高级功能	create_feishu_table	创建和编辑表格	结构化数据展示	✅ 完成
	过程图插入	支持流程图和思维导图	过程组织和可视化	✅ 完成
图像插入	upload_and_bind_image_to_block	支持插入本地和远程图像	修改文档内容	✅ 完成
	公式支持	支持数学公式	学术和技术文档	✅ 完成

🎨 支持的样式特征（基本支持所有MD格式）

• 文本样式粗体、斜体、下划线、删除线、内联代码
• 文本颜色灰色、棕色、橙色、黄色、绿色、蓝色、紫色
• 对齐方式左对齐、居中、右对齐
• 标题级别支持1-9级标题
• 代码块支持多种编程语言的语法高亮
• 列表有序列表（编号）、无序列表（项目符号）
• 图像支持本地和网络图像
• 公式在文本块中插入数学公式，支持LaTeX语法
• Mermaid图表支持流程图、序列图、思维导图、类图、饼图等
• 表格支持创建多行多列的表格，单元格可以包含各种类型的内容，如文本、标题、列表、代码块等

---

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

• 简化工具集21个工具 → 13个工具，去除冗余，聚焦核心功能0.0.15 ✅
• 优化描述7000+token → 3000+token，简化提示，节省请求token0.0.15 ✅
• ~~批量增强增加批量更新和批量上传图像，单次操作效率提升50%~~0.0.15 ✅
• 流程优化减少多步骤调用，实现复杂任务的一键完成
• 支持多种凭证类型包括租户的access_token和用户的access_token，满足不同场景的认证要求(飞书应用配置变更) 0.0.16 ✅。
• 支持Cursor用户登录方便。无需在Cursor平台上验证用户 ❌
• 支持Mermaid图表流程图、序列图等，丰富文档内容0.1.11 ✅
• 支持表格创建创建包含各种块类型的复杂表格，支持样式控制0.1.2 ✅
• 支持飞书多用户用户认证一人部署，多人使用0.1.3 ✅
• 支持用户_access_token的自动刷新无需频繁授权，提升用户体验0.1.6 ✅

---

🔧 飞书配置教程

⚠️ 重要提醒：在开始使用前，需要完成飞书应用配置，否则此工具无法正常使用。

关于如何创建飞书应用并获取应用凭证，请参见官方教程。

详细的飞书应用配置步骤对于注册飞书应用、配置权限以及添加文档访问权限的详细指南，请参考 手把手教程 FEISHUVNet.md。

---

🏃‍♂️ 快速开始

方法1：使用NPM快速运行

npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type=<tenant/user>

方法2：本地运行

1. 克隆仓库

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

2. 安装依赖

   pnpm install
   

3. 配置环境变量（复制.env.example文件并保存为.env文件）

4. 编辑.env文件 在项目的根目录中使用任何文本编辑器打开.env文件，填写您的飞书应用凭证：

   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   PORT=3333
   FEISHU_AUTH_TYPE=tenant/user
   

5. 运行服务器

   pnpm run dev
   

⚙️ 项目配置

环境变量配置

变量名称	必填	描述	默认值
FEISHU_APP_ID	✅	飞书应用ID	-
FEISHU_APP_SECRET	✅	飞书应用密钥	-
PORT	❌	服务器端口	3333
FEISHU_AUTH_TYPE	❌	认证证书类型，使用user(用户级别，当作为用户操作飞书文档时需要OAuth授权)，使用tenant(应用级别，默认)	tenant

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

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_AUTH_TYPE": "<tenant/user>"
      }
    },
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=123456"
    }
  }
}

---

📝 使用提示（重要）

1. 建议指定一个文件夹：

   创建新文档时，建议主动提供飞书文件夹令牌（可以是特定文件夹或根文件夹），这可以更有效地定位和管理文档。如果您不确定具体的子文件夹，LLM可以自动搜索您指定的文件夹中最合适的子文件夹来创建新文档。

   如何获取文件夹令牌？ 打开飞书文件夹页面并复制链接（例如 https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx）令牌是链接中的最后一个字符串（例如 xxxxxxxxxxxxxxxxxxxxxx）。请勿泄露真实的令牌。

2. 图像上传路径说明：

   当本地运行MCP时，图像路径支持本地绝对路径和http/https网络图像；在服务器环境中，仅支持网络图像链接（由于Cursor调用MCP时参数长度限制，目前不支持直接上传图像文件，请使用图像路径或链接方法进行上传）。

3. 公式使用说明：

   正常文本和公式元素可以在文本块中混合使用。公式使用LaTeX语法，例如：1+2=3、\frac{a}{b}、\sqrt{x}等。支持同一文本块内的多个公式和普通文本。

4. 使用飞书用户认证：

   添加权限时区分用户认证和租户认证，因此首次从租户切换到用户时，需要注意配置的权限为了区分不同的用户，需要在MCP服务器服务配置的URL中添加查询参数userKey，这个值是用户的唯一标识符，最好随机设置

---

🚨 故障排除

权限问题故障排除

首先检查配置问题：手把手教程 FEISHUVNet.md。

问题确认

1. 检查应用权限确保应用已获得必要的文档访问权限
2. 验证文档授权确认目标文档已被授权给应用或应用所在的组
3. 检查可用范围确保应用发布版本的可用范围包括文档所有者

权限验证和故障排除

1. 获取令牌：构建自建应用以获取app_access_token
2. 使用第1步获取的令牌验证是否有权限访问文档：获取文档基本信息

常见问题

• 应用未找到检查应用是否已发布且可用范围配置正确
• 权限不足参考云文档常见问题
• 知识库访问问题参考知识库常见问题

---

📚 开发者Wiki

详细的开发文档和技术指南为学习者和贡献者提供了全面的指导：

• Wiki首页 -完整的文档索引和快速导航
• 架构设计 -总体架构和技术栈描述
• 核心模块详细解释 -每个模块的实现细节和代码示例
• 认证和授权 -令牌管理和多用户支持机制
• 开发者指南 -环境搭建、开发流程、调试技巧
• API参考文档 -所有实用函数的详细文档
• 最佳实践 -代码标准化、性能优化和安全实践
• MCP协议实现 -MCP协议解释和传输层实现

---

💖 支持项目

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

• ⭐ 给项目点赞
• 🐛 报告错误和问题
• 💡 提出新功能建议
• 📖 改进文档
• 🔀 提交Pull Request

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

Star历史