feishu-docx-mcp

v0.2.2

Published

23 days ago

Model Context Protocol server for Feishu integration

0High
0Medium
0Low

ham1912

feishu lark mcp typescript

飞书 MCP 服务器（增强版）

本项目基于 cso1z/Feishu-MCP 开源项目改造而来，在原有功能基础上进行了大量增强，主要面向 Claude Code 等 AI 编码工具的深度集成场景。感谢原作者的出色工作。

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

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

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

文件夹目录获取：快速获取和浏览飞书文档文件夹下的所有文档，便于整体管理和查找。
内容获取与理解：支持 Markdown、大纲、关键字搜索等多维度内容读取，AI 能精准理解文档上下文。
智能创建与编辑：可自动创建新文档、批量生成和编辑内容，支持 Markdown 级别的章节替换与追加。
高效检索与搜索：内置关键字搜索，帮助你在大量文档中迅速找到目标信息。

🆕 相对原版的改造内容

本 fork 在原版基础上新增了以下功能，主要提升 AI 对文档的深度理解和高效编辑能力：

1. Markdown 输出与 Feishu Link Tags

重构文档读取输出格式，引入 <feishu:image>、<feishu:whiteboard> 等语义标签，替代原来的纯文本/块 JSON 输出。AI 可直接获得结构化的 Markdown，保留图片、白板、Mermaid 等非文本元素的引用。

2. Extra 富文本增强区

在文档读取结果末尾附加 <extra> 区块，包含：

图片 AI 描述：自动调用视觉模型分析文档中的图片内容（需配置 IMAGE_AI_PROVIDER）
群聊卡片信息：解析 chat_card 块，输出群名称与描述
@ 提及用户：解析 mention_user 元素，输出用户显示名

3. 白板转 PlantUML

自动将飞书文档中的白板内容转换为 PlantUML 格式（支持流程图、时序图、状态图、类图、思维导图等），AI 可直接理解白板中的图形逻辑。

4. 多维表格（Bitable）记录读取

支持读取嵌入式多维表格的记录数据，在 extra 区块中输出字段与行内容。

5. Markdown 级别文档编辑（新增两个工具）

append_markdown_to_document：将 Markdown 内容追加到文档末尾或指定位置
replace_feishu_document_section：按标题定位章节，整体替换为新 Markdown 内容；保留图片/文件引用（feishu://media/TOKEN）

6. 文件附件上传（新增工具）

upload_file_to_document：上传本地或远程文件到文档，支持 PDF 预览模式

7. 块索引精准查询（新增两个工具）

lookup_block：按语义 key 查询块的完整 JSON 数据
lookup_block_index：获取块的父 ID、兄弟位置，用于精准插入/删除

8. 工具精简

移除了以下工具，避免冗余调用：

get_feishu_whiteboard_content（功能已内置到 extra 区块）
get_feishu_image_resource（功能已内置到 extra 区块）
copy_feishu_document（实验性功能，已下线）

9. Claude Code 配套 Skill

提供 feishu-mcp-workflows skill，涵盖 19 个工具的完整工作流与最佳实践，专为 Claude Code 用户优化（见下方配套 Skill）。

⭐ Star 本项目，第一时间获取最新功能和重要更新！

🛠️ 工具功能详情（19 个工具）

npm 包名：feishu-docx-mcp

