从 Markdown 到飞书文档：用 MCP 打通 AI 内容沉淀01｜📌 一句话说清楚 mcp-feishu-doc

面向 AI 写作、技术文档沉淀和知识库运营场景。本文介绍 mcp-feishu-doc 解决了什么问题，以及它如何把 AI 生成的 Markdown 内容，带着图片、附件和结构信息，落到飞书文档和知识库里。

01｜📌 一句话说清楚

mcp-feishu-doc 是一个面向文档工作流的 MCP Server。

它不是一个通用飞书 API 工具箱，而是把 Markdown 上传、图片附件处理、知识库落位、文档读取和基础版本检测串起来，解决 AI 内容进入飞书的最后一步。
简单说：

AI 负责生成和整理内容，mcp-feishu-doc 负责把内容交付到飞书文档和知识库。

02｜🧩 为什么需要它

很多团队已经开始让 AI 参与写文档：项目说明、技术方案、接口文档、会议纪要、复盘材料、产品调研、运营文章，甚至根据代码仓库自动生成开发文档。真正卡住的地方，往往不是“AI 会不会写”，而是“写完以后怎么进入团队系统”。

常见问题大概有四类：

问题一：Markdown 要复制到飞书里，格式容易丢；
问题二：图片和附件要重新上传，本地路径经常失效；
问题三：文档要放到指定知识库，不应该停在个人草稿里；
问题四：后续还要能读回来，继续总结、改写和维护。

所以这个项目关注的不是单次调用接口，而是把“生成内容”到“沉淀内容”这条链路顺起来。

03｜✅ 它解决的核心问题

更好承接真实 Markdown

真实的 Markdown 往往不只是正文，还会带 Front Matter、Wiki Link、Callout、任务列表、本地图片和附件引用。mcp-feishu-doc 在上传前会先做一层预处理，把这些常见格式转换成更适合飞书文档承接的内容，并把图片、附件替换成可上传的资源占位。它的定位不是“能把 Markdown 传上去”，而是尽量让原来的文档结构、资源引用和阅读体验，在进入飞书后还能保留下来。

图片和附件必须跟着内容一起走

文档里最容易出问题的往往不是正文，而是图片、附件和本地资源路径。这个项目支持本地图片上传、本地附件上传、远程图片下载转存、远程附件下载转存，也支持在读取文档时按原顺序返回图片和附件资源。这意味着 AI 不只是写了文字，也能把图文内容完整带到飞书里。

知识库写入更直接

对于团队来说，文档最终通常不是停在个人云空间，而是进入某个知识库空间。工具支持上传到云空间根目录、指定文件夹、指定 Wiki 空间，也支持在已有 Wiki 节点下创建子文档。这样 AI 助手就可以参与实际知识库建设，而不是只生成一段需要人工搬运的草稿。

04｜🛠 常用工具

从使用视角看，它覆盖了授权、上传、读取、更新、搜索和知识库浏览这些基础动作。

工具	用来做什么
`feishu_list_apps`	验证 MCP 服务和授权状态
`feishu_auth_url`	生成 OAuth 授权链接
`feishu_upload_markdown`	上传单篇 Markdown
`feishu_batch_upload_markdown`	批量上传多篇 Markdown
`feishu_get_document`	读取正文、图片、附件和版本信息
`feishu_update_document`	更新已有云空间文档，并做基础冲突检测
`feishu_list_wikis`	查看可访问的知识库

还有搜索、知识库节点浏览等能力，但日常上手时先掌握这几个就够了。

说明：feishu_update_document 目前更适合云空间文档的更新。Wiki 文档更新链路还在优化中，使用时建议谨慎评估。

05｜🔐 授权模型：个人号先跑通，企业号看权限

mcp-feishu-doc 默认采用 OAuth 授权，工具会使用当前授权用户的身份访问飞书文档。个人账号或个人知识库更适合用来快速验证上传、读取和批量导入流程。
如果是在企业账号下使用，当前版本部分能力依赖 drive:drive 权限。这个权限在很多企业租户里需要额外审批，未授权时可能无法完成文档读取或上传。
后续会把读取链路尽量收敛到更小的权限范围，例如优先探索 drive:export:readonly：通过导出 PDF 后在本地解析，减少对全量云空间读取权限的依赖。更长期的方向，是把能力做得更适合企业内部使用：比如只允许访问指定知识库或指定文档，保留操作记录，并通过白名单控制哪些用户和文档可以被 AI 处理。

