Feishu/Lark OpenAPI

Conecta agentes de IA a la plataforma Feishu/Lark para automatizar tareas como procesamiento de documentos, gestión de conversaciones y programación de calendarios.

GitHubPrueba este MCPPatrocinado

Documentación

Feishu/Lark OpenAPI MCP

Inglés | 中文

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

⚠️ Aviso de versión Beta: Esta herramienta se encuentra actualmente en fase Beta. Las funciones y API pueden cambiar, por lo que te recomendamos mantenerte al día con las versiones publicadas.

Esta es la herramienta oficial de Feishu/Lark OpenAPI MCP (Model Context Protocol) diseñada para ayudar a los usuarios a conectarse rápidamente con la plataforma Feishu/Lark y permitir una colaboración eficiente entre agentes de IA y Feishu/Lark. La herramienta encapsula las interfaces de la API de la plataforma abierta de Feishu/Lark como herramientas MCP, lo que permite 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 calendario y más.

Características

Kit completo de API de Feishu/Lark: Encapsula casi todas las interfaces de la API de Feishu/Lark, incluyendo gestión de mensajes, gestión de grupos, operaciones de documentos, eventos de calendario, Bitable y otras áreas funcionales principales.
Soporte de autenticación dual:
- Soporta autenticación mediante App Access Token
- Soporta autenticación mediante User Access Token
Protocolos de comunicación flexibles:
- Soporta el modo de flujo de entrada/salida estándar (stdio), adecuado para la integración con herramientas de IA como Trae/Cursor/Claude
- Soporta el modo de eventos enviados por el servidor (SSE), que proporciona interfaces basadas en HTTP
Soporta múltiples métodos de configuración, adaptándose a diferentes escenarios de uso

Lista de herramientas

Puedes encontrar una lista completa de todas las herramientas de 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 de Feishu/Lark

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

Visita la Plataforma Abierta de Feishu o la Plataforma Abierta de Lark e inicia sesión
Haz clic en 'Consola' y crea una nueva aplicación
Obtén el App ID y el App Secret, que se utilizarán para la autenticación de la API
Agrega los permisos necesarios para tu aplicación según tu escenario de uso
Si necesitas llamar a las API como usuario, configura las URL de redirección de OAuth 2.0 y obtén tokens de acceso de usuario

Para obtener pautas detalladas sobre la creación y configuración de aplicaciones, consulta la Documentación de la Plataforma Abierta de Feishu - Creación de una aplicación o la Documentación de la Plataforma Abierta de Lark.

Instalación de Node.js

Antes de usar la herramienta lark-mcp, necesitas instalar el entorno Node.js.

Instalación de Node.js en macOS

Usando Homebrew (Recomendado):
```
brew install node
```
Usando el instalador oficial:
- Visita el sitio web de Node.js
- Descarga e instala la versión LTS
- Después de la instalación, verifica en la terminal:
```
node -v
npm -v
```

Instalación de Node.js en Windows

Usando el instalador oficial:
- Visita el sitio web de Node.js
- Descarga y ejecuta el instalador de Windows (archivo .msi)
- Sigue el asistente de instalación para completar la instalación
- Después de la instalación, verifica en el símbolo del sistema:
```
node -v
npm -v
```
Usando nvm-windows:
- Descarga nvm-windows
- Instala nvm-windows
- Usa nvm para instalar Node.js:
```
nvm install latest
nvm use <version_number>
```

Instalación

Instala la herramienta lark-mcp globalmente:

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, agrega 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, puedes agregar 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 API

Por defecto, el servicio MCP habilita las API comunes. Para habilitar otras herramientas o solo API específicas o preajustes, puedes especificarlas usando el parámetro -t (separadas por comas):

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

Colecciones de herramientas predefinidas en detalle

La siguiente tabla detalla cada herramienta de API y su inclusión en diferentes colecciones predefinidas, lo que te ayuda a elegir el preajuste adecuado para tus necesidades:

