Feishu Codex MCP v26.08.25

简体中文 | English

通过企业自建应用，把飞书知识库和已授权的共享云盘接入 Codex。该 MCP 使用 App ID 与 App Secret 获取应用身份，可列出、搜索和读取知识库、电子表格、多维表格与共享文件，也能在严格边界内新建或小范围修改文档。

本仓库是可公开上传到 GitHub 的源码版。它不包含真实 .env、任何飞书内容、本地备份、下载文件、依赖目录或发布压缩包。

功能与安全边界

• 使用飞书应用身份，不要求在浏览器里登录个人飞书账号。
• App ID 与 App Secret 只证明“这是哪个应用”；API 权限和目标资源授权共同决定“它能访问什么”。
• 默认 FEISHU_WIKI_READ_SCOPE=root，只读取指定根节点及其后代。
• 可将读取范围改成 space，读取根节点所在知识空间的全部节点；写操作仍限制在配置的根节点或共享文件夹内。
• 修改文档前会保存本地备份；恢复操作会创建新草稿，不会直接覆盖当前文档。
• 不提供删除、移动、分享或修改权限等破坏性工具。
• Codex 对写工具使用 writes 审批模式，执行前仍会请求确认。

准备工作

你需要：

• 一个有权创建、发布或审批企业自建应用的飞书企业账号；
• Windows 10/11；
• Node.js 24 或更高版本；
• Codex Desktop、Codex CLI 或 Codex IDE 扩展；
• 一个准备授权给应用的知识库节点；共享云盘文件夹为可选项。

官方入口：

• 飞书开放平台开发者后台
• 飞书开放平台开发文档
• Codex MCP 配置文档

一、创建飞书企业自建应用

1. 打开飞书开放平台开发者后台，选择“创建企业自建应用”。
2. 填写应用名称、说明和图标。
3. 进入“凭证与基础信息”，复制 App ID 与 App Secret，暂时保存在密码管理器中。
4. 不要把 App Secret 发到聊天、Issue、截图或 GitHub。若已经泄露，应立即在飞书后台重置。

这个项目使用应用身份换取 tenant_access_token，因此不需要个人 OAuth 登录。你是企业管理员或应用管理员，并不等于应用自动拥有所有知识库和云盘权限；资源仍需单独授权。

二、配置并发布飞书权限

进入应用的“权限管理”，按实际要使用的能力申请权限。飞书后台的中文名称可能调整，建议同时按权限码搜索。

能力	只读权限	使用写工具时的权限
知识库目录	wiki:wiki:readonly	wiki:wiki 或后台显示的等价可写权限
新版文档	docx:document:readonly	docx:document
电子表格	sheets:spreadsheet:readonly	本项目当前只读取，可保持只读
多维表格	bitable:app:readonly	本项目当前只读取，可保持只读
云盘文件	drive:drive:readonly	在共享文件夹新建文档时使用等价可写权限

最小权限原则：只使用读取工具时，不要申请可写权限。若飞书后台显示的权限名称与上表不同，请以对应 API 页面列出的最新“所需权限”为准。

权限添加后还要完成：

1. 创建应用版本；
2. 申请发布；
3. 由企业管理员审批新增权限；
4. 确认版本状态为已发布。

仅在后台勾选权限但没有发布，运行中的应用身份不会获得新权限。

三、授权知识库与共享云盘

API 权限是应用能力，资源授权是具体文档的访问权，两者缺一不可。

授权知识库

1. 打开准备接入的知识库或目标根节点。
2. 在知识空间成员、权限设置或文档协作者中添加刚创建的企业自建应用。不同飞书版本中入口可能显示为“添加文档应用”。
3. 只读取时授予查看权限；需要 feishu_edit 或 feishu_create 时再授予编辑权限。
4. 若搜索不到应用，先确认应用已发布、审批通过，并且可用范围包含当前账号。

授权共享云盘文件夹

1. 打开目标共享文件夹的分享或权限设置。
2. 添加该企业自建应用，并按需要授予查看或编辑权限。
3. 只配置一个明确的根文件夹，不要把整个企业云盘作为默认边界。

管理员身份不会绕过知识库和文件夹的资源授权。应用最终可见的内容，是“已发布的 API 权限”与“已授权资源”的交集。

四、取得 Wiki 和 Drive Token

Wiki token

复制目标知识库节点链接，例如：

