飞书 MCP 服务器

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

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

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

文件夹目录获取：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。
内容获取与理解：支持结构化、分块、富文本等多维度内容读取，AI 能精准理解文档上下文。
智能创建与编辑：可自动创建新文档、批量生成和编辑内容，满足多样化写作需求。
高效检索与搜索：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。

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

🎬 使用演示视频

你可以通过以下视频了解 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`	搜索文档	查找特定内容	✅ 已完成
工具功能	`convert_feishu_wiki_to_document_id`	Wiki链接转换	将Wiki链接转为文档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+ 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 ✅

🔧 飞书配置教程

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

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

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

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

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

方式二：本地运行

克隆仓库

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

安装依赖
```
pnpm install
```
配置环境变量(复制一份.env.example保存为.env文件)
编辑 .env 文件 在项目根目录下找到并用任意文本编辑器打开 .env 文件，填写你的飞书应用凭证：
```
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
PORT=3333
FEISHU_AUTH_TYPE=tenant/user
```
运行服务器
```
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"
    }
  }
}

📝 使用贴士（重要）

推荐指定文件夹：

新建文档时，建议主动提供飞书文件夹 token（可为具体文件夹或根文件夹），这样可以更高效地定位和管理文档。如果不确定具体的子文件夹，可以让LLM自动在你指定的文件夹下查找最合适的子目录来新建文档。

如何获取文件夹 token？ 打开飞书文件夹页面，复制链接（如 https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx），token 就是链接最后的那一串字符（如 xxxxxxxxxxxxxxxxxxxxxx，请勿泄露真实 token）。
图片上传路径说明：

本地运行 MCP 时，图片路径既支持本地绝对路径，也支持 http/https 网络图片；如在服务器环境，仅支持网络图片链接（由于cursor调用mcp时参数长度限制，暂不支持直接上传图片文件本体，请使用图片路径或链接方式上传）。
公式使用说明：

在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：1+2=3、\frac{a}{b}、\sqrt{x}等。支持在同一文本块中包含多个公式和普通文本。
使用飞书user认证：

user认证与tenant认证在增加权限时是有区分的，所以在初次由tenant切换到user时需要注意配置的权限；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，该值是用户的唯一标识所以最好在设置时越随机越好

🚨 故障排查

权限问题排查

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

问题确认

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

权限验证与排查

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

常见问题

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

📚 开发者 Wiki

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

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

💖 支持项目

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

⭐ 给项目一个 Star
🐛 报告 Bug 和问题
💡 提出新功能建议
📖 改进文档
🔀 提交 Pull Request

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

Star History

飞书 MCP 服务器

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

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

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

文件夹目录获取：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。
内容获取与理解：支持结构化、分块、富文本等多维度内容读取，AI 能精准理解文档上下文。
智能创建与编辑：可自动创建新文档、批量生成和编辑内容，满足多样化写作需求。
高效检索与搜索：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。

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

🎬 使用演示视频

你可以通过以下视频了解 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`	搜索文档	查找特定内容	✅ 已完成
工具功能	`convert_feishu_wiki_to_document_id`	Wiki链接转换	将Wiki链接转为文档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+ 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 ✅

🔧 飞书配置教程

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

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

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

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

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

方式二：本地运行

克隆仓库

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

安装依赖
```
pnpm install
```
配置环境变量(复制一份.env.example保存为.env文件)
编辑 .env 文件 在项目根目录下找到并用任意文本编辑器打开 .env 文件，填写你的飞书应用凭证：
```
FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
PORT=3333
FEISHU_AUTH_TYPE=tenant/user
```
运行服务器
```
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"
    }
  }
}

📝 使用贴士（重要）

推荐指定文件夹：

新建文档时，建议主动提供飞书文件夹 token（可为具体文件夹或根文件夹），这样可以更高效地定位和管理文档。如果不确定具体的子文件夹，可以让LLM自动在你指定的文件夹下查找最合适的子目录来新建文档。

如何获取文件夹 token？ 打开飞书文件夹页面，复制链接（如 https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx），token 就是链接最后的那一串字符（如 xxxxxxxxxxxxxxxxxxxxxx，请勿泄露真实 token）。
图片上传路径说明：

本地运行 MCP 时，图片路径既支持本地绝对路径，也支持 http/https 网络图片；如在服务器环境，仅支持网络图片链接（由于cursor调用mcp时参数长度限制，暂不支持直接上传图片文件本体，请使用图片路径或链接方式上传）。
公式使用说明：

在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：1+2=3、\frac{a}{b}、\sqrt{x}等。支持在同一文本块中包含多个公式和普通文本。
使用飞书user认证：

user认证与tenant认证在增加权限时是有区分的，所以在初次由tenant切换到user时需要注意配置的权限；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，该值是用户的唯一标识所以最好在设置时越随机越好

🚨 故障排查

权限问题排查

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

问题确认

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

权限验证与排查

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

常见问题

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

📚 开发者 Wiki

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

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

💖 支持项目

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

⭐ 给项目一个 Star
🐛 报告 Bug 和问题
💡 提出新功能建议
📖 改进文档
🔀 提交 Pull Request

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

Feishu MCP Server

README Documentation

飞书 MCP 服务器

🎬 使用演示视频

🛠️ 工具功能详情

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

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

🔧 飞书配置教程

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

方式二：本地运行

⚙️ 项目配置

环境变量配置

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

📝 使用贴士（重要）

推荐指定文件夹：

图片上传路径说明：

公式使用说明：

使用飞书user认证：

🚨 故障排查

权限问题排查

问题确认

权限验证与排查

常见问题

📚 开发者 Wiki

💖 支持项目

Star History

Quick Install

Quick Actions

Key Features

Feishu MCP Server

README Documentation

飞书 MCP 服务器

🎬 使用演示视频

🛠️ 工具功能详情

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

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

🔧 飞书配置教程

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

方式二：本地运行

⚙️ 项目配置

环境变量配置

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

📝 使用贴士（重要）

推荐指定文件夹：

图片上传路径说明：

公式使用说明：

使用飞书user认证：

🚨 故障排查

权限问题排查

问题确认

权限验证与排查

常见问题

📚 开发者 Wiki

💖 支持项目

Star History

Quick Install

Quick Actions

Key Features