Feishu Codex MCP v26.08.25

简体中文 | English

Через собственное корпоративное приложение Feishu база знаний Feishu и авторизованное общее облачное хранилище подключаются к Codex. Этот MCP использует App ID и App Secret для получения идентичности приложения; он может выводить список, искать и читать базу знаний, электронные таблицы, многомерные таблицы и общие файлы, а также создавать документы или вносить небольшие изменения в строгих границах.

Этот репозиторий — версия исходного кода, которая может быть публично загружена на GitHub. Он не содержит реального .env, контента Feishu, локальных резервных копий, загруженных файлов, каталогов зависимостей или архива выпуска.

Возможности и границы безопасности

• Используется идентификация приложения Feishu, не требуется вход в личный аккаунт Feishu в браузере.

• App ID и App Secret показывают только то, что это за приложение; права API и авторизация целевых ресурсов вместе определяют, к каким данным оно может получить доступ.

• По умолчанию FEISHU_WIKI_READ_SCOPE=root — чтение только указанного корневого узла и его дочерних узлов.

• Можно изменить область чтения на space, чтобы читать все узлы пространства знаний, в котором находится корневой узел; операции записи по-прежнему ограничены настроенным корневым узлом или общей папкой.

• Перед изменением документа сохраняется локальная резервная копия; операция восстановления создаёт новый черновик и не перезаписывает текущий документ напрямую.

• Не предоставляются разрушительные инструменты: удаление, перемещение, публикация или изменение прав.

• Для инструментов записи Codex использует режим подтверждения writes; перед выполнением всё равно запрашивается подтверждение.

Related MCP server: Feishu MCP Server

Подготовка

Вам понадобятся:

• Аккаунт предприятия Feishu, имеющий право создавать, публиковать или одобрять корпоративные приложения;

• Windows 10/11;

• Node.js 24 или выше;

• Codex Desktop, Codex CLI или расширение Codex IDE;

• Узел базы знаний, который вы планируете авторизовать для приложения; общая папка на облачном диске опциональна.

Официальные ресурсы:

• Консоль разработчика открытой платформы Feishu

• Документация разработчика открытой платформы Feishu

• Документация по настройке MCP для Codex

1. Создание собственного корпоративного приложения Feishu

1. Откройте консоль разработчика открытой платформы Feishu и выберите «Создать собственное корпоративное приложение».

2. Заполните название приложения, описание и иконку.

3. Перейдите в «Учётные данные и основная информация», скопируйте App ID и App Secret и временно сохраните их в менеджере паролей.

4. Не отправляйте App Secret в чаты, issues, скриншоты или на GitHub. Если он уже раскрыт, немедленно сбросьте его в консоли Feishu.

Этот проект использует идентификацию приложения для получения tenant_access_token, поэтому личный вход через OAuth не требуется. Тот факт, что вы являетесь администратором предприятия или администратором приложения, не означает, что приложение автоматически получает доступ ко всем базам знаний и облачным дискам; ресурсы по-прежнему требуют отдельной авторизации.

2. Настройка и публикация разрешений Feishu

Перейдите в раздел «Управление разрешениями» приложения и запросите разрешения в соответствии с реально используемыми возможностями. Названия в консоли Feishu на китайском могут меняться; рекомендуется искать также по кодам разрешений.

Принцип минимальных привилегий: если вы используете только инструменты чтения, не запрашивайте разрешения на запись. Если название разрешения в консоли Feishu отличается от таблицы, ориентируйтесь на актуальные «требуемые разрешения», указанные на соответствующей странице API.

После добавления разрешений также необходимо выполнить:

1. Создать версию приложения;

2. Отправить заявку на публикацию;

3. Получить одобрение новых разрешений от администратора предприятия;

4. Убедиться, что статус версии — «Опубликована».

Если только отметить разрешения в консоли без публикации, работающее приложение не получит новые возможности.

3. Авторизация базы знаний и общего облачного диска

Разрешения API — это возможности приложения, а авторизация ресурсов — это доступ к конкретным документам. Требуется и то, и другое.

Авторизация базы знаний

1. Откройте базу знаний или целевой корневой узел, который планируете подключить.

2. В участников пространства знаний, в настройках разрешений или в списке соавторов документа добавьте созданное собственное корпоративное приложение. В разных версиях Feishu этот пункт может отображаться как «Добавить приложение документа».