https://your-tenant.feishu.cn/wiki/WIKI_NODE_TOKEN?from=copylink

/wiki/ 后、查询参数 ? 前的部分就是 FEISHU_WIKI_ROOT_TOKEN。完整链接可以填入 FEISHU_WIKI_ROOT_URL，用于生成可点击链接。

Drive token

复制已授权共享文件夹链接，例如：

https://your-tenant.feishu.cn/drive/folder/DRIVE_FOLDER_TOKEN

/folder/ 后、查询参数前的部分就是 FEISHU_DRIVE_ROOT_TOKEN。不需要云盘能力时可留空。

不要把普通文档 token、知识库节点 token 和云盘文件夹 token 混用。若链接结构与示例不同，可先在浏览器地址栏中确认资源类型，或通过飞书 API 调试台核对 token。

五、安装项目并填写 .env

在 PowerShell 中进入项目目录：

npm ci
Copy-Item .env.example .env
notepad .env

在 .env 中填写自己的值：

FEISHU_APP_ID=<你的 App ID>
FEISHU_APP_SECRET=<你的 App Secret>
FEISHU_WIKI_ROOT_TOKEN=<知识库根节点 Wiki token>
FEISHU_WIKI_ROOT_URL=https://your-tenant.feishu.cn/wiki/<知识库根节点 Wiki token>
FEISHU_WIKI_READ_SCOPE=root
FEISHU_DRIVE_ROOT_TOKEN=<共享文件夹 Drive token；不用云盘时留空>
FEISHU_API_BASE_URL=https://open.feishu.cn/open-apis
FEISHU_BACKUP_DIR=data/backups

读取范围有两个选择：

• root：默认值，只读取配置根节点及其子节点，适合公开部署和最小授权。
• space：读取该根节点所属知识空间的全部节点，适合确实需要跨目录搜索的场景。

space 只扩大读取发现范围，不扩大写入边界。.env 已被 .gitignore 排除；只能提交 .env.example。

使用说明

完成飞书应用配置后，按下面的顺序连接：

1. 运行 npm ci 安装锁定版本的依赖。
2. 把 .env.example 复制为 .env。
3. 填写自己的 App ID、App Secret 和知识库根节点 Wiki token。
4. 保持 FEISHU_WIKI_READ_SCOPE=root 可将读取限制在根节点及其后代；确实要读取同一知识空间的其他目录时才改为 space。
5. 需要读取共享云盘时填写 FEISHU_DRIVE_ROOT_TOKEN；不用云盘时留空。
6. 双击 connect-feishu.cmd，看到 Setup completed 后完全退出并重启 Codex。
7. 让 Codex 执行“列出飞书知识库根目录”，确认 MCP 已连接。
8. 更换应用、目录或读取范围后，修改 .env 并再次重启 Codex。

知识库根节点即使没有子页面，feishu_list_wiki 也会返回根节点本身。space 模式可让列出、搜索和读取覆盖同一知识空间，但创建、编辑和恢复草稿仍受原始 FEISHU_WIKI_ROOT_TOKEN 限制。

读取知识库中的多维表格时，feishu_read 可用 table 指定数据表，并用 max_tables、max_records 限制返回量。该能力需要 bitable:app:readonly 或等价的更高权限，且目标多维表格必须授权给应用。

在项目目录运行以下命令，可执行不写入飞书内容的在线只读诊断：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1

六、连接 Codex

自动配置（Windows）

安装依赖并填写 .env 后，双击：

connect-feishu.cmd

脚本会保留 ~/.codex/config.toml 中的其他设置，只更新 [mcp_servers.feishu] 段。成功后完全退出并重新打开 Codex。

手动配置

Codex 的 MCP 配置文件位于 ~/.codex/config.toml。把路径改成你机器上的绝对路径，Windows 路径建议使用 /：

[mcp_servers.feishu]
command = "C:/Program Files/nodejs/node.exe"
args = ["C:/path/to/FeishuCodexMCP/src/server.js"]
cwd = "C:/path/to/FeishuCodexMCP"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

这里不需要把 App ID 或 Secret 写进 config.toml。服务器会从 cwd 指向目录中的 .env 读取配置。Codex Desktop、CLI 与 IDE 扩展在同一台机器上共用这份配置。

修改配置后必须重启 Codex。重启后，可以让 Codex 执行“列出飞书知识库根目录”来确认连接。

七、检查连接与制作发布包

