Feishu/Lark OpenAPI MCP

Español | 中文

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

⚠️ Versión Beta Aviso: Esta herramienta se encuentra actualmente en fase Beta. Las características y APIs pueden cambiar, así que por favor manténgase actualizado con los lanzamientos de versiones.

Esta es la herramienta oficial OpenAPI MCP (Model Context Protocol) de Feishu/Lark diseñada para ayudar a los usuarios a conectarse rápidamente a la plataforma Feishu/Lark y permitir una colaboración eficiente entre los Agentes AI y Feishu/Lark. La herramienta encapsula las interfaces API de la Plataforma Abierta Feishu/Lark como herramientas MCP, permitiendo a los asistentes de IA llamar directamente a estas interfaces e implementar varios escenarios de automatización como procesamiento de documentos, gestión de conversaciones, programación de calendarios, etc.

Características

• Kit completo de herramientas de API de Feishu/Lark: Encapsula casi todas las interfaces API de Feishu/Lark, incluida la gestión de mensajes, la gestión de grupos, las operaciones de documentos, los eventos de calendario, Bitable y otras áreas funcionales básicas.
• Sistema Génesis AI: Crea aplicaciones completas de Lark Base a partir de requisitos en lenguaje natural con la generación impulsada por IA
  • Analiza los requisitos y sugiere estructuras de datos óptimas
  • Genera tablas, campos, vistas y reglas de automatización
  • Crear diagramas ER y documentación
  • Optimizar bases existentes con recomendaciones de IA
• Soporte de autenticación dual
  • Soporta autenticación App Access Token
  • Admite la autenticación con 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 servidor (SSE), que proporciona interfaces basadas en HTTP
• Avisos inteligentes: Avisos MCP para flujos de trabajo comunes de Génesis
• Soporta múltiples métodos de configuración, adaptándose a diferentes escenarios de uso

Lista de herramientas

Una lista completa de todas las herramientas Feishu/Lark soportadas se puede encontrar 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, es necesario crear una aplicación Feishu/Lark:

1. Visite la Plataforma AbiertaFeishu o la Plataforma Abierta Lark e inicie sesión
2. Haga clic en "Consola" y cree una nueva aplicación
3. Obtenga el App ID y el App Secret, que se utilizarán para la autenticación de la API
4. Añada los permisos necesarios para su aplicación en función de su escenario de uso
5. Si necesita llamar a APIs como usuario, configure URLs de redirección OAuth 2.0 y obtenga tokens de acceso de usuario

Para obtener directrices 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, es necesario instalar el entorno Node.js.

Instalación de Node.js en macOS

1. Usando Homebrew (Recomendado):

   brew install node

2. Usando el instalador oficial:

   • Visite el sitio web de Node.js
   • Descarga e instala la versión LTS
   • Después de la instalación, verifique en la terminal:

     node -v npm -v

Instalación de Node.js en Windows

1. Usando el Instalador Oficial:

   • Visite 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. Uso de nvm-windows:

   • Descargue nvm-windows
   • Instale nvm-windows
   • Utilice nvm para instalar Node.js:

     nvm install latest nvm use <version_number>

Instalación

Instale la herramienta lark-mcp de forma global:

npm install -g @larksuiteoapi/lark-mcp

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, añade lo siguiente a tu archivo de configuración:

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "<your_app_id>", "-s", "<your_app_secret>" ] } }

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