3. Если нужен только просмотр, дайте право на просмотр; только когда нужны feishu_edit или feishu_create, дайте право на редактирование.

4. Если приложение не находится экзаменом, сначала убедитесь, что оно опубликовано, утверждено и область его доступности включает текущий аккаунт.

Авторизация общей папки облачного диска

1. Откройте настройки общего доступа или разрешений для целевой общей папки.

2. Добавьте это корпоративное приложение и предоставьте ему право просмотра или изменения.

3. Настройте только один определённый корневой каталог; не делайте весь корпоративный облачный диск границей по умолчанию.

Роль администратора не обходит авторизацию ресурсов базы знаний и папок. Итоговые видимые приложению данные — это пересечение «опубликованных разрешений API» и «авторизованных ресурсов».

4. Получение wiki-токенов и Drive-токенов

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. Если доступ к облачному диску не нужен, это поле можно оставить пустым.

Не смешивайте токены обычного документа, узла базы знаний и папки облачного диска. Если структура ссылки отличается от примеров, сначала в адресной строке браузера уточните тип ресурса или проверьте токен через отладочную консоль API Feishu.

5. Установка проекта и заполнение .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.

Инструкция по использованию

После настройки приложения Feishu подключайте его в следующем порядке:

1. Выполните npm ci, чтобы установить зависимости точных версий.

2. Скопируйте .env.example в .env.

3. Заполните свои App ID, App Secret и Wiki-токен корневого узла базы знаний.

4. Держите FEISHU_WIKI_READ_SCOPE=root, чтобы ограничить чтение корневым узлом и его дочерними; изменяйте на space только если действительно нужно читать другие каталоги того же пространства знаний.

5. Для чтения общего облачного диска заполните FEISHU_DRIVE_ROOT_TOKEN; если облачный диск не нужен, оставьте пустым.

6. Дважды щёлкните connect-feishu.cmd, после появлении Setup completed полностью выйдите и перезапустите Codex.

7. Попросите Codex выполнить «получить список корневого узла базы знаний Feishu», чтобы убедиться, что MCP подключён.

8. При смене приложения, каталога или области чтения измените .env и снова перезапустите Codex.

Даже если у корневого узла базы знаний нет дочерних страниц, feishu_list_wiki вернёт сам корневой узел. Режим space позволяет списку, поиску и чтению охватывать всё пространство знаний, но создание, редактирование и восстановление черновиков по-прежнему ограничены исходным FEISHU_WIKI_ROOT_TOKEN.

При чтении многомерной таблицы в базе знаний feishu_read может указать конкретную таблицу данных через параметр max_tables, а также можно через max_records ограничить количество возвращаемых записей. Для этой возможности требуется bitable:app:readonly или более высокий эквивалентный уровень, а целевая многомерная таблица должна быть явно авторизована для приложения.

Выполните в каталоге проекта следующую команду для онлайновой диагностики только чтения, не записывающей контент в Feishu:

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

6. Подключение Codex

Автоматическая настройка (Windows)

После установки зависимостей и заполнения .env дважды щёлкните:

connect-feishu.cmd

Скрипт сохранит другие настройки в ~/.codex/config.toml и обновит только секцию [mcp_servers.feishu]. После успешного выполнения полностью закройте и заново откройте Codex.

Ручная настройка

Файл конфигурации MCP для Codex расположен по адресу ~/.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. Сервер читает конфигурацию из файла .env в каталоге, указанном через cwd. Codex Desktop, CLI и расширение IDE на одном устройстве используют эту общую конфигурацию.

После изменения конфигурации обязательно перезапустите Codex. Затем вы можете попросить Codex «получить список корневого узла базы знаний Feishu», чтобы подтвердить подключение.

7. Проверка подключения и создание выпуска

Запустите диагностику только для чтения, требующую реальные учётные данные Feishu:

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

Диагностика только чтения проверяет аутентификацию приложения, корневой узел базы знаний, текущую область чтения, электронные таблицы, многомерные таблицы и общий облачный диск; она не изменяет контент Feishu.

Для создания безопасного пакета с зависимостями выполните:

npm run package:safe

