Servidor MCP de Feishu

Proporciona a Cursor, Windsurf, Cline y otras herramientas de codificación impulsadas por IA la capacidad de acceder, editar y procesar de forma estructurada documentos de Feishu, y además es compatible con la gestión de tareas de Feishu y la consulta de información de usuarios, implementado sobre un servidor del Model Context Protocol.

Ahora se incluye una herramienta CLI independiente feishu-tool, que permite invocar directamente todas las herramientas de Feishu desde el terminal o desde un script, sin necesidad de iniciar el servidor MCP. Combinado con Feishu-Skill, permite que agentes de IA como Claude Code elijan automáticamente la forma más adecuada de operar con Feishu.

Este proyecto permite que las herramientas de IA de codificación puedan:

• Procesamiento de documentos: obtener, comprender, crear y editar documentos de Feishu directamente, lo que mejora significativamente la inteligencia y la eficiencia del procesamiento documental.

• Gestión de tareas: listar, crear, actualizar y eliminar tareas de Feishu, con soporte de subtareas y gestión de miembros (requiere autenticación de usuario).

• Consulta de usuarios: buscar usuarios de Feishu por nombre u obtenerlos en lote por ID, para facilitar la asignación de tareas y la colaboración en documentos (requiere autenticación de usuario).

Cubre por completo el flujo real de uso de los documentos de Feishu, ayudándote a aprovechar eficazmente los recursos documentales:

1. Consulta del directorio de carpetas: obtén y explora rápidamente todos los documentos de una carpeta de documentos de Feishu, lo que facilita la gestión integral y la búsqueda.

2. Consulta y comprensión del contenido: admite lectura multimensional como estructurada, por bloques o enriquecida, para que la IA pueda entender con precisión el contexto del documento.

3. Creación y edición inteligentes: puede crear automáticamente nuevos documentos, generar y editar contenido en lote, satisfaciendo necesidades de escritura diversas.

4. Búsqueda y recuperación eficiente: incorpora búsqueda por palabras clave para encontrar rápidamente la información objetivo entre numerosos documentos.

5. Gestión de tareas y consulta de usuarios: admite operaciones CRUD de tareas de Feishu y búsqueda de información de usuarios, facilitando la asociación de tareas y personas en los documentos.

Este proyecto consigue una obtención, edición y búsqueda inteligentes en tu flujo diario de trabajo con documentos de Feishu, además de ampliar la gestión de tareas y usuarios, mejorando la eficiencia y la experiencia del procesamiento de contenido.

💡 Recomendación del proyecto

Si usas Claude Code, se recomienda combinarlo con claude-ip-guard, detecta automáticamente la ubicación geográfica de la IP y bloquea las visitas a regiones restringidas, evitando la suspensión de la cuenta de Claude por cambios de red.

🎬 Vídeo de demostración de uso

Puedes conocer el efecto objetivo y el proceso de uso del MCP a través de los siguientes vídeos:

⭐ Dale una estrella a este proyecto y no te pierdas las nuevas func y actualizaciones importantes. Seguir el proyecto te permitirá estar al día de las nuevas funciones, correcciones y optimizaciones y lo seguirá utilizando de forma eficiente. Tu apoyo también nos ayudará dar mejor forma y desarrollo del proyecto. ⭐

🛠️ Detalles de las funciones de las herramientas

🎨 Funciones de estilo admitidas (básicamente compatible con todos los formatos de Markdown)

• Estilos de texto: negrita, cursiva, subrayado, tachado, código en línea.

• Colores de texto: gris, marrón, naranja, amarillo, verde, azul, morado.

• Alineación: izquierda, centro, derecha.

• Niveles de encabezado: admite títulos de nivel 1 a 9.

• Bloques de código: admite resaltado de sintaxis para varios lenguajes de programación.

• Listas: listas ordenadas (numeradas) y listas no ordenadas (con viñetas).

• Imágenes: admite imágenes locales y remotas.

• Fórmulas: inserte fórmulas matemáticas en los bloques de texto y admite sintaxis LaTeX.

• Diagramas Mermaid: admite diagramas de flujo, diagramas de secuencia, mapas mentales, diagramas de clases, diagramas circulares, etc.

• Tablas: admite tablas de varias filas; las celdas pueden incluir múltiples tipos de contenido como texto, títulos, listas y bloques de código.

• 💦 Notas / Pizarra: admite la creación de una pizarra en los documentos de Feishu, para mostrar contenidos más rico y diversificado.