06｜⚖️ 和官方 MCP 的关系

飞书官方已经有 lark-openapi-mcp，它的优势很明显：覆盖面广，适合操作多类飞书能力。如果你要做消息、日历、审批、通讯录等自动化，官方 MCP 更合适。
mcp-feishu-doc 的定位更窄，重点放在飞书文档和知识库这条链路上。

维度	官方 `lark-openapi-mcp`	`mcp-feishu-doc`
定位	飞书 OpenAPI 的通用 MCP 入口	飞书文档工作流 MCP
覆盖范围	广，适合多类业务能力	窄，聚焦 Docx / Wiki / Drive / 搜索
使用感	更像直接调 API	更像完成文档任务
图片/附件	需要自己组合底层接口	上传和读取都做了封装
知识库落位	需要理解 Wiki 相关接口	直接传目标空间或节点
权限说明	能力广，审批时要解释范围	场景更聚焦，但当前仍需关注 Drive 权限审批
适合场景	全量飞书自动化	AI 文档归档、读取、更新

它不是替代官方工具，而是补上一个更具体的场景：让 AI 生成的内容真正进入飞书知识库，并且后面还能继续读取和维护。

07｜🚀 从能不能用，到真正用起来

开工前：先验证工具状态

接入 MCP 工具后，不建议一上来就上传文档。更稳的方式是先让 AI 调用 feishu_list_apps，确认 MCP 服务已经被 IDE 识别，飞书应用配置也能正常读取。
如果应用数量是 0，也不一定是报错，可能只是还没有完成 OAuth 授权。接下来调用 feishu_auth_url，在浏览器里完成授权，就可以继续使用文档相关能力。

场景一：批量上传项目资料

当一个项目里有多篇 Markdown，例如教程、配置说明、开发规范，可以直接批量上传。
批量上传的价值在于：不用一篇篇复制，也不用逐个补图，适合把本地文档一次性整理到团队知识库。

上传完成后，多篇 Markdown 会进入指定知识库，并保留为独立文档，后续可以继续搜索、阅读和维护。

场景二：读取带图片的飞书文档

另一个常见场景，是让 AI 读取一篇已经在飞书里的文档。普通读取如果只拿正文文本，信息会少很多。尤其是教程、配置说明、操作记录这类文档，截图往往才是重点。
feishu_get_document 会读取正文、图片块、附件信息和版本信息。AI 可以按图片顺序逐张查看，再结合上下文总结每张图表达什么。

这对技术文章、接入教程、问题排查记录很有用，因为很多细节不在正文里，而在截图里。

08｜⚙️ 最小配置示例

在 MCP 客户端里配置服务后，就可以让 AI 助手调用对应工具。

{
  "mcpServers": {
    "mcp-feishu-doc": {
      "command": "npx",
      "args": ["-y", "@hibson/mcp-feishu-doc@latest"],
      "env": {
        "FEISHU_DEFAULT_APP_ID": "cli_your_app_id",
        "FEISHU_DEFAULT_APP_SECRET": "your_app_secret",
        "FEISHU_OAUTH_CALLBACK_URL": "http://localhost:3010/oauth/feishu/callback",
        "MCP_TRANSPORT_TYPE": "stdio",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "~/.mcp-feishu-doc/storage"
      }
    }
  }
}

完整接入、权限配置、参数说明，可以看 npm 页面：

👉 www.npmjs.com/package/@hi…

09｜👥 适合哪些人使用

开发者：把 README、技术方案、接口说明沉淀到飞书。

技术团队：批量维护项目知识库，让项目资料不再散落在本地。

AI 工作流搭建者：把“生成内容”延伸到“发布内容”，让自动化链路真正闭环。

10｜✨ 总结

AI 写作的价值，不只在于生成一段内容，更在于能否进入团队真实使用的知识系统。
mcp-feishu-doc 解决的正是这最后一公里：从 Markdown 到飞书文档，从本地图片到云端素材，从个人草稿到团队知识库，从一次性生成到可持续维护。
如果你的团队已经在用飞书，也在尝试用 AI 写文档，那么这个 MCP Server 可以让内容生产链路更完整、更自动化，也更适合长期沉淀。

从 Markdown 到飞书文档：用 MCP 打通 AI 内容沉淀