Feishu/Lark OpenAPI MCP

MCP de OpenAPI de Feishu/Lark

inglés |中文

Recuperación de documentación para desarrolladores (MCP) | Documento oficial

Aviso de la versión beta : Esta herramienta se encuentra actualmente en fase beta. Las funciones y API pueden cambiar, así que manténgase al tanto de las nuevas versiones.

Esta es la herramienta oficial de Feishu/Lark para el Protocolo de Contexto de Modelo (MCP) de OpenAPI, diseñada para ayudar a los usuarios a conectarse rápidamente a la plataforma Feishu/Lark y facilitar la colaboración eficiente entre los agentes de IA y Feishu/Lark. Esta herramienta encapsula las interfaces de la API de Plataforma Abierta de Feishu/Lark como herramientas MCP, lo que permite a los asistentes de IA llamar directamente a estas interfaces e implementar diversos escenarios de automatización, como el procesamiento de documentos, la gestión de conversaciones, la programación de calendarios y más.

Características

• Kit de herramientas API completo de Feishu/Lark: encapsula casi todas las interfaces API de Feishu/Lark, incluidas la gestión de mensajes, la gestión de grupos, las operaciones de documentos, los eventos de calendario, Bitable y otras áreas funcionales centrales.
• Soporte de autenticación dual:
  • Admite autenticación mediante token de acceso a la aplicación
  • Admite autenticación de token de acceso de usuario
• Protocolos de comunicación flexibles:
  • Admite el modo de flujo de entrada/salida estándar (stdio), adecuado para la integración con herramientas de IA como Trae/Cursor/Claude
  • Admite el modo de eventos enviados por el servidor (SSE), lo que proporciona interfaces basadas en HTTP
• Admite múltiples métodos de configuración, adaptándose a diferentes escenarios de uso.

Lista de herramientas

Puede encontrar una lista completa de todas las herramientas Feishu/Lark compatibles en tools.md , donde las herramientas están categorizadas por proyecto y versión con descripciones.

Preparación

Creación de una aplicación Feishu/Lark

Antes de utilizar la herramienta lark-mcp, debe crear una aplicación Feishu/Lark:

1. Visita la Plataforma Abierta Feishu o la Plataforma Abierta Lark e inicia sesión
2. Haga clic en "Consola" y cree una nueva aplicación
3. Obtenga el ID de la aplicación y el secreto de la aplicación, que se utilizarán para la autenticación de la API
4. Agregue los permisos necesarios para su aplicación según su escenario de uso
5. Si necesita llamar a las API como usuario, configure las URL de redireccionamiento de OAuth 2.0 y obtenga tokens de acceso de usuario

Para obtener pautas detalladas sobre la creación y configuración de aplicaciones, consulte la Documentación de la plataforma abierta Feishu: Creación de una aplicación o la Documentación de la plataforma abierta Lark .

Instalación de Node.js

Antes de utilizar la herramienta lark-mcp, debe instalar el entorno Node.js.

Instalación de Node.js en macOS

1. Usando Homebrew (Recomendado) :
   brew install node
2. Usando el instalador oficial :
   • Visita el sitio web de Node.js
   • Descargue e instale la versión LTS
   • Luego de la instalación, verificar en la terminal:
     node -v npm -v

Instalación de Node.js en Windows

1. Usando el instalador oficial :
   • Visita el sitio web de Node.js
   • Descargue y ejecute el instalador de Windows (archivo .msi)
   • Siga el asistente de instalación para completar la instalación.
   • Después de la instalación, verifique en el símbolo del sistema:
     node -v npm -v
2. Usando nvm-windows :
   • Descargar nvm-windows
   • Instalar nvm-windows
   • Utilice nvm para instalar Node.js:
     nvm install latest nvm use <version_number>

Instalación

Instalar la herramienta lark-mcp globalmente:

Guía de uso

Uso con Trae/Cursor/Claude

