MCP de OpenAPI de Feishu/Lark

Inglés | Chino

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 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 "Comenzar" 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 Cursor/Claude

Para integrar la funcionalidad de Feishu/Lark en herramientas de IA como 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 avanzada

Parámetros de la línea de comandos

La herramienta lark-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
3. Especificación del dominio internacional de Lark :
   lark-mcp mcp -a cli_xxxx -s yyyyy -d https://open.larksuite.com
4. Habilitar solo herramientas API específicas :
   lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create
5. 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
6. 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 ).

7. 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

8. 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

Uso del 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.

Uso del token de acceso de usuario

Si necesita llamar a las API como un usuario específico, puede hacerlo especificando un token de acceso de usuario:

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

Especificación de dominios personalizados

Si está utilizando la versión internacional de Lark o un dominio personalizado, puede especificarlo mediante el parámetro -d :

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 Cursor o Claude, comunicándose a través de flujos de entrada/salida estándar.
   lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
2. Modo SSE : proporciona una interfaz HTTP basada en eventos enviados por el servidor, adecuada para aplicaciones web o escenarios que requieren interfaces de red.
   # Default listens only on localhost lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse -p 3000 # Listen on all network interfaces (allowing remote access) lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m sse --host 0.0.0.0 -p 3000
   Después del inicio, el punto final SSE será accesible en http://<host>:<port>/sse .

Habilitación de más API

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

Lista de API compatibles predeterminadas

De forma predeterminada, el servicio MCP habilita las siguientes API:

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 o usar app_access_token.
• 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.