📈 Plan semanal: Mejora de la eficiencia de la herramienta

• ~~ Simplificar el conjunto de herramientas: de 21 herramientas a 13, eliminar redundancias y centrarse en las funciones centrales...~~ 0.0.15 ✅

• ~~ Optimizar la descripción: de más de 7000 tokens a más de 3000 tokens, simplificar prompts y ahorrar tokens en las peticiones~~ 0.0.15 ✅

• ~~ Mejoras por lotes: añade actualización por lotes y subida de imágenes por lotes, para una eficiencia de acceso de un 50% por operación.~~ 0.0.15 ✅

• Optimización de procesos: reducir las llamadas de múltiples pasos y lograr en un solo clic la finalización de tareas complejas.

• Compatibilidad con varios tipos de credenciales: incluye tenant\_access\_token y user\_access\_token, para satisfacer los escenarios de autenticación (Sus camios de like en la configuración de la aplicación de Feishu) 0.0.16 ✅

• Soporte de inicio de sesión del usuario de Cursor: conveniente para autenticar Internet de usuarios en la plataforma ---No se realizará, no es necesario ❌

• Admite diagramas Mermaid: diagramas de flujo, diagramas de secuencia, etc., para enriquecer el contenido de los documentos 0.1.11 ✅

• Soporte de creación de tablas: crear tablas complejas con variados tipos de bloques y control de estilos 0.1.2 ✅

• Soporte de multi-usuario user Feishu: un despliegue para múltiples usuarios 0.1.3 ✅

• Soportar el refresh automático de un user\_access\_token: no requiere autorización frecuente, mejora la ergonomía 0.1.6 ✅

• Soportar la verificación del alcance: verificación de la autorización de la app para que cumpla los requisitos de la herramienta. Si no se cumple, se proporciona una guía amigable para la utilización más fluida 0.1.7 ✅

• Soporte en la creación de contenidos de pizarra: comparado con Mermaid, la pizarra puede mostrar contenido más rico y variado, con una experiencia de visualización más agradable (con cambio en la configuración de la aplicación de Feishu) 0.1.7 ✅

• Extraer feishuAppId y feishuAppSecret desde variables de entorno: se separa la configuración de Feishu de las variables de entorno para poder configurarlos en clientes como Cursor y que un servicio pueda ser compartido en varios equipos.

• Soporte para base de conocimientos y 'Mi base de documentos': implementar recorrido de nodos, creación de nodos, creación de archivos, búsqueda en base y documentación (Suscribió in the Feishu app configuration) 0.1.8 ✅

• Notificación de nuevas versiones: cuando se publique una nueva versión, se informará al usuario con avisos y descripciones relevantes.

• Problema de autenticación de los usuarios en modo stdio: corrección del fallo de autenticación de usuario en el modo stdio 0.1.9 ✅

• Configurabilidad de la función de comprobación de permisos: conviértela en una opción configurable; controlable a través de la variable de entorno FEISHU_SCOPE_VALIDATION o el parámetro de línea de comandos --feishu-scope-validation; está habilitada por defecto para satisfacer distintos escenarios de uso 0.2.0 ✅

• Optimizar el directorio de caché: guardar cachés de tokens en el directorio de configuración a nivel de sistema 0.2.2 ✅ gracias a Molunerfinn, leeeezx, Master-cai y otras sugerencias y contribuciones.

• Optimizar el código relacionado con las herramientas MCP: reconstruir la estructura del código para sentar bases para futuras funcionalidades 0.2.3 ✅

• Soporte de gestión de tareas: list, create, update, delete en Feishu: subcuentas y gestión de miembros 0.2.4 ✅

• Soporte de consulta de usuarios: busque por nombre o por ID en lote, ayudando en la asignación de tareas y la colaboración en documentos 0.2.4 ✅

• Extracción de la capa Tool API: se una nueva capa Tool API con correspondencia biunívoca con la capa de tool, para unificar la validación de parámetros, la conversión de datos, el mapeo de errores, etc. ✅

• Compatibilidad con modo CLI: compatible con llamada CLI feishu-tool <tool-name> '<json>', para facilitar scripts y escenarios de automatización 0.2.6 ✅

• Skill terminado: se proporciona Feishu-Skill para guiar agentes de IA como Claude Code en el uso de la CLI de feishu-mcp en escenarios adecuados 0.2.6 ✅

🔧 Tutorial de configuración de Feishu

