@hibson/mcp-feishu-doc

v2.6.8

Published

2 months ago

A Model Context Protocol (MCP) server for Feishu (Lark) cloud document and wiki management. Supports OAuth, Markdown upload, document reading/updating/deleting, search, and multi-app configuration.

0High
0Medium
0Low

hibson

feishu lark mcp model-context-protocol mcp-server typescript wiki document markdown oauth

3 分钟接入

如果你只是想在 MCP Client 里直接用已经发布到 npm 的版本，优先看这一节，不需要先 clone 仓库。

当前 npm 包名：

@hibson/mcp-feishu-doc
当前仓库版本：2.6.8

先准备飞书应用

在配置 MCP Client 之前，先去飞书开放平台创建一个自建应用。第一次接入最核心的是下面 4 个点：

创建一个自建应用，拿到 App ID 和 App Secret
在「安全设置」里添加重定向 URL：http://localhost:3010/oauth/feishu/callback
在「权限管理」里开通最小权限集合
如果你要操作知识库，再去目标 Wiki 里「添加文档应用」

建议开通的权限：

补充说明：

回调地址必须和 FEISHU_OAUTH_CALLBACK_URL 完全一致，路径必须是 /oauth/feishu/callback。
如果目标是知识库，除了开放平台里的 API 权限外，还需要在目标 Wiki 中手动「添加文档应用」，否则常见表现是 feishu_list_wikis 空列表、上传到 Wiki 时报 403。
某些租户里权限需要经过应用发布或管理员审批后才会真正生效。

再把 MCP 配到客户端

下面这段 mcp.json 可以直接复制。填上你自己的 appId / appSecret 后就能用。

适用于支持 mcpServers 配置的 MCP Client。

{
  "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",
        "LOGS_DIR": "~/.mcp-feishu-doc/logs",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "~/.mcp-feishu-doc/storage"
      }
    }
  }
}

建议：

STORAGE_PROVIDER_TYPE 使用 filesystem，这样 OAuth 凭证、默认应用信息、文档元数据都能持久化。
STORAGE_FILESYSTEM_PATH 和 LOGS_DIR 建议放到独立目录，便于排查授权、上传、读取问题。
FEISHU_OAUTH_CALLBACK_URL 默认可以直接使用 http://localhost:3010/oauth/feishu/callback。
在 stdio 模式下，只要配置了 FEISHU_OAUTH_CALLBACK_URL，服务会自动拉起本地 OAuth 回调地址。

首次使用流程

在飞书开放平台创建自建应用，并完成回调地址和权限配置。
把上面的 mcp.json 配到你的 MCP Client。
回填 FEISHU_DEFAULT_APP_ID 和 FEISHU_DEFAULT_APP_SECRET。
启动客户端后先调用 feishu_auth_url 获取授权链接。
浏览器完成授权回调后，再调用 feishu_get_user_info 或 feishu_list_wikis 验证是否可用。
开始使用 feishu_upload_markdown、feishu_get_document、feishu_update_document。

最常用的几个工具

feishu_auth_url：生成授权链接
feishu_upload_markdown：上传 Markdown 到云文档或知识库
feishu_get_document：读取文档正文、块结构和图片/附件资源
feishu_update_document：更新已有文档，支持冲突检测
feishu_list_wikis / feishu_list_wiki_nodes：定位知识库空间和节点

项目定位

mcp-feishu-doc 不是对飞书 OpenAPI 的简单直出，而是围绕“文档工作流”做的一层高阶封装。

它重点解决这三件事：

把本地 Markdown 稳定上传到飞书云文档或知识库，而不是只暴露底层导入接口。
读取文档时返回更适合 AI 消费的结构化结果，而不是只拿一段纯文本。
让文档在上传后还能持续维护，包括位置记忆、冲突检测、更新重建和多应用管理。

核心亮点

文档上传工作流完整：支持 filePath 或 content，支持上传到 drive 或 wiki，支持 targetId 和 parentNodeToken。
Markdown 处理更强：支持 Front Matter、callout、wiki link、代码块过滤、任务列表、高亮、删除线等语法转换。
图片与附件能力完整：支持本地图片/附件上传，支持远程图片/附件下载转存，支持读取时回传媒体资源。
文档读取更适合 Agent：返回 content + blocks + assets + revisionId，保留图片/附件在正文中的顺序。
更新链路可落地：支持冲突检测、force 覆盖、原位置重建、修订号追踪。
本地调试友好：支持 stdio、http、MCP Inspector、本地 mcp.json 配置。
工程化完整：支持 DI、存储抽象、结构化日志、OpenTelemetry、单测和集成测试。

当前功能

文档工作流

上传 Markdown 到飞书文档或知识库
批量上传多个 Markdown 文档
读取飞书文档内容
更新已有飞书文档
删除飞书文档
搜索飞书文档

媒体能力

上传本地图片到文档
上传本地附件到文档
支持远程图片下载后转存
支持远程附件下载后转存
读取时返回图片和附件资源
读取时提供图片内联 / 本地文件两种交付方式

飞书管理能力

OAuth 授权与回调处理
获取当前用户信息
多应用配置与默认应用切换
列出知识库空间
列出云空间文件夹
列出知识库节点

工具列表

当前共内置 15 个工具：

工具注册入口见 src/mcp-server/tools/definitions/index.ts。

典型使用场景

把本地 README.md、方案文档、周报、分享稿直接上传到飞书知识库
读取飞书文档后再做总结、改写、翻译或生成更新版本
将本地带图片的 Markdown 文档同步到飞书
在 AI Agent 中实现“生成文档 -> 上传 -> 读取 -> 更新”的闭环工作流
使用多个飞书应用账号切换不同环境或不同租户

