Feishu Codex MCP v26.08.25

简体中文 | English

Conecta el wiki de Feishu y las unidades de nube compartidas autorizadas a Codex mediante una aplicación empresarial creada por la propia empresa. Este MCP usa App ID y App Secret para obtener la identidad de la aplicación; permite enumerar, buscar y leer wikis, hojas de cálculo, tablas Bitable y archivos compartidos, así como crear documentos o realizar modificaciones acotadas dentro de límites estrictos.

Este repositorio es la versión de código fuente que se puede subir públicamente a GitHub. No incluye un .env real, contenido de Feishu, copias de seguridad locales, archivos descargados, directorios de dependencias ni paquetes de publicación.

Funciones y límites de seguridad

• Usa la identidad de la aplicación de Feishu; no requiere iniciar sesión con una cuenta personal de Feishu en el navegador.

• App ID y App Secret solo demuestran "qué aplicación es"; los permisos de la API y la autorización de recursos determinan conjuntamente "a qué puede acceder".

• El valor predeterminado de FEISHU_WIKI_READ_SCOPE es root; solo lee el nodo raíz especificado y sus descendientes.

• Puedes cambiar el alcance de lectura a space para leer todos los nodos del espacio de wiki al que pertenece el nodo raíz; las operaciones de escritura siguen limitándose al nodo raíz configurado o a la carpeta compartida.

• Antes de modificar un documento se guarda una copia de seguridad local; la restauración crea un borrador nuevo y no sobrescribe directamente el documento actual.

• No se ofrecen herramientas destructivas como eliminación, movimiento, uso compartido u ocultamiento de permisos.

• Codex usa el modo de aprobación writes para las herramientas de escritura y sigue solicitando confirmación antes de ejecutarlas.

Related MCP server: Feishu MCP Server

Requisitos previos

Necesitarás:

• Una cuenta empresarial de Feishu con permiso para crear, publicar o aprobar aplicaciones empresariales propias;

• Windows 10/11;

• Node.js 24 o superior;

• Codex Desktop, Codex CLI o la extensión de Codex para IDE;

• Un nodo raíz del wiki que vayas a autorizar a la aplicación; la carpeta compartida de la unidad de nube es opcional.

Enlaces oficiales:

• Panel de desarrolladores de la plataforma abierta de Feishu

• Documentación de desarrollo de la plataforma abierta de Feishu

• Documentación de configuración de MCP de Codex

1. Crear una aplicación empresarial propia en Feishu

1. Abre el panel de desarrolladores de la plataforma abierta de Feishu y elige "Crear aplicación empresarial propia".

2. Rellena el nombre, la descripción y el icono de la aplicación.

3. Entra en "Credenciales e información básica", copia App ID y App Secret y guárdalos temporalmente en una gestor de contraseñas.

4. No envíes App Secret a chats, issues, capturas de pantalla ni GitHub. Si ya se ha filtrado, restablece inmediatamente el secreto en el panel de Feishu.

Este proyecto usa la identidad de aplicación para obtener un tenant_access_token, por lo que no necesita un inicio de sesión OAuth personal. Ser administrador de la empresa o administrador de la aplicación no implica que la aplicación tenga automáticamente todos los permisos del wiki y de la unidad de nube; los recursos deben autorizarse por separado.

2. Configurar y publicar los permisos de Feishu

Entra en "Gestión de permisos" de la aplicación y solicita los permisos según las capacidades que vayas a usar. El nombre en chino del panel de Feishu puede variar; conviene buscar también por el código de permiso.

Principio de mínimo privilegio: si solo se utilizan herramientas de lectura, no solicites permisos de escritura. Si en el panel de Feishu el nombre del permiso aparece distinto al de la tabla, toma como referencia el "requisito de permiso" correspondiente más actualizado de la página de la API.

Además de añadir los permisos, debes:

1. Crear una versión de la aplicación;

2. Solicitar la publicación;

3. Que el administrador de la empresa apruebe los nuevos permisos;

4. Confirmar que el estado de la versión esté publicado.

Si solo marcas los permisos en el panel sin publicar una versión, la identidad de la aplicación en ejecución no obtendrá los nuevos permisos.

3. Autorización del wiki y de la unidad compartida

Los permisos de API son la capacidad de la aplicación; la autorización de recursos es el acceso de la aplicación a los documentos concretos. Ambos son imprescindibles.

Autorizar el wiki

1. Abre el wiki que se va a integrar o el nodo raíz de destino.

2. Añade la aplicación empresarial recién creada en los miembros del espacio de wiki, la configuración de permisos o los colaboradores del documentos. En algunas versiones de Feishu la entrada puede mostrarse como "Añadir aplicación de documento".

3. Si solo se va a leer, otorga permiso de visualización; con feishu_edit o feishu_create, otorga permiso de edición.

4. Si no encuentras la aplicación, confirma que ya se ha publicado, que la aprobación ha pasado y que la disponibilidad incluye la cuenta actual.

