# Feishu Codex MCP v26.08.25

[简体中文](README.md) | [English](README_EN.md)

通过企业自建应用，把飞书知识库和已授权的共享云盘接入 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 扩展；
- 一个准备授权给应用的知识库节点；共享云盘文件夹为可选项。

官方入口：

- [飞书开放平台开发者后台](https://open.feishu.cn/app)
- [飞书开放平台开发文档](https://open.feishu.cn/document/home/index)
- [Codex MCP 配置文档](https://developers.openai.com/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

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

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

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

### Drive token

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

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

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

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

## 五、安装项目并填写 .env

在 PowerShell 中进入项目目录：

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

在 `.env` 中填写自己的值：

```dotenv
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
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1
```

## 六、连接 Codex

### 自动配置（Windows）

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

```text
connect-feishu.cmd
```

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

### 手动配置

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

```toml
[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
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-live.ps1
```

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

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

```powershell
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，再清理历史后上传。

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

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

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