快速开始

这一节主要面向本地开发、调试和二次开发。如果你只是要在客户端里直接用，请优先看前面的“3 分钟接入”。

前置要求

Node.js >= 20
pnpm >= 10

安装

git clone https://github.com/Hbin-Zhuang/mcp-feishu-doc.git
cd mcp-feishu-doc
pnpm install

配置环境变量

复制示例配置：

cp .env.example .env

最少需要确认这些字段：

MCP_TRANSPORT_TYPE
MCP_HTTP_PORT
STORAGE_PROVIDER_TYPE
STORAGE_FILESYSTEM_PATH
FEISHU_DEFAULT_APP_ID
FEISHU_DEFAULT_APP_SECRET
FEISHU_OAUTH_CALLBACK_URL

推荐本地调试配置：

MCP_TRANSPORT_TYPE=stdio
MCP_LOG_LEVEL=debug
STORAGE_PROVIDER_TYPE="filesystem"
STORAGE_FILESYSTEM_PATH="./.storage"
FEISHU_OAUTH_CALLBACK_URL=http://localhost:3010/oauth/feishu/callback

如果你要用 OAuth 网页回调，建议再起一个 http 模式实例，或者直接使用 dev:http。

本地快速调试

方式一：最快上手，用构建产物 + MCP Inspector

适合检查工具入参、快速点调、验证上传和读取。

pnpm run build
pnpm run inspector

说明：

pnpm run inspector 会基于 dist/index.js 启动服务。
这也是为什么运行 Inspector 前要先执行一次 pnpm run build。
如果你刚改了源码但没重新 build，Inspector 里看到的还是旧逻辑。

方式二：源码热更新调试，适合本地开发

STDIO 模式：

pnpm run dev:stdio

HTTP 模式：

pnpm run dev:http

说明：

dev:stdio 适合 MCP Client 或本地 SDK 客户端直接拉起。
dev:http 适合调 OAuth 回调、HTTP 接入或浏览器调试。
两个命令都基于 tsx watch src/index.ts，改代码会自动重启。

方式三：本地 MCP Client 直接接入

仓库根目录自带一个示例配置文件 mcp.json。

默认示例展示的是“直接使用 npm 已发布版本”的方式。如果你要在本地开发仓库源码，可以参考下面两个版本。

已发布版本：

{
  "mcpServers": {
    "mcp-feishu-doc": {
      "command": "npx",
      "args": ["-y", "@hibson/mcp-feishu-doc@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "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",
        "LOGS_DIR": "~/.mcp-feishu-doc/logs",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "~/.mcp-feishu-doc/storage"
      }
    }
  }
}

本地构建产物版本：

{
  "mcpServers": {
    "mcp-feishu-doc-local": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "debug",
        "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",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "./.storage"
      }
    }
  }
}

本地源码直连版本：

{
  "mcpServers": {
    "mcp-feishu-doc-local-dev": {
      "command": "pnpm",
      "args": ["exec", "tsx", "src/index.ts"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "debug",
        "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",
        "STORAGE_PROVIDER_TYPE": "filesystem",
        "STORAGE_FILESYSTEM_PATH": "./.storage"
      }
    }
  }
}

不同方式适用场景：

npx @hibson/mcp-feishu-doc@latest：给最终用户接入，最省事。
node ./dist/index.js：适合验证你当前仓库 build 出来的产物。
pnpm exec tsx src/index.ts：适合本地开发调试，改完源码立即生效。

常用调试命令

pnpm run build                 # 构建 dist
pnpm run dev:stdio             # 源码热更新，STDIO
pnpm run dev:http              # 源码热更新，HTTP
pnpm run start:stdio           # 运行构建产物，STDIO
pnpm run start:http            # 运行构建产物，HTTP
pnpm run inspector             # 启动 MCP Inspector（依赖 dist）
pnpm run typecheck             # TypeScript 类型检查
pnpm run lint                  # ESLint 检查
pnpm run test                  # 单元测试
pnpm run test:integration:feishu # 飞书集成测试

配置说明

所有配置在 src/config/index.ts 中统一解析并做 Zod 校验。

常用环境变量如下：

注意：本地调试时推荐使用 filesystem 存储，否则 OAuth 凭证、文档元数据和默认应用信息不会持久保存。

当前上传 / 读取 / 更新能力

上传

支持 filePath 和 content
支持 drive / wiki
支持 targetId 和 parentNodeToken
支持 Markdown 预处理
支持本地图片与附件上传
支持远程图片与附件转存

读取

返回 title
返回近似 Markdown 的 content
返回保序的 blocks
返回 assets
返回 revisionId

更新

支持内容或文件路径更新
支持冲突检测
支持 force 强制覆盖
支持原位置重建
支持修订号追踪

架构概览

核心调用链如下：

MCP Tool Definition
  -> FeishuService
    -> FeishuApiProvider
    -> MarkdownProcessorProvider
    -> StorageService

对应目录：

src/mcp-server/tools/definitions：工具定义
src/services/feishu：飞书服务编排与 API 调用
src/storage：持久化与多后端抽象
src/container：依赖注入
src/utils：日志、性能、解析、遥测等横切能力

项目结构

测试与质量检查

pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run test:integration:feishu

部署

本地运行构建产物

pnpm run build
pnpm run start:stdio

或：

pnpm run build
pnpm run start:http

Cloudflare Workers

pnpm run deploy:dev
pnpm run deploy:prod

许可证

本项目基于 Apache 2.0 许可证发布，详见 LICENSE。