Autorizar la carpeta compartida de la unidad

1. Abre la configuración de uso compartido o de permisos de la carpeta compartida de destino.

2. Añade la aplicación empresarial propia y otorga permiso de visualización o edición según lo necesario.

3. Configura una única carpeta raíz clara; no establezcas toda la unidad de la empresa como límite predeterminado.

El rol de administrador no omita la autorización de recursos del wiki ni de las carpetas. El contenido visible final de la aplicación es la intersección entre "los permisos de API publicados" y "los recursos autorizados".

4. Obtener los tokens de Wiki y de Drive

Token de Wiki

Copia el enlace del nodo raíz del wiki de destino, por ejemplo:

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

La parte posterior a /wiki/ y anterior al parámetro de consulta ? es FEISHU_WIKI_ROOT_TOKEN. En FEISHU_WIKI_ROOT_URL puedes completar el enlace completo para generar enlaces clics de documento.

Token de Drive

Copia un enlace de la carpeta compartida autorizada, por ejemplo:

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

La parte posterior a /folder/ y anterior al índice de consulta ? es FEISHU_DRIVE_ROOT_TOKEN. Puedes dejarlo vacío si no necesitas usar la unidad de nube.

No mezcles tokens de documentos normales, tokens de nodos de conocimiento y tokens de carpetas de unidad. Si la estructura del enlace difiere del ejemplo, confirma el tipo de recurso en la barra de direcciones del navegador o verifica el token en la consola de pruebas de la API de Feishu.

5. Instalar el proyecto y completar el .env

En PowerShell, entra en el directorio del proyecto:

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

Rellena tus propios valores en .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

El ámbito de lectura tiene dos opciones:

• root: valor por defecto. Solo lee el nodo raíz configurado y sus descendientes; es adecuado para despliegues públicos y permisos mínimos.

• space: lee todos los nodos del espacio de wiki al que pertenece el nodo raíz; sirve para casos de búsqueda transversal entre directorios del mismo espacio.

space solo amplía el ámbito de descubrimiento de lectura; no amplía la frontera de escritura. .env está excluido por .gitignore; solo se puede confirmar .env.example.

Instrucciones de uso

Una vez completada la configuración de la aplicación de Feishu, conéctate en el siguiente orden:

1. Ejecuta npm ci para instalar las dependencias bloqueadas según su versión.

2. Copia .env.example como .env.

3. Completa tu propio App ID, App Secret y el token del nodo del wiki.

4. Mantén FEISHU_WIKI_READ_SCOPE=root para limitar la lectura al nodo raíz y sus descendientes; usa space solo si realmente necesitas leer otros directorios del mismo espacio de wiki.

5. Si debes leer la unidad compartida, completa FEISHU_DRIVE_ROOT_TOKEN; si no la usas, déjalo vacío.

6. Haz doble clic en connect-feishu.cmd; cuando veas Setup completed, cierra del todo y reinicia Codex.

7. Pide a Codex que ejecute "lista la raíz del wiki de Feishu" para confirmar que el MCP está conectado.

8. Si cambias la aplicación, el directorio o el ámbito de lectura, actualiza .env y vuelve a reiniciar Codex.

El nodo raíz del wiki siempre se devuelve en feishu_list_wiki, incluso si no tiene subpáginas. El modo space permite que el listado, la búsqueda y la lectura cubran todo un espacio de wiki, pero la creación, edición y restauración de borradores sigue sujeta al FEISHU_WIKI_ROOT_TOKEN configurado originalmente.

Al leer una tabla Bitable del wiki, feishu_read puede especificar la tabla con table y limitar devoluciones con max_tables y max_records. Para ello se requiere bitable:app:readonly permiso equivalente de mayor nivel, y la tabla Bitable debe estar autorizada a la aplicación.

Ejecuta el siguiente comando en la raíz del proyecto para realizar un diagnóstico de solo lectura en línea que no escribe en Feishu:

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

6. Conexión con Codex

Configuración automática (Windows)

Instala las dependencias y completa .env; a continuación, haz doble clic en:

connect-feishu.cmd

El script conserva el resto de la configuración de ~/.codex/config.toml y solo actualiza la sección [mcp_servers.feishu]. Si todo es correcto, cierre por completo y vuelve a abrir Codex.

Configuración manual

El archivo de configuración MCP de Codex está en ~/.codex/config.toml. Cambia la ruta por la ruta absoluta de tu máquina; para rutas de Windows se recomienda usar /:

