飞书 MCP 服务器

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

现已支持 `feishu-tool` 独立 CLI 工具，可在终端或脚本中直接调用所有飞书工具，无需启动 MCP 服务器。配合 Feishu-Skill 可让 Claude Code 等 AI Agent 自动选择最合适的方式操作飞书。

本项目让 AI 编码工具能够：

• 文档处理：直接获取、理解、创建和编辑飞书文档，显著提升文档处理的智能化和效率
• 任务管理：列取、创建、更新、删除飞书任务，支持子任务和成员管理（需 user 认证）
• 用户信息：按名称搜索或按 ID 批量获取飞书用户，便于任务分配和文档协作（需 user 认证）

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

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

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

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

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

5. 任务管理与用户查询：支持飞书任务 CRUD 及用户信息搜索，便于在文档中关联任务和人员。

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

💡项目推荐：

使用 Claude Code 推荐配合 claude-ip-guard —— 自动检测 IP 地理位置并拦截受限地区访问，防止因网络切换导致 Claude 封号。

🎬 使用演示视频

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

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

🛠️ 工具功能详情

🎨 支持的样式功能（基本支持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、leeeezx、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，指导 Claude Code 等 AI Agent 在合适场景下使用 feishu-mcp CLI~~ 0.2.6 ✅

🔧 飞书配置教程

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

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

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

🏃‍♂️ 快速开始

方式一：使用 NPM 快速运行

npx feishu-mcp@latest --feishu-app-id= --feishu-app-secret= --feishu-auth-type= --enabled-modules=

方式二：本地运行

1. 克隆仓库

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

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

3. 编辑 .env 文件

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

FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   PORT=3333
   FEISHU_AUTH_TYPE=tenant/user
   FEISHU_ENABLED_MODULES=document,task

4. 运行服务器

方式一：本地运行

pnpm install

pnpm run dev

方式二：使用 Docker Compose

docker-compose up -d

docker-compose logs -f

🖥️ feishu-tool CLI 工具

从 `0.2.5` 版本起，`feishu-mcp` npm 包随附 `feishu-tool` 独立 CLI，可在终端、Shell 脚本或 AI Agent 中直接调用所有飞书工具，无需启动 MCP 服务器。

安装

# 全局安装（推荐）
npm install -g feishu-mcp@latest

配置

# 1. 查看 CLI 概览（子命令 + 可用工具集）
feishu-tool --help

# 2. 查看初始化指南（获取 App ID / Secret 的步骤说明）
feishu-tool guide

# 3. 写入凭证
feishu-tool config set FEISHU_APP_ID cli_xxxxx
feishu-tool config set FEISHU_USER_KEY "$(node -e 'console.log(crypto.randomUUID())')"
# FEISHU_USER_KEY 建议每个本地用户或客户端保持唯一

# 4. 查看当前配置（确认写入正确）
feishu-tool config

# 5. 查看某个工具的详细参数
feishu-tool help create_feishu_document

# 6. 调用工具
feishu-tool create_feishu_document '{"title": "测试文档"}'

> 完整参数说明请参阅 Feishu-Skill 文档。

⚙️ 项目配置

环境变量配置

功能模块说明

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

stdio 模式（推荐）

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "",
        "FEISHU_APP_SECRET": "",
        "FEISHU_AUTH_TYPE": "",
        "FEISHU_ENABLED_MODULES": "document,task",
        "FEISHU_USER_KEY": ""
      }
    }
  }
}

SSE 模式

{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=123456"
    }
  }
}

HTTP Streamable 模式

{
  "mcpServers": {
    "feishu_streamable": {
      "url": "http://localhost:3333/mcp?userKey=123456"
    }
  }
}

Bearer Token 认证（可选）

当配置了 `MCP_BEARER_TOKEN` 环境变量后，所有 HTTP/SSE/StreamableHTTP 端点将要求请求携带 `Authorization: Bearer ` 头。适用于公网部署场景，防止未授权访问。

配置示例：

# .env 文件
MCP_BEARER_TOKEN=your-secret-token-here

客户端配置示例（SSE 模式 + Bearer 认证）：

> ⚠️ 目前大多数 MCP 客户端（如 Cursor、Cline）不支持在 SSE/StreamableHTTP 连接中自定义请求头。如需使用 Bearer 认证，请确认你的客户端支持传递 `Authorization` 头，或通过反向代理（如 Nginx）在服务端前置认证。

对于支持自定义头的客户端或 API 调用：

# SSE 连接示例
curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3333/sse?userKey=123456

# StreamableHTTP 请求示例
curl -X POST -H "Authorization: Bearer your-secret-token-here" -H "Content-Type: application/json" http://localhost:3333/mcp?userKey=123456

⚠️ 重要提示 : URL 中的 `userKey` 表示连接用户的标识，是非常重要的配置，请填写并尽可能随机

userKey 传递方式：支持两种方式传递用户标识

• URL 查询参数：`?userKey=123456`（推荐，配置简单）
• 请求头：`user-key: 123456`（适合需要隐藏参数的场景）

📝 使用贴士（重要）

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时需要注意配置的权限；为了区分不同的用户需要传递用户标识 userKey，支持两种方式：

该值是用户的唯一标识，所以最好在设置时越随机越好

5. ### 强烈建议使用user认证：

tenant认证有诸多限制，比如文件访问权限、飞书openapi兼容(不支持搜索wiki文档)、文档创建编辑记录等方面都不如user认证。

6. ### 任务与用户信息功能：

想用 AI 帮你管理飞书任务（列出待办、创建任务、分配负责人）或查找同事信息？需要两步：① 使用 user 认证（tenant 模式下不提供这些能力）；② 在配置中设置 `FEISHU_ENABLED_MODULES=document,task`。启用 task 后，用户查询功能会自动可用，无需额外配置。

7. ### 使用 Lark 国际版：

飞书国内版无需额外配置。如果你的团队使用 Lark 国际版或自建飞书服务，需额外设置：

FEISHU_BASE_URL=https://open.larksuite.com/open-apis
   FEISHU_AUTH_BASE_URL=https://accounts.larksuite.com

8. ### 内网访问、外网回调分离：

如果 MCP 客户端通过内网地址访问服务（例如 `http://feishu-mcp:3333/mcp`），但飞书 OAuth 回调必须使用公网域名，可额外设置：

FEISHU_PUBLIC_BASE_URL=https://somo-feishu-mcp.yfgao.net

这样客户端仍可继续连接内网地址，而返回给用户的授权链接会使用 `https://somo-feishu-mcp.yfgao.net/callback` 作为回调地址。

9. ### 多租户中转架构下的 userKey 动态切换：

在多租户中转架构下，系统通过集成管理工具统一代理飞书 MCP 服务。由于底层 MCP 服务实例在会话层存在复用，不同用户的请求实际上运行在共享的 Session 上下文中。因此，系统需支持基于请求头透传的 `user-key` 进行动态切换，以实现租户身份的隔离与上下文注入，从而满足多用户并发访问的需求。

如何切换 userKey：

> 注意：此功能仅在 HTTP Streamable 模式下有效，SSE 和 stdio 模式不支持动态切换。

🚨 故障排查

权限问题排查

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

问题确认

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

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

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

权限验证与排查

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

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

常见问题

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

📚 开发者 Wiki

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

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

💖 支持项目

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

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

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

Star History