Feishu/Lark OpenAPI

Conecta agentes de IA a la plataforma Feishu/Lark para automatizar el procesamiento de documentos, la gestión de conversaciones y la programación de calendarios a través de su OpenAPI.

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 MCP (Model Context Protocol) oficial de Feishu/Lark OpenAPI, 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, permitiendo que los asistentes de IA llamen directamente a estas interfaces e implementen varios escenarios de automatización como procesamiento de documentos, gestión de conversaciones, programación de calendario, entre otros.

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 con 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 modo de flujo de entrada/salida estándar (stdio), adecuado para integración con herramientas de IA como Trae/Cursor/Claude
- Soporta modo de eventos enviados por el servidor (SSE), proporcionando interfaces basadas en HTTP
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 soportadas de Feishu/Lark se puede encontrar en tools.md, donde las herramientas están categorizadas por proyecto y versión con descripciones.

Preparación

Crear 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 usará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 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 - Crear una aplicación o la Documentación de la Plataforma Abierta de Lark.

Instalar Node.js

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

Instalar 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
```

Instalar 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

De manera predeterminada, el servicio MCP habilita las API comunes. Para habilitar otras herramientas o solo API específicas o preconjuntos, puedes especificarlos usando el parámetro -t (separados 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 preestablecidas en detalle

La siguiente tabla detalla cada herramienta de API y su inclusión en diferentes colecciones preestablecidas, ayudándote a elegir el preestablecido adecuado para tus necesidades:

Nombre de herramienta	Descripción de 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 grupal		✓	✓
im.v1.chat.list	Obtener lista de chats grupales		✓	✓
im.v1.chat.search	Buscar chats grupales	✓
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 tablas de datos de base	✓	✓		✓	✓
bitable.v1.appTableRecord.create	Crear registros de tablas de datos de base		✓		✓
bitable.v1.appTableRecord.batchCreate	Crear registros en lote para tablas de datos de base	✓				✓
bitable.v1.appTableRecord.update	Actualizar registros de tablas de datos de base		✓		✓
bitable.v1.appTableRecord.batchUpdate	Actualizar registros en lote para tablas de datos de base					✓
docx.v1.document.rawContent	Obtener contenido de 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 tarea							✓
task.v2.task.addReminders	Agregar recordatorios a 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 libre/ocupado								✓
calendar.v4.calendar.primary	Obtener calendario principal								✓

Nota: En la tabla, "✓" indica que la herramienta está incluida en ese preestablecido. 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`	App ID de la 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 del nombre de la herramienta, opciones: snake, camel, dot o kebab, por defecto snake	`-c camel`
`--language`	`-l`	Idioma de las herramientas, opciones: zh o en, por defecto 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 auto	`--token-mode user_access_token`
`--mode`	`-m`	Modo de transporte, opciones: stdio o sse, por defecto stdio	`-m sse`
`--host`		Host de escucha en modo SSE, por defecto localhost	`--host 0.0.0.0`
`--port`	`-p`	Puerto de escucha en modo SSE, por defecto 3000	`-p 3000`
`--config`		Ruta del archivo de configuración, soporta 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
```
Uso de identidad de 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 la Plataforma Abierta de Feishu o el 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.
Configurar 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 (predeterminado) será determinado por el LLM al llamar a la API.

Especificar 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

Habilitar 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 soporta las siguientes colecciones de herramientas preestablecidas:
- preset.light - Conjunto de herramientas ligero con menos herramientas pero de uso frecuente, adecuado para escenarios que requieren un menor uso de tokens
- preset.default - Conjunto de herramientas predeterminado que contiene todas las herramientas preestablecidas
- 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 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.

Usar 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

Configurar 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).
Configurar el formato del nombre de la herramienta a camel case:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
```
Nota: Al configurar el formato del nombre de la 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

Usar 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

Usar 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 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 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 anularán la configuración correspondiente del archivo de configuración.
Modos de transporte:

lark-mcp soporta dos modos de transporte:
1. modo stdio (predeterminado/recomendado): Adecuado para 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 <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. Verifica que puedas 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: Comprueba si el token ha expirado. user_access_token suele tener 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: Comprueba 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 desarrollador o en la Consola de desarrollador de Lark. Asegúrate de que los permisos hayan sido aprobados.
Problema: Las llamadas a la API relacionadas con la carga/descarga de imágenes o archivos fallan Solución: La versión actual no admite la funcionalidad de carga/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 de 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 debas cambiar la fuente de la 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: Comprueba 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éalos en el repositorio de GitHub.