| 功能类别 | 工具名称 | 描述 | 状态 | |---------|--------|------|------| | 文档管理 | create_feishu_document | 创建新的飞书文档（支持 Drive 文件夹和 Wiki 空间） | ✅ | | | get_feishu_document_info | 获取文档基本信息；Wiki 链接转文档 ID | ✅ | | | get_feishu_document_blocks | 获取文档内容（Markdown/大纲/关键字搜索模式） | ✅ | | Markdown 编辑 🆕 | append_markdown_to_document | 将 Markdown 内容追加到文档末尾或指定位置 | ✅ | | | replace_feishu_document_section | 按标题定位章节，整体替换为新 Markdown | ✅ | | 块级编辑 | batch_create_feishu_blocks | 批量创建多个块（文本/标题/代码/列表/图片/Mermaid/白板/表格） | ✅ | | | update_feishu_block_text | 更新已有块的文本内容和样式 | ✅ | | | delete_feishu_document_blocks | 删除文档块 | ✅ | | 块索引查询 🆕 | lookup_block | 按语义 key 查询块的完整 JSON 数据 | ✅ | | | lookup_block_index | 获取块的父 ID 和兄弟位置，用于精准插入/删除 | ✅ | | 图片 & 文件 | upload_and_bind_image_to_block | 上传本地或远程图片并绑定到图片块 | ✅ | | 🆕 | upload_file_to_document | 上传文件附件到文档（支持 PDF 预览） | ✅ | | 表格 | create_feishu_table | 创建多行列表格，单元格支持多种块类型 | ✅ | | 白板 | fill_whiteboard_with_plantuml | 向白板块填充 PlantUML 或 Mermaid 图表 | ✅ | | 文件夹管理 | get_feishu_root_folder_info | 获取根文件夹、知识库空间列表 | ✅ | | | get_feishu_folder_files | 获取文件夹/Wiki 节点下的文件列表 | ✅ | | | create_feishu_folder | 创建新文件夹 | ✅ | | 搜索 | search_feishu_documents | 关键字搜索文档和 Wiki 节点 | ✅ |

🎨 支持的样式功能

文本样式：粗体、斜体、下划线、删除线、行内代码
文本颜色：灰色、棕色、橙色、黄色、绿色、蓝色、紫色
对齐方式：左对齐、居中、右对齐
标题级别：支持1-9级标题
代码块：支持多种编程语言语法高亮
列表：有序列表（编号）、无序列表（项目符号）
图片：支持本地图片和网络图片
文件附件：支持任意格式文件，PDF 支持预览模式
公式：在文本块中插入数学公式，支持LaTeX语法
Mermaid图表：支持流程图、时序图、思维导图、类图、饼图等
表格：支持创建多行列表格，单元格可包含文本、标题、列表、代码块等多种内容类型
飞书文档画板：支持飞书文档的画板创建，提供更丰富和多样化的内容

🤖 配套 Claude Code Skill

本项目为 Claude Code 用户提供了配套的 feishu-mcp-workflows skill，涵盖所有 19 个工具的完整工作流与最佳实践。

安装方式

将 .claude/skills/feishu-mcp-workflows.zip 下载后，通过 Claude Code 安装：

# 下载 skill 压缩包
# 在 Claude Code 中安装：
/skills install feishu-mcp-workflows.zip

或者直接将 .claude/skills/feishu-mcp-workflows/ 目录复制到你项目的 .claude/skills/ 下。

Skill 内容

该 skill 包含：

所有工具的参数说明与使用示例
推荐工作流（读取文档 → 按章节编辑 → 精准块操作）
lookup_block / lookup_block_index 块索引查询工作流
图片、文件上传最佳实践
Wiki 知识库操作指南
常见场景的完整操作链路

在使用飞书 MCP 工具前调用此 skill，可显著减少试错次数，提升操作准确率。

🔧 飞书配置教程

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

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

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

🏃‍♂️ 快速开始

方式一：NPM 直接使用（推荐）

npx feishu-docx-mcp --stdio

在 Claude Code、Cursor、Cline 等工具中，将以下配置加入 MCP 配置文件：

{
  "mcpServers": {
    "feishu-docx-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-docx-mcp", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "cli_xxxxxxxxxx",
        "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx"
      }
    }
  }
}

如需启用图片 AI 分析功能，额外添加以下可选配置：

{
  "env": {
    "FEISHU_APP_ID": "cli_xxxxxxxxxx",
    "FEISHU_APP_SECRET": "xxxxxxxxxxxxxxxx",
    "IMAGE_AI_PROVIDER": "anthropic",
    "IMAGE_AI_API_KEY": "sk-ant-xxxxxxxx",
    "IMAGE_AI_MODEL": "claude-haiku-4-5-20251001",
    "IMAGE_AI_MAX_IMAGES": "10"
  }
}