Para integrar la funcionalidad de Feishu/Lark en herramientas de IA como Trae, Cursor o Claude, agregue lo siguiente a su archivo de configuración:

Para acceder a las API con identidad de usuario, puede agregar un token de acceso de usuario:

Configuración de API personalizada

De forma predeterminada, el servicio MCP habilita las API comunes. Para habilitar otras herramientas o solo API o ajustes preestablecidos específicos, puede especificarlos mediante el parámetro -t (separados por comas):

Colecciones de herramientas preestablecidas en detalle

La siguiente tabla detalla cada herramienta API y su inclusión en diferentes colecciones de ajustes preestablecidos, lo que le ayudará a elegir el ajuste preestablecido adecuado para sus necesidades:

Nota : En la tabla, "✓" indica que la herramienta está incluida en ese preajuste. Usar -t preset.xxx solo habilitará las herramientas marcadas con "✓" en la columna correspondiente.

Configuración avanzada

Parámetros de la línea de comandos

La herramienta lark-mcp mcp proporciona varios parámetros de línea de comandos para una configuración flexible del servicio MCP:

Ejemplos de uso de parámetros

1. Uso básico (usando la identidad de la aplicación):
   lark-mcp mcp -a cli_xxxx -s yyyyy
2. Usando la identidad del usuario :
   lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

   Nota : Los tokens de acceso de usuario se pueden obtener mediante el proceso de autorización de Feishu Open Platform o Lark Open Platform , o bien, puede usar la consola de depuración de la API para obtenerlos. Tras usar un token de acceso de usuario, las llamadas a la API se realizarán con la identidad de ese usuario.

3. Configuración del modo de token específico :
   lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token

   Nota : Esta opción permite especificar explícitamente el tipo de token que se usará al llamar a las API. El modo auto (predeterminado) lo determinará el LLM al llamar a la API.

4. Especificación de dominios Lark o KA :
   # Lark international version lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.larksuite.com # Custom domain (KA domain) lark-mcp mcp -a <your_app_id> -s <your_app_secret> -d https://open.your-ka-domain.com
5. Habilitar solo herramientas API específicas u otras herramientas API :
   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create

   Nota : El parámetro -t admite las siguientes colecciones de herramientas preestablecidas:

   • preset.default : conjunto de herramientas predeterminado que contiene todas las herramientas preestablecidas
   • preset.im.default - Herramientas relacionadas con la mensajería instantánea, como gestión de grupos, envío de mensajes, etc.
   • preset.bitable.default : herramientas relacionadas con Bitable, como creación de tablas, gestión de registros, etc.
   • preset.bitable.batch : herramientas de operación por lotes de Bitable, que incluyen funciones de creación y actualización de registros por lotes
   • preset.doc.default : herramientas relacionadas con los documentos, como lectura de contenido, gestión de permisos, etc.
   • preset.task.default : herramientas relacionadas con la gestión de tareas, como creación de tareas, gestión de miembros, etc.
   • preset.calendar.default : herramientas de gestión de eventos de calendario, como creación de eventos de calendario, consulta de estado libre/ocupado, etc.

6. Uso del modo SSE con un puerto y host específicos :
   lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000
7. Configuración del idioma de las herramientas en chino :
   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

   Nota : Configurar el idioma en chino ( -l zh ) puede consumir más tokens. Si tiene problemas con el límite de tokens al integrar con modelos de idiomas grandes, considere usar la configuración predeterminada en inglés ( -l en ).

8. Establecer el formato del nombre de la herramienta en CamelCase :
   lark-mcp mcp -a cli_xxxx -s yyyyy -c camel

   Nota : Al configurar el formato del nombre de la herramienta, puede cambiar cómo aparecen los nombres en el MCP. Por ejemplo, im.v1.message.create en diferentes formatos:

   • formato de serpiente (predeterminado): im_v1_message_create
   • formato camello: imV1MessageCreate
   • formato kebab: im-v1-message-create
   • formato de punto: im.v1.message.create