[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"

Aquí no necesitas escribir App ID ni App Secret en config.toml. El servidor leerá la configuración desde el archivo .env del directorio indicado en cwd. Codex Desktop, CLI y la extensión de IDE comparten esta configuración en la misma máquina.

Debes reiniciar Codex tras cambiar la configuración. Después del reinicio, pide a Codex que ejecute "lista de la raíz del wiki de Feishu" para confirmar la conexión.

7. Comprobación de conexión y generación del paquete publicado

Ejecuta un diagnóstico de solo lectura que use credenciales reales de Feishu:

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

El diagnóstico de solo lectura comprueba la autenticación de la aplicación, el nodo raíz del wiki, el ámbito de lectura actual, las hojas de cálculo, las tablas Bitable y la unidad compartida; no modifica contenido de Feishu.

Cuando necesites generar un paquete seguro con dependencias:

npm run package:safe

El script verifica una lista blanca de los archivos incluido en el zip, escanee los valores sensibles y hace una comprobación de arranque sin conexión; a continuación genera 飞书MCP-v26.08.25.zip en el directorio superior al proyecto. Este paquete es de publicación y no debe subirse a GitHub.

Lista de herramientas MCP

Preguntas frecuentes

¿Por qué no puedo leer contenido aunque tengo App ID y App Secret?

Las credenciales solo autentican la identidad de la aplicación. Además se deben cumplir estas condiciones: los permisos de la aplicación se han publicado y aprobado, el recurso de destino se ha autorizado a la aplicación, el tipo de token es correcto y el recurso se encuentra dentro del ámbito de lectura configurado.

¿Por qué no es necesario el inicio de sesión en el navegador?

Esta solución usa la identidad de la aplicación empresarial propia y obtiene tenant_access_token con App ID y App Secret. El inicio de sesión en el navegador normalmente corresponde a OAuth de usuario; es un método de autenticación distinto y no es un paso obligatorio de este proyecto.

Soy administrador, ¿por qué tengo que configurar permisos?

Administrador es tu rol de cuenta; las peticiones API representan a la aplicación empresarial propia. Feishu separa la administración de la cuenta, los permisos de API de la aplicación y los permisos de recursos, para evitar que una sola aplicación creada por un administrador pueda leer automáticamente toda la información de la empresa.

El nodo raíz se lee, pero el resto del wiki no aparece

Revisa FEISHU_WIKI_READ_SCOPE. El valor root solo recorre los descendientes del nodo raíz; si realmente es necesario leer otros directorios del mismo espacio de conocimiento, cambia a space y reinicia Codex. Si sigue sin aparecer, revisa la autorización del espacio de conocimiento para esta aplicación.

No se pueden leer las tablas Bitable

Comprueba que la aplicación tiene al menos bitable:app:readonly o un permiso superior equivalente, que la versión de permisos se ha publicado y que la tabla Bitable ha añadido la aplicación como user o como aplico colaborador.

No aparecen herramientas de Feishu en Codex

Revisa que la ruta de ~/.codex/config.toml exista, que el proyecto haya ejecutado npm ci y que .env esté en el cwd; luego cierra completamente de Codex y reiníciala. También puedes ejecutar antes node src/server.js para ver errores de inicio; el servidor MCP stdio normal espera entrada tras arrancar y no abre ninguna página de inicio de sesión.

Notas de seguridad y revisión para subir

El repositorio público y el paquete de publicación no deben contener un .env real, App ID, App Secret, tokens de Wiki/Drive, URLs del wiki corporativo, archivos descargados o copias locales de seguridad. El empaquetador seguro revisa la lista blanca del archivo comprimido y escanea los valores sensibles del archivo .env local; si detecta una configuración real, deniega la publicación.

FEISHU_WIKI_READ_SCOPE=space solo amplía el ámbito de lectura dentro del mismo espacio de conocimiento. La creación, la edición y la restauración de borradores siguen limitados al nodo raíz configurado; la funcionalidad de tablas Bitable se mantiene de solo lectura y no ofrece ninguna herramienta de escritura de registros.

Si se sospecha una filtración de credenciales:

1. Restablece inmediatamente el App Secret en la plataforma abierta de Feishu.

2. Revoca o reduce los permisos de la aplicación y revisa la autorización de recursos en el wiki, tablas Bitable y unidad compartida.

3. Elimina los archivos locales y paquetes que contengan credenciales antiguas.

4. Si las credenciales llegaron a estar en el historial de Git, revisa y limpia el historial antes de subir, y usa siempre el nuevo Secret.

Revisión final:

• En el repositorio solo existe .env.example; no hay .env ni otros archivos realesde credenciales.

• App Secret, tokens reales de Wiki/Drive, el dominio de la empresa y contenido de Feishu no aparecen en ningún archivo rastreado.

• No hay node_modules, data, downloads, backups, registros ni archivos comprimidos.

• git status --short solo muestra los cambios previstos o está vacío.

• Usa git ls-files para verificar la lista completa de archivos que se van a subir.

• Si en el historial de Git hubo credenciales, no basta con eliminar el archivo actual; primero restablece el Secret de Feishu y limpia el historial, después sube.

Ejecuta un chequeo rápido con el siguiente comando:

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

La última parte puede realizar con los marcadores de los campos; confirma manualmente que solo son marcadores de posición del ejemplo y no valores reales.