⚠️ Nota importante: antes de usar, debe completar la configuración de Feishu App; de lo contrario, no podrá usar la herramienta.

Las explications sobre cómo crear una aplicación de Feishu y obtener credenciales de la aplicación puedes encontrarlas en el tutorial oficial.

Pasos detallados de configuración: para registrar la aplicación, configurar los permisos, agregar permisos de acceso a documentos, consulte la guía paso a paso FEISHU_CONFIG.md.

🏃♂️ Inicio rápido

Forma 1: con NPM

npx feishu-mcp@latest --feishu-app-id=<你的飞书应用ID> --feishu-app-secret=<你的飞书应用密钥> --feishu-auth-type=<tenant/user> --enabled-modules=<document,task>

Forma 2: Ejecución local

1. Clonar el repositorio

   git clone https://github.com/cso1z/Feishu-MCP.git
   cd Feishu-MCP

2. Configurar variables (copie .env.example y guárdelo como .env)

3. Editar el archivo .env Ubique el archivo .env en el directorio raíz del project y ábralo con un editor de texto cualquiera, luego introduzca sus credenciales de Feishu:

   FEISHU_APP_ID=cli_xxxxx
   FEISHU_APP_SECRET=xxxxx
   PORT=3333
   FEISHU_AUTH_TYPE=tenant/user
   FEISHU_ENABLED_MODULES=document,task

4. Ejecutar el servidor

   • Instalar dependencias

     pnpm install

   • Iniciar servicio

     pnpm run dev

   • Usar Docker Compose

     • Iniciar servicio

       docker-compose up -d

     • Ver logs

       docker-compose logs -f

🖥️ Herramienta CLI feishu-tool

Desde la versión 0.2.5, el paquete npm de feishu-mcp incluye la herramienta CLI independiente feishu-tool, que puede invocar directamente todas las herramientas de Feishu desde el terminal, un script de shell o un agente de IA, sin necesidad de iniciar un servidor MCP.

Instalación

# 全局安装（推荐）
npm install -g feishu-mcp@latest

Configuración

# 1. 查看 CLI 概览（子命令 + 可用工具集）
feishu-tool --help

# 2. 查看初始化指南（获取 App ID / Secret 的步骤说明）
feishu-tool guide

# 3. 写入凭证
feishu-tool config set FEISHU_APP_ID cli_xxxxx
feishu-tool config set FEISHU_USER_KEY "$(node -e 'console.log(crypto.randomUUID())')"
# FEISHU_USER_KEY 建议每个本地用户或客户端保持唯一

# 4. 查看当前配置（确认写入正确）
feishu-tool config

# 5. 查看某个工具的详细参数
feishu-tool help create_feishu_document

# 6. 调用工具
feishu-tool create_feishu_document '{"title": "测试文档"}'

Para consultar la explicación completa de parámetros, consulte Feishu-Skill Docs.

⚙️ Configuración del proyecto

Configuración de variables de entorno

Descripción de los módulos funcionales

Configuración por archivo (aplica a Cursor, Cline, etc.)

Modo stdio (recomendado)

{
  "mcpServers": {
    "feishu-mcp": {
      "command": "npx",
      "args": ["-y", "feishu-mcp@latest", "--stdio"],
      "env": {
        "FEISHU_APP_ID": "<你的飞书应用ID>",
        "FEISHU_APP_SECRET": "<你的飞书应用密钥>",
        "FEISHU_AUTH_TYPE": "<tenant/user>",
        "FEISHU_ENABLED_MODULES": "document,task",
        "FEISHU_USER_KEY": "<你的用户标识>"
      }
    }
  }
}

Modo SSE

{
  "mcpServers": {
    "feishu_local": {
      "url": "http://localhost:3333/sse?userKey=123456"
    }
  }
}

Modo HTTP Streamable

{
  "mcpServers": {
    "feishu_streamable": {
      "url": "http://localhost:3333/mcp?userKey=123456"
    }
  }
}

Autenticación Bearer Token (opcional)

Cuando se configura la variable de entorno MCP_BEARER_TOKEN, todos los puntos finales de HTTP/SSE/StreamableHTTP exigirán la cabecera Authorization: Bearer <token> en la solicitud. Es adecuada para despliegues expuestos en internet, previniendo accesos no autorizados.

Ejemplo de configuración:

# .env 文件
MCP_BEARER_TOKEN=your-secret-token-here

Ejemplo de configuración de cliente (modo SSE + autenticación Bearer):