9. Uso de variables de entorno en lugar de parámetros de línea de comandos :
   # Set environment variables export APP_ID=cli_xxxx export APP_SECRET=yyyyy # Start the service (no need to specify -a and -s parameters) lark-mcp mcp
10. Usando el archivo de configuración :

Además de los parámetros de la línea de comandos, también puedes usar un archivo de configuración en formato JSON para establecer parámetros:

Ejemplo de archivo de configuración (config.json):

Nota : Los parámetros de la línea de comandos tienen mayor prioridad que el archivo de configuración. Al usar tanto los parámetros de la línea de comandos como el archivo de configuración, estos últimos anularán la configuración correspondiente en el archivo de configuración.

11. Modos de transporte :

lark-mcp admite dos modos de transporte:

1. Modo stdio (predeterminado/recomendado) : adecuado para la integración con herramientas de IA como Trae/Cursor o Claude, comunicándose a través de flujos de entrada/salida estándar.

2. Modo SSE : proporciona una interfaz HTTP basada en eventos enviados por el servidor, adecuada para escenarios donde la ejecución local no es posible.

Después del inicio, el punto final SSE será accesible en http://<host>:<port>/sse .

Preguntas frecuentes

• Problema : No se puede conectar a la API de Feishu/Lark. Solución : Verifique su conexión de red y asegúrese de que los valores APP_ID y APP_SECRET sean correctos. Verifique que pueda acceder a la API de plataforma abierta de Feishu/Lark; es posible que necesite configurar un proxy.
• Problema : Error al usar user_access_token. Solución : Verifique si el token ha caducado. user_access_token suele tener una validez de 2 horas y debe actualizarse periódicamente. Puede implementar un mecanismo de actualización automática de tokens.
• Problema : No se pueden llamar ciertas API tras iniciar el servicio MCP, con errores de permisos insuficientes. Solución : Compruebe si su aplicación ha obtenido los permisos de API correspondientes. Algunas API requieren permisos adicionales de alto nivel, que se pueden configurar en la Consola del desarrollador o en la Consola del desarrollador de Lark . Asegúrese de que los permisos estén aprobados.
• Problema : Fallan las llamadas a la API relacionadas con la carga/descarga de imágenes o archivos. Solución : La versión actual no admite la función de carga/descarga de archivos e imágenes. Estas API serán compatibles en futuras versiones.
• Problema : La línea de comandos muestra caracteres ilegibles en Windows. Solución : Cambie la codificación de la línea de comandos a UTF-8 ejecutando chcp 65001 en el símbolo del sistema. Si usa PowerShell, es posible que deba cambiar la fuente del terminal o la configuración de PowerShell.
• Problema : Errores de permisos durante la instalación. Solución : En macOS/Linux, use sudo npm install -g @larksuiteoapi/lark-mcp para la instalación o modifique los permisos de la ruta de instalación global de npm. Los usuarios de Windows pueden intentar ejecutar el símbolo del sistema como administrador.
• Problema : se excedió el límite de tokens después de iniciar el servicio MCP Solución : intente usar -t para reducir la cantidad de API habilitadas o use un modelo que admita tokens más grandes (como claude3.7).
• Problema : No se puede conectar ni recibir mensajes en modo SSE. Solución : Compruebe si el puerto ya está en uso e intente cambiar a otro. Asegúrese de que el cliente esté conectado correctamente al endpoint SSE y esté gestionando el flujo de eventos.

Enlaces relacionados

• Plataforma abierta Feishu
• Plataforma Abierta Internacional Lark
• Documentación de la API de plataforma abierta de Feishu
• Documentación de la API de la plataforma abierta Lark
• Sitio web de Node.js
• Documentación de npm

Comentario

Agradecemos cualquier problema que nos ayude a mejorar esta herramienta. Si tienes alguna pregunta o sugerencia, compártela en el repositorio de GitHub.