Nombre de la herramienta	Descripción de la función	preset.light	preset.default (Predeterminado)	preset.im.default	preset.base.default	preset.base.batch	preset.doc.default	preset.task.default	preset.calendar.default
im.v1.chat.create	Crear un chat de grupo		✓	✓
im.v1.chat.list	Obtener lista de chats de grupo		✓	✓
im.v1.chat.search	Buscar chats de grupo	✓
im.v1.chatMembers.get	Obtener miembros del grupo		✓	✓
im.v1.message.create	Enviar mensajes	✓	✓	✓
im.v1.message.list	Obtener lista de mensajes	✓	✓	✓
bitable.v1.app.create	Crear base		✓		✓	✓
bitable.v1.appTable.create	Crear tabla de datos de base		✓		✓	✓
bitable.v1.appTable.list	Obtener lista de tablas de datos de base		✓		✓	✓
bitable.v1.appTableField.list	Obtener lista de campos de tabla de datos de base		✓		✓	✓
bitable.v1.appTableRecord.search	Buscar registros de tabla de datos de base	✓	✓		✓	✓
bitable.v1.appTableRecord.create	Crear registros de tabla de datos de base		✓		✓
bitable.v1.appTableRecord.batchCreate	Crear registros de tabla de datos de base en lote	✓				✓
bitable.v1.appTableRecord.update	Actualizar registros de tabla de datos de base		✓		✓
bitable.v1.appTableRecord.batchUpdate	Actualizar registros de tabla de datos de base en lote					✓
docx.v1.document.rawContent	Obtener contenido del documento	✓	✓				✓
docx.builtin.import	Importar documentos	✓	✓				✓
docx.builtin.search	Buscar documentos	✓	✓				✓
drive.v1.permissionMember.create	Agregar permisos de colaborador		✓				✓
wiki.v2.space.getNode	Obtener nodo de Wiki	✓	✓				✓
wiki.v1.node.search	Buscar nodos de Wiki		✓				✓
contact.v3.user.batchGetId	Obtener IDs de usuario en lote	✓	✓
task.v2.task.create	Crear tarea							✓
task.v2.task.patch	Modificar tarea							✓
task.v2.task.addMembers	Agregar miembros a la tarea							✓
task.v2.task.addReminders	Agregar recordatorios a la tarea							✓
calendar.v4.calendarEvent.create	Crear evento de calendario								✓
calendar.v4.calendarEvent.patch	Modificar evento de calendario								✓
calendar.v4.calendarEvent.get	Obtener evento de calendario								✓
calendar.v4.freebusy.list	Consultar estado de disponibilidad								✓
calendar.v4.calendar.primary	Obtener calendario principal								✓

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

Parámetro	Corto	Descripción	Ejemplo
`--app-id`	`-a`	ID de aplicación de Feishu/Lark	`-a cli_xxxx`
`--app-secret`	`-s`	App Secret de la aplicación de Feishu/Lark	`-s xxxx`
`--domain`	`-d`	Dominio de la API de Feishu/Lark, por defecto es https://open.feishu.cn	`-d https://open.larksuite.com`
`--tools`	`-t`	Lista de herramientas de API a habilitar, separadas por comas	`-t im.v1.message.create,im.v1.chat.create`
`--tool-name-case`	`-c`	Formato de nombre de herramienta, opciones: snake, camel, dot o kebab, por defecto es snake	`-c camel`
`--language`	`-l`	Idioma de las herramientas, opciones: zh o en, por defecto es en	`-l zh`
`--user-access-token`	`-u`	Token de acceso de usuario para llamar a las API como usuario	`-u u-xxxx`
`--token-mode`		Tipo de token de API, opciones: auto, tenant_access_token o user_access_token, por defecto es auto	`--token-mode user_access_token`
`--mode`	`-m`	Modo de transporte, opciones: stdio o sse, por defecto es stdio	`-m sse`
`--host`		Host de escucha en modo SSE, por defecto es localhost	`--host 0.0.0.0`
`--port`	`-p`	Puerto de escucha en modo SSE, por defecto es 3000	`-p 3000`
`--config`		Ruta del archivo de configuración, admite formato JSON	`--config ./config.json`
`--version`	`-V`	Mostrar número de versión	`-V`
`--help`	`-h`	Mostrar información de ayuda	`-h`

Ejemplos de uso de parámetros