方式二：本地源码运行

克隆仓库

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

配置环境变量（复制 .env.example 为 .env）

编辑 .env 文件

FEISHU_APP_ID=cli_xxxxx
FEISHU_APP_SECRET=xxxxx
FEISHU_AUTH_TYPE=tenant/user

安装依赖并启动

pnpm install
pnpm run dev

或使用 Docker Compose：

docker-compose up -d
docker-compose logs -f

⚙️ 项目配置

环境变量配置

| 变量名 | 必需 | 描述 | 默认值 | |--------|------|------|-------| | FEISHU_APP_ID | ✅ | 飞书应用 ID | - | | FEISHU_APP_SECRET | ✅ | 飞书应用密钥 | - | | FEISHU_AUTH_TYPE | ❌ | 认证类型：tenant（应用级，默认）或 user（用户级，需 OAuth 授权） | tenant | | PORT | ❌ | HTTP 模式服务器端口 | 3333 | | IMAGE_AI_PROVIDER | ❌ | 图片 AI 分析服务商（目前支持 anthropic） | - | | IMAGE_AI_API_KEY | ❌ | 图片 AI 服务 API Key | - | | IMAGE_AI_MODEL | ❌ | 图片 AI 使用的模型 | - | | IMAGE_AI_MAX_IMAGES | ❌ | 每次文档读取最多分析的图片数量 | 5 |

HTTP 模式配置（多用户 SSE 服务）

如需以 HTTP 服务方式运行（支持多用户共享），在 MCP 配置中使用：

{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=<随机字符串>"
    }
  }
}

⚠️ 重要提示：userKey 是用户唯一标识，请使用随机字符串，避免与其他用户冲突。

📝 使用贴士（重要）

推荐指定文件夹：
新建文档时，建议主动提供飞书文件夹 token（可为具体文件夹或根文件夹），这样可以更高效地定位和管理文档。如果不确定具体的子文件夹，可以让LLM自动在你指定的文件夹下查找最合适的子目录来新建文档。
如何获取文件夹 token？ 打开飞书文件夹页面，复制链接（如 https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx），token 就是链接最后的那一串字符（如 xxxxxxxxxxxxxxxxxxxxxx，请勿泄露真实 token）。
Markdown 编辑优先：
编辑已有文档时，优先使用 get_feishu_document_blocks（outline 模式）查看大纲，再用 replace_feishu_document_section 按标题替换章节内容，比逐块操作效率高得多。
图片上传路径说明：
本地运行 MCP 时，图片路径既支持本地绝对路径，也支持 http/https 网络图片；如在服务器环境，仅支持网络图片链接（由于cursor调用mcp时参数长度限制，暂不支持直接上传图片文件本体，请使用图片路径或链接方式上传）。
公式使用说明：
在文本块中可以混合使用普通文本和公式元素。公式使用LaTeX语法，如：1+2=3、\frac{a}{b}、\sqrt{x}等。支持在同一文本块中包含多个公式和普通文本。
使用飞书user认证：
user认证与tenant认证在增加权限时是有区分的，所以在初次由tenant切换到user时需要注意配置的权限；为了区分不同的用户需要在配置mcp server服务的url增加query参数：userKey，该值是用户的唯一标识所以最好在设置时越随机越好
强烈建议使用user认证：
tenant认证有诸多限制，比如文件访问权限、飞书openapi兼容(不支持搜索wiki文档)、文档创建编辑记录等方面都不如user认证。

🚨 故障排查

权限问题排查

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

问题确认

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

权限验证与排查

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

常见问题

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

📚 开发者 Wiki

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

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

💖 支持项目

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

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

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

本项目 fork 自 cso1z/Feishu-MCP，遵循原项目 MIT 协议。