Скрипт проверяет белый список содержимого архива, сканирует чувствительные значения и выполняет офлайновую проверку запуска, после чего создаёт 飞书MCP-v26.08.25.zip в родительском каталоге. Этот архив является артефактом выпуска и не должен попадать в Git.

Список инструментов MCP

Часто задаваемые вопросы

Есть App ID и Secret, почему всё равно ничего не читается?

Учётные данные нужны только для аутентификации приложения. Одновременно должны быть выполнены условия: разрешения приложения опубликованы и одобрены, целевой ресурс авторизован для приложения, токен имеет правильный тип, а ресурса находится в настроенной области чтения.

Почему не требуется вход в браузере?

В этом проекте используется собственный корпоративный target, и tenant_access_token получается через App ID и Secret. Вход через браузер обычно означает OAuth пользователя — это отдельный способ аутентификации, он не является обязательным для проекта.

Я администратор, зачем же ещё настраивать разрешения?

Администратор — это роль вашей учётной записи, а запросы API действуют от имени корпоративного приложения в Feishu присутствует раздельное управление аккаунтом, правами API приложения и правами доступа к ресурсам; это защищает от автоматического доступа приложения ко всем данным предприятияКуртии команды.

Корень читается, но другие страницы базы знаний не видны

Проверьте FEISHU_WIKI_READ_SCOPE. root проходится только по подузлам корня. Если вам действительно нужно читать другие каталоги пространства знаний, измените на space и перезапустите Codex. Если всё равно не видно, проверьте авторизацию пространства знаний для приложения.

Не читается многомерная таблица

Убедитесь, что приложение имеет как минимум bitable:app:readonly или эквивалентное более высокое разрешение, версия разрешений уже опубликована, а конкретная многоконфигурированная таблица добавила приложение в качестве «приложения для документа» или соавтора.

Инструменты Feishu не появляются в Codex

Проверьте, существует ли путь в ~/.codex/config.toml, выполнен ли npm ci в проекте, находится ли .env в cwd, и полностью перезапустите Codex. Можно также запустить node src/server.js, чтобы увидеть ошибки на старте; обычный stdio MCP-сервер после запуска ожидает ввод и не выводит веб-страницу с входом.

Меры безопасности и проверка перед публикацией

Ни в публичном репозитории, ни в пакете выпуска не должны быть настоящими .env, App ID, App Secret, Wiki/Drive-токены, ссылки на корпоративную базу знаний, загруженные файлы или лок. резервные копии. Безопасный архиватор проверяет белый список содержимого пакета и ищет чувствительные значения в локальном .env; при обнаружении реальной конфигурации публикация отклоняется.

FEISHU_WIKI_READ_SCOPE=space расширяет только чтение в пределах того же пространства знаний. Создание, редактирование и восстановление черновиков по-прежнему ограничены настроенным корневым узлом; функциональность многомерных таблиц остаётся только чтение, записи не предллаются интеллектуальные инструменты.

Если индикаторы были открыты, скомпрометированы:

1. Немедленно сбросьте App Secret на открытой платформе Feishu.

2. Отзовите или ограничьте права приложения и просмотрите авторизации для базы знаний, многомерных таблиц и общего облачного диска.

3. Удалите локальные файлы и архивы, содержащие старые учётные данные.

4. Если учётные изменения или выделисты, очистите историю Git перед отправкой; всегда ориентируйтесь на новый Secret.

Перед загрузкой проверить каждый пункт:

• В репозитории только .env.example, нет .env и других настоящих файлов с учётными данными.

• App Secret, реальные Wiki/Drive-токены, корпоративные домены и контент Feishu не встречаются ни в одном отслеживаемом файле.

• Нет node_modules, data, downloads, backups, журналов или архивов.

• Вывод git status --short содержит только ожидаемые изменения или пуст.

• Используйте git ls-files для повторного просмотра полного спискафайлов, который будет загружен.

• Если учётные данные когда-либо попадали в историю Git, удаления текущего файла недостаточно: сначала сбрtoken new Secret, реальных токен, корпоративный домен и внутренний файли в Git-истории, настоящий видимость?

Используйте следующую команду для быстрой проверки:

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

Последняя команда может обнаружить в README шаблонные примеч и местоholders; обязательно убедитесь, что это только местаholders, а не настоящие значения.