Uso básico (usando identidad de aplicación):
```
lark-mcp mcp -a cli_xxxx -s yyyyy
```
Usando identidad de usuario:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz
```
Nota: Los tokens de acceso de usuario se pueden obtener a través del proceso de autorización de la Plataforma Abierta de Feishu o del proceso de autorización de la Plataforma Abierta de Lark, o puedes usar la consola de depuración de API para obtenerlos. Después de usar un token de acceso de usuario, las llamadas a la API se realizarán con la identidad de ese usuario.
Configuración de un modo de token específico:
```
lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token
```
Nota: Esta opción te permite especificar explícitamente qué tipo de token usar al llamar a las API. El modo auto (por defecto) será determinado por el LLM al llamar a la API.

Especificando dominios de 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

Habilitando solo herramientas de API específicas u otras herramientas de 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 predefinidas:
- 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 predeterminado que contiene todas las herramientas predefinidas
- preset.im.default - Herramientas relacionadas con mensajería instantánea, como gestión de grupos, envío de mensajes, etc.
- preset.base.default - Herramientas relacionadas con bases, como creación de tablas, gestión de registros, etc.
- preset.base.batch - Herramientas de operaciones por lotes de bases, incluyendo funciones de creación y actualización de registros en lote
- 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 disponibilidad, etc.

Usando 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

Configurando el idioma de las herramientas a chino:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
```
Nota: Configurar el idioma a chino (-l zh) puede consumir más tokens. Si encuentras problemas de límite de tokens al integrarte con modelos de lenguaje grandes, considera usar la configuración predeterminada en inglés (-l en).
Configurando el formato de nombre de herramienta a camelCase:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
```
Nota: Al configurar el formato de nombre de herramienta, puedes cambiar cómo aparecen los nombres de las herramientas en el MCP. Por ejemplo, im.v1.message.create en diferentes formatos:
- formato snake (predeterminado): im_v1_message_create
- formato camel: imV1MessageCreate
- formato kebab: im-v1-message-create
- formato dot: im.v1.message.create

Usando 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

Usando archivo de configuración:

Además de los parámetros de línea de comandos, también puedes usar un archivo de configuración en formato JSON para establecer 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 línea de comandos tienen mayor prioridad que el archivo de configuración. Cuando se usan tanto parámetros de línea de comandos como archivo de configuración, los parámetros de línea de comandos sobrescribirán la configuración correspondiente en el archivo de configuración.
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.
```
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
```

Modo SSE: Proporciona una interfaz HTTP basada en Server-Sent Events, adecuada para escenarios donde no es posible la ejecución local.

# 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 endpoint SSE será accesible en http://<host>:<port>/sse.

Preguntas frecuentes

Problema: No se puede conectar a la API de Feishu/Lark Solución: Verifica tu conexión de red y asegúrate de que tu APP_ID y APP_SECRET sean correctos. Confirma que puedes acceder a la API de la Plataforma Abierta de Feishu/Lark; es posible que necesites configurar un proxy.
Problema: Error al usar user_access_token Solución: Verifica si el token ha expirado. user_access_token generalmente tiene un período de validez de 2 horas y debe actualizarse periódicamente. Puedes implementar un mecanismo de actualización automática de tokens.
Problema: No se pueden llamar ciertas APIs después de iniciar el servicio MCP, con errores de permisos insuficientes Solución: Verifica si tu aplicación ha obtenido los permisos de API correspondientes. Algunas APIs requieren permisos adicionales de alto nivel, que se pueden configurar en la Consola de Desarrolladores o Consola de Desarrolladores de Lark. Asegúrate de que los permisos hayan sido aprobados.
Problema: Fallan las llamadas a APIs relacionadas con carga/descarga de imágenes o archivos Solución: La versión actual no admite la funcionalidad de carga y descarga de archivos e imágenes. Estas APIs serán compatibles en versiones futuras.
Problema: La línea de comandos muestra caracteres ilegibles en el entorno Windows Solución: Cambia la codificación de la línea de comandos a UTF-8 ejecutando chcp 65001 en el símbolo del sistema. Si usas PowerShell, es posible que necesites cambiar la fuente del terminal o la configuración de PowerShell.
Problema: Errores de permisos durante la instalación Solución: En macOS/Linux, usa sudo npm install -g @larksuiteoapi/lark-mcp para la instalación, o modifica 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: Límite de tokens excedido después de iniciar el servicio MCP Solución: Intenta usar -t para reducir el número de APIs habilitadas, o usa un modelo que admita más tokens (como claude3.7).
Problema: No se puede conectar o recibir mensajes en modo SSE Solución: Verifica si el puerto ya está en uso e intenta cambiar a un puerto diferente. Asegúrate de que el cliente esté correctamente conectado al endpoint SSE y esté manejando el flujo de eventos.

Enlaces relacionados

Comentarios

Los problemas son bienvenidos para ayudar a mejorar esta herramienta. Si tienes alguna pregunta o sugerencia, por favor plantéala en el repositorio de GitHub.