运行需要真实飞书凭证的只读诊断：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1

只读诊断会检查应用认证、知识库根节点、当前读取范围、电子表格、多维表格和共享云盘，不会修改飞书内容。

需要制作包含依赖的安全发布包时运行：

npm run package:safe

脚本会核对压缩包白名单、扫描敏感值并执行离线启动检查，然后在项目上级目录生成 飞书MCP-v26.08.25.zip。该压缩包是发布产物，不应提交到 GitHub。

MCP 工具列表

工具	作用	类型
feishu_list_wiki	列出已授权根节点、子节点或知识空间目录	只读
feishu_search	在允许范围内按标题与正文搜索	只读
feishu_read	读取文档、电子表格、多维表格或文件	只读
feishu_edit	按修订号小范围替换或插入文档块，写前备份	写入，需审批
feishu_create	在允许的知识库节点或共享文件夹中新建 Docx	写入，需审批
feishu_list_drive	遍历已授权共享文件夹	只读
feishu_list_backups	查看本机保存的文档修改前快照	只读
feishu_create_restore_draft	从备份创建新的恢复草稿，不覆盖原文	写入，需审批

常见问题

有 App ID 和 Secret，为什么仍然读不到内容？

凭证只负责应用身份认证。还要同时满足：应用权限已发布并审批、目标资源已授权给应用、token 类型正确、资源位于配置的读取范围内。

为什么不需要浏览器登录？

本项目使用企业自建应用身份，通过 App ID 与 Secret 获取 tenant_access_token。浏览器登录通常对应用户 OAuth；这是另一套认证方式，不是本项目的必需步骤。

我是管理员，为什么还要配置权限？

管理员是你的账号角色，API 请求则代表企业自建应用。飞书把账号管理权、应用 API 权限和具体资源权限分开管理，避免一个应用仅凭管理员创建就自动读取全企业资料。

根节点能读取，但其他知识库页面看不到

检查 FEISHU_WIKI_READ_SCOPE。root 只遍历根节点后代；若确实要读取同一知识空间的其他目录，可改成 space 后重启 Codex。仍不可见时，检查知识空间对应用的授权。

多维表格读不到

确认应用至少具有 bitable:app:readonly 或等价的更高权限，权限版本已经发布，并且该多维表格已把应用添加为文档应用或协作者。

Codex 中没有出现飞书工具

检查 ~/.codex/config.toml 中的路径是否存在、项目是否已执行 npm ci、.env 是否位于 cwd，然后完全退出并重启 Codex。也可先运行 node src/server.js 检查启动错误；正常的 stdio MCP 服务器启动后会等待输入，不会弹出网页登录页面。

安全说明与上传检查

公开仓库和安全发布包都不得包含真实 .env、App ID、App Secret、Wiki/Drive token、企业知识库 URL、下载文件或本地备份。安全打包器会核对压缩包白名单，并扫描本机 .env 中的敏感值；发现真实配置时会拒绝发布。

FEISHU_WIKI_READ_SCOPE=space 只扩大同一知识空间的读取范围。创建、编辑和恢复草稿仍受配置根节点限制；多维表格功能保持只读，不提供记录写入工具。

如果怀疑凭证泄露：

1. 立即在飞书开放平台重置 App Secret。
2. 收回或缩小应用权限，并检查知识库、多维表格和共享云盘的资源授权。
3. 删除包含旧凭证的本地文件和压缩包。
4. 若凭证进入过 Git 历史，应清理历史后再上传，并始终以新 Secret 为准。

上传前逐项确认：

• [ ] 仓库中只有 .env.example，没有 .env 或其他真实凭证文件。
• [ ] App Secret、真实 Wiki/Drive token、企业域名和飞书内容没有出现在任何已跟踪文件中。
• [ ] 没有 node_modules、data、downloads、backups、日志或压缩包。
• [ ] git status --short 只显示预期改动，或保持为空。
• [ ] 用 git ls-files 复核即将上传的完整文件列表。
• [ ] 若凭证曾进入 Git 历史，仅删除当前文件不够；应先重置飞书 Secret，再清理历史后上传。

可用以下命令做快速检查：

git ls-files
git grep -n -I -E "FEISHU_APP_SECRET=.+|tenant_access_token|your-tenant\.feishu\.cn"

最后一条命令可以命中 README 中的占位示例；人工确认它们只是占位符，不是真实值。