{ "mcpServers": { "lark-mcp": { "command": "npx", "args": [ "-y", "@larksuiteoapi/lark-mcp", "mcp", "-a", "<your_app_id>", "-s", "<your_app_secret>", "-u", "<your_user_token>" ] } }

Configuración personalizada de la API

Por defecto, el servicio MCP habilita las API comunes. Para habilitar otras herramientas o sólo API específicas o preestablecidas, puede especificarlas mediante el parámetro -t (separado por comas):

lark-mcp mcp -a <tu_id_app> -s <tu_secreto_app> -t im.v1.message.create,im.v1.message.list,im.v1.chat.create,preset.calendar.default

Colecciones de herramientas preestablecidas en detalle

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

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

Sistema Génesis AI

El Sistema Genesis AI permite crear aplicaciones Lark Base completas a partir de requisitos de lenguaje natural. Cuando se utiliza MCP, Genesis proporciona tanto herramientas como indicaciones para ayudarle a crear aplicaciones rápidamente.

Uso de Génesis con MCP

1. Habilite las herramientas deGénesis:

   lark-mcp mcp -a <su_id_app> -s <su_secreto_app> -t preset.genesis.default

2. Avisos de Génesis disponibles (registrados automáticamente con el servidor MCP):

   • genesis_create_base - Crear una base Lark completa a partir de los requisitos
   • genesis_migrate_excel - Migrar Excel a Lark Base con optimización AI
   • genesis_template_crm - Generar sistema CRM utilizando plantillas
   • genesis_optimize_base - Optimizar base existente con AI
   • genesis_ai_features - Añadir características con IA a una base

3. Ejemplo de uso en AI Assistant:

   "Utilice la instrucción genesis_create_base para crear un sistema de gestión de tareas con los siguientes requisitos: - Realizar un seguimiento de las tareas con prioridad y fechas de vencimiento - Asignar tareas a los miembros del equipo - Supervisar el progreso del proyecto - Generar informes semanales"

4. Herramientas de Genesis disponibles:

   • genesis.builtin.create_base - Crear base a partir de requisitos
   • genesis.builtin.analyze_requirements - Analizar y sugerir estructura
   • genesis.builtin.generate_er_diagram - Genera diagramas ER
   • genesis.builtin.optimize_base - Optimizar bases existentes
   • genesis.builtin.create_view - Crear vistas personalizadas (cuadrícula, kanban, calendario, etc.)
   • genesis.builtin.create_dashboard - Crear cuadros de mando copiando y personalizando
   • genesis.builtin.create_automation - Crear flujos de trabajo de automatización con disparadores y acciones
   • genesis.builtin.create_filter_view - Crear vistas de filtro para hojas de cálculo

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 (utilizando la identidad de la aplicación):

   lark-mcp mcp -a cli_xxxx -s yyyyy

2. Uso de la identidad de usuario:

   lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz

   Nota: Los tokens de acceso de usuario pueden obtenerse a través del proceso deautorizaciónde Feishu Open Platform o de Lark Open Platform, o puede utilizar la consola de depuración de API para obtenerlos. Después de utilizar 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 le permite especificar explícitamente qué tipo de token utilizar al llamar a las API. El modo automático (por defecto) será determinado por el LLM al llamar a la API.

4. Especificación de dominios Lark o KA:

   # Versión internacional de Lark lark-mcp mcp -a <su_id_app> -s <su_secreto_app> -d https://open.larksuite.com # Dominio personalizado (dominio KA) lark-mcp mcp -a <su_id_app> -s <su_secreto_app> -d https://open.your-ka-domain.com

5. Habilitar sólo 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.light - Conjunto de herramientas ligero con menos herramientas pero de uso común, adecuado para escenarios que requieren un uso reducido de tokens
   • preset.default - Conjunto de herramientas por defecto 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.base.default - Herramientas relacionadas con la base, como creación de tablas, gestión de registros, etc.
   • preset.base.batch - Herramientas de operaciones por lotes de la base, incluidas las funciones de creación y actualización de registros por lotes
   • preset.doc.default - Herramientas relacionadas con documentos, como lectura de contenido de documentos, 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.
   • preset.genesis.default - Herramientas impulsadas por Genesis AI para crear y optimizar aplicaciones Lark Base

6. Uso del modo SSE con puerto y host específicos:

   lark-mcp mcp -a cli_xxxx -s yyyyy -m sse --host 0.0.0.0 -p 3000

7. Establecer el idioma de las herramientas en chino:

   lark-mcp mcp -a cli_xxxx -s yyyyy -l zh

   Nota: La configuración del idioma en chino(-l zh) puede consumir más tokens. Si tiene problemas con el límite de tokens al integrar modelos lingüísticos de gran tamaño, considere la posibilidad de utilizar la configuración predeterminada en inglés(-l en).

8. Establecer el formato del nombre de la herramienta en mayúsculas y minúsculas:

   lark-mcp mcp -a cli_xxxx -s aaaa -c camel

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

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

9. Uso de variables de entorno en lugar de parámetros de línea de comandos:

   # Establecer variables de entorno export APP_ID=cli_xxxx export APP_SECRET=yyyyy # Iniciar el servicio (no es necesario especificar los parámetros -a y -s) lark-mcp mcp

10. Uso del archivo de configuración:

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

    lark-mcp mcp --config ./config.json

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

    { "appId": "cli_xxxx", "appSecret": "xxxx", "domain": "https://open.feishu.cn", "tools": ["im.v1.message.create", "im.v1.chat.create"], "toolNameCase": "snake", "language": "zh", "userAccessToken": "", "tokenMode": "auto", "mode": "stdio", "host": "localhost", "port": "3000" }

    Nota: Los parámetros de la línea de comandos tienen mayor prioridad que el archivo de configuración. Cuando se utilizan tanto parámetros de línea de comandos como el archivo de configuración, los parámetros de línea de comandos anulan los ajustes correspondientes 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 estándar de entrada/salida.

    lark-mcp mcp -a <id_de_la_aplicacion> -s <secreto_de_la_aplicacion> -m stdio

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

    # Escuchar en todas las interfaces de red (permitiendo el acceso remoto) lark-mcp mcp -a <su_app_id> -s <su_app_secret> -m sse -p 3000

    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/LarkSolución: Compruebe su conexión de red y asegúrese de que su APP_ID y APP_SECRET son correctos. Compruebe que puede acceder a la API de plataforma abierta de Feishu/Lark; es posible que tenga que configurar un proxy.

• Problema: Error al utilizar user_access_tokenSolución: Compruebe si el token ha caducado. user_access_token suele tener un periodo de validez de 2 horas y debe actualizarse periódicamente. Puede implementar un mecanismo de actualización automática de tokens.

• Problema: No se puede llamar a determinadas API tras iniciar el servicio MCP, con errores de permisos insuficientesSolución: Compruebe si su aplicación ha obtenido los permisos de API correspondientes. Algunas API requieren permisos adicionales de alto nivel, que pueden configurarse en la Consola del Desarrollador o en la Consola del Desarrollador de Lark. Asegúrese de que los permisos han sido aprobados.

• Problema: Las llamadas a la API relacionadas con la carga/descarga de imágenes o archivos fallanSolución: La versión actual no soporta la funcionalidad de carga/descarga de archivos e imágenes. Estas API serán soportadas en futuras versiones.

• Problema: La línea de comandos muestra caracteres confusos en el entorno WindowsSolución: Cambie la codificación de la línea de comandos a UTF-8 ejecutando chcp 65001 en la línea de comandos. Si utiliza PowerShell, es posible que tenga que cambiar la fuente del terminal o la configuración de PowerShell.

• Problema: Errores de permisos durante la instalaciónSolución: En macOS/Linux, utilice 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 ha superado el límite de tokens tras iniciar el servicio MCPSolución: Pruebe a utilizar -t para reducir el número de API habilitadas o utilice un modelo que admita tokens más grandes (como claude3.7).

• Problema: No se puede conectar o recibir mensajes en modo SSESolución: Compruebe si el puerto ya está en uso e intente cambiarlo por otro. Asegúrese de que el cliente está conectado correctamente al punto final SSE y está gestionando el flujo de eventos.

Enlaces relacionados

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

Comentarios

Los comentarios son bienvenidos para ayudar a mejorar esta herramienta. Si tiene alguna pregunta o sugerencia, por favor, plantee en el repositorio de GitHub.