⚠️ Actualmente la mayoría de clientes MCP (como Cursor, Cline) no admiten personalizar las headers de las peticiones en conexiones SSE/StreamableHTTP. Si quiere usar la autenticación Bearer, confirme que su client soporta enviar la cabecera Authorization o use un proxy inverso (como Nginx) para la autenticación previa del servidor.

Para clientes o llamadas de API que admitan custom header:

# SSE 连接示例
curl -H "Authorization: Bearer your-secret-token-here" http://localhost:3333/sse?userKey=123456

# StreamableHTTP 请求示例
curl -X POST -H "Authorization: Bearer your-secret-token-here" -H "Content-Type: application/json" http://localhost:3333/mcp?userKey=123456

⚠️ Aviso importante: el userKey en la URL identifica al usuario en la conexión, es una configuración muy importante; por favor, complétala y hazla lo más aleatoria posible.

Formas de pasar userKey: se soportan dos maneras de pasar la identidad del usuario

• Parámetro de consulta en URL: ?userKey=123456 (recomendado, fácil de configurar)

• Cabecera de solicitud: user-key: 123456 (adecuado para escenarios donde es necesario ocultar el parámetro)

正文接下来: 使用建议 (important)

1. Se recomienda especificar una carpeta:

Al crear un documento nuevo, se recomienda proporcionar de forma proactiva el token de la carpeta de Feishu (puede ser una carpeta concreta o la carpeta raíz), de manera que se pueda localizar y gestionar el documento de forma más eficiente. Si no se está seguro de la subcarpeta concreta, se puede permitir que el LLM busque automáticamente el subdirectorio más adecuado dentro de la carpeta que se haya especificado para crear el documento.

¿Cómo obtener el token de la carpeta? Abre la página de carpetas de Feishu y copia el enlace (por ejemplo, https://.../drive/folder/xxxxxxxxxxxxxxxxxxxxxx). El token es la última cadena de caracteres del enlace (por ejemplo, xxxxxxxxxxxxxxxxxxxxxx); por favor, no expongas el token real.

2. Notas sobre la ruta de subida de imágenes

Al ejecutar MCP localmente, las rutas de imagen admiten tanto rutas absolutas locales como imágenes mediante http/https; en un entorno de servidor, solo se admiten enlaces de imágenes externas (debido a la limitación de longitud de los parámetros al llamar al MCP desde cursor, no se admite por el momento la subida directa del archivo de imagen; usa la ruta de imagen o el enlace para subirla).

3. Instrucciones de uso de fórmulas:

En un bloque de texto pueden mezclarse texto normal y fórmulas. Las fórmulas utilizan sintaxis LaTeX, como 1+2=3, \frac{a}{b}, \sqrt{x}, etc. Se admite incluir varias fórmulas y texto normal en el mismo bloque de texto.

4. Usar la autenticación de usuario de Feishu:

La autenticación user y la autenticación tenant se diferencian a la hora de añadir permisos, por lo que la primera vez que se cambie de tenant a user hay que prestar atención a los permisos configurados; para distinguir a los distintos usuarios, es necesario pasar el identificador de usuario userKey. Se admiten dos formas:

• Parámetro de consulta en la URL: añade ?userKey=123456 a la URL del servidor MCP.

• Cabecera de solicitud: envía la cabecera user-key: 123456.

Este valor es el identificador único del usuario, así que es mejor que sea cuanto más aleatorio mejor al configurarlo.

5. Se recomienda encarecidamente usar la autenticación user:

La autenticación tenant tiene numerosas limitaciones; por ejemplo, en el acceso a archivos, en la compatibilidad con la API abierta de Feishu (no admite la búsqueda de documentos wiki) y en los registros de creación y edición de documentos. En todos estos aspectos, la autenticación tenant no es tan buena como la autenticación user.

6. Funciones de tareas e información de usuarios:

¿Quieres que la IA te ayude a gestionar tareas de Feishu such as listar pendientes, crear tareas, asignar responsables, o consultar información de compañeros? Necesitas dos pasos: ① usar autenticación user (en el formato tenant no se ofrecen estas capacidades); ② establecer FEISHU_ENABLED_MODULES=document,task en la configuración. Tras habilitar task, la función de consulta de usuarios estará disponible automáticamente, sin necesidad de configuración adicional.

7. Usar la versión internacional de Lark:

La versión local de Feishu no necesita configuración adicional. Si tu equipo usa la versión internacional de Lark o un servicio de Feishu autogestionado, deberá configurarse lo siguiente:

FEISHU_BASE_URL=https://open.larksuite.com/open-apis
FEISHU_AUTH_BASE_URL=https://accounts.larksuite.com

8. Separación del acceso desde red interna y la devolución de llamada desde red externa:

Si el cliente MCP accede al servicio a través de una dirección de red interna (por ejemplo, http://feishu-mcp:3333/mcp), pero la devolución de llamada OAuth de Feishu debe usar de dominio público, es posible configurarlo así:

FEISHU_PUBLIC_BASE_URL=https://somo-feishu-mcp.yfgao.net

De esta forma, el cliente puede seguir conectándose a la dirección de red interna, mientras que el enlace de autorización devuelto al usar https://somo-feishu-mcp.yfgao.net/callback como dirección de callback.

9. Cambio dinámico de userKey en una arquitectura de retransmisión multi-inquilino:

En una architecture de retransmisión multiinquilino, el sistema agente de la primera etapa para el servicio MCP de Feishu de forma unificada a través de herramientas de gestión de la integración. Dado que las instancias subyacentes del servicio MCP se reutilizan a nivel de sesión, las solicitudes de los diferentes usuarios se ejecutan realmente en el contexto de una sesión compartida. Por tanto, el sistema necesita admitir el cambio dinámico basado en user-key transmitido en la cabecera de soltura, para lograr el aislamiento de la identidad del inquilino y la inyección de contexto, y así satisfacer las necesidades de acceso concurrent de múltiples usuarios.

Cómo cambiar el userKey:

• En este modo HTTP Streamable, las solicitudes posteriores pueden act actualizando el identificador de usuario de la sesión actual mediante la cabecera user-key.

• Forma de enviarlo: añade la cabecera user-key: <nuevo identificador> en la solicitud.

• Ejemplo de uso: cuando el usuario A termina una operación, la solicitud del usuario B incluye user-key: <nueva persona>, y el sistema cambia automáticamente la sesión al contexto del usuario B.

Nota: esta función solo es válida para el modo HTTP Streamable; los modos SSE y stdio no admiten el cambio dinámico.

🚨 Solución de problemas

Solución de problemas de permisos

Primero consulta los problemas de configuración en Tutorial paso a paso FEISHU_CONFIG.md.

Confirmación del problema

1. Verificar los permisos de la aplicación: asegúrate de que la aplicación tenga los permisos de acceso necesarios documentos.

2. Verificar la autorización del documento: confirma que el documento ha sido autorizado a la aplicación o al grupo de la aplicación.

3. Comprobar el ámbito de disponibilidad: asegúrate de que el ámbito de disponibilidad de la versión publicada de la aplicación incluya al propietario del documento.

Verificación e investigación de permisos

1. Obtén el token: obtener el app_access_token de una aplicación creada por tu cuenta

2. Usa el token obtenido en el paso 1 para verificar si tienes permiso de acceso al documento: obtener información básica del documento

Preguntas frecuentes

• No encuentra la aplicación: comprueba si la aplicación se ha publicado y si su ámbito de disponibilidad está configurado.

• Permisos insuficientes: consulta las Preguntas frecuentes sobre documentos en la nube

• Problemas de acceso a la base de conocimientos: consulta las Preguntas frecuentes sobre la base de conocimiento

📚 Wiki para desarrolladores

Documentación detallada de desarrollo y guías técnicas para proporcionar una orientación integral a los que aprenden:

• Inicio del Wiki - Índice completo y navegación rápida

• Diseño de la arquitectura - Descripción de la arquitectura y la pila tecnológica

• Explicación detallada de los módulos centrales - Detalles de implementación y ejemplos de código de cada módulo

• Autenticación y autorización - Gestión de Token y soporte multi-usuario

• Guía del desarrollador - Configuración del entorno, proceso contrac, descubrimiento y depuración

• Referencia de API - Documentación detallada de todas las funciones de la herramienta

• Buenas prácticas - Convenciones de código, optimización del rendimiento y prácticas de seguridad

• Implementación del protocolo MCP - Explicación y transporte del protocolo MCP

💖 Apoyar el proyecto

Si este proyecto te ha sido de utilidad, considera:

• ⭐ Dar una estrella al proyecto

• 🐛 Informar de erroes y problemas

• 💡 Sug buen funcionalidades

• 📖 Mejorar la documentación

• 🔀 Enviar una Pull Request

¡Tu apoyo es nuestra fuerza motriz!

Star History