飞书 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+→3000+ tokens，简化提示 0.0.15 ✅
批量增强：新增批量更新/图片上传，效率提升50% 0.0.15 ✅
流程优化：减少多步调用，一键完成复杂任务
多凭证支持：tenant/user_access_token 0.0.16 ✅
mermaid支持：流程图/时序图等 0.1.11 ✅
表格创建：支持复杂表格样式 0.1.2 ✅
多用户认证：一人部署，多人使用 0.1.3 ✅
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并编辑：

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>"
      }
    }
  }
}

📝 使用建议

推荐指定文件夹：新建文档时建议提供文件夹token（可为根文件夹），便于高效管理。如不确定子文件夹，可让AI自动查找最合适位置。

获取文件夹token：打开飞书文件夹，复制链接中的xxxxxxxxxxxxxxxxxxxxxx部分（请勿泄露真实token）。
图片上传路径说明：

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

文本块中可混合使用普通文本与公式元素。公式采用 LaTeX 语法，例如：1+2=3、\frac{a}{b}、\sqrt{x} 等。支持在同一文本块内嵌入多个公式与普通文本内容。
飞书用户认证配置：

用户认证与租户认证在权限配置上存在差异，首次从租户切换至用户认证时需特别注意权限设置；为区分不同用户，需在配置 MCP 服务 URL 时添加 userKey 查询参数，该值作为用户唯一标识，建议设置时尽可能保持随机性

🚨 故障排查指南

权限问题排查

建议首先对照配置文档检查：飞书配置教程 FEISHU_CONFIG.md。

问题确认步骤

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

权限验证流程

获取访问令牌：自建应用获取 app_access_token
使用上述令牌验证文档访问权限：获取文档基本信息

常见问题解答

应用不可见：检查应用是否已发布且可用范围配置正确
权限不足：参考云文档常见问题指南
知识库访问异常：查阅知识库问题解决方案

📚 开发者知识库

提供完整的开发文档与技术指南，助力开发者快速上手：

Wiki 首页 - 文档索引与快速导航
系统架构 - 整体架构与技术栈解析
核心模块 - 各模块实现细节与代码示例
认证体系 - Token 管理与多用户支持机制
开发指南 - 环境搭建与调试技巧
API 文档 - 完整接口参考手册
最佳实践 - 代码规范与性能优化方案
MCP 协议 - 协议详解与传输层实现

💡 小贴士: 您也可以通过 GitHub Wiki 浏览文档。GitHub Wiki 设置方法请参考配置指南。

💖 项目支持

如果您觉得这个项目有价值，欢迎：

⭐ 为项目点亮 Star
🐛 提交问题报告
💡 提议新功能
📖 协助完善文档
🔀 贡献代码

您的支持是我们持续改进的动力！