Feishu/Lark OpenAPI

Conecta agentes de IA à plataforma Feishu/Lark para automatizar tarefas como processamento de documentos, gerenciamento de conversas e agendamento de calendário.

GitHub

Documentação

Feishu/Lark OpenAPI MCP

English | 中文

Recuperação de Documentação para Desenvolvedores MCP | Documento Oficial

⚠️ Aviso de Versão Beta: Esta ferramenta está atualmente em fase Beta. Recursos e APIs podem mudar, portanto, mantenha-se atualizado com os lançamentos de versões.

Esta é a ferramenta oficial OpenAPI MCP (Model Context Protocol) do Feishu/Lark, projetada para ajudar os usuários a se conectarem rapidamente à plataforma Feishu/Lark e permitir uma colaboração eficiente entre Agentes de IA e o Feishu/Lark. A ferramenta encapsula as interfaces de API da Plataforma Aberta Feishu/Lark como ferramentas MCP, permitindo que assistentes de IA chamem diretamente essas interfaces e implementem vários cenários de automação, como processamento de documentos, gerenciamento de conversas, agendamento de calendário e muito mais.

Recursos

Kit Completo de API Feishu/Lark: Encapsula quase todas as interfaces de API do Feishu/Lark, incluindo gerenciamento de mensagens, gerenciamento de grupos, operações de documentos, eventos de calendário, Bitable e outras áreas funcionais principais.
Suporte a Autenticação Dupla:
- Suporta autenticação com App Access Token
- Suporta autenticação com User Access Token
Protocolos de Comunicação Flexíveis:
- Suporta modo de fluxo de entrada/saída padrão (stdio), adequado para integração com ferramentas de IA como Trae/Cursor/Claude
- Suporta modo Server-Sent Events (SSE), fornecendo interfaces baseadas em HTTP
Suporta múltiplos métodos de configuração, adaptando-se a diferentes cenários de uso

Lista de Ferramentas

Uma lista completa de todas as ferramentas Feishu/Lark suportadas pode ser encontrada em tools.md, onde as ferramentas são categorizadas por projeto e versão com descrições.

Preparação

Criando um Aplicativo Feishu/Lark

Antes de usar a ferramenta lark-mcp, você precisa criar um aplicativo Feishu/Lark:

Visite a Plataforma Aberta Feishu ou a Plataforma Aberta Lark e faça login
Clique em "Console" e crie um novo aplicativo
Obtenha o App ID e o App Secret, que serão usados para autenticação de API
Adicione as permissões necessárias para o seu aplicativo com base no seu cenário de uso
Se você precisar chamar APIs como usuário, configure URLs de redirecionamento OAuth 2.0 e obtenha tokens de acesso de usuário

Para diretrizes detalhadas de criação e configuração de aplicativos, consulte a Documentação da Plataforma Aberta Feishu - Criando um Aplicativo ou a Documentação da Plataforma Aberta Lark.

Instalando o Node.js

Antes de usar a ferramenta lark-mcp, você precisa instalar o ambiente Node.js.

Instalando o Node.js no macOS

Usando Homebrew (Recomendado):
```
brew install node
```
Usando o Instalador Oficial:
- Visite o site do Node.js
- Baixe e instale a versão LTS
- Após a instalação, verifique no terminal:
```
node -v
npm -v
```

Instalando o Node.js no Windows

Usando o Instalador Oficial:
- Visite o site do Node.js
- Baixe e execute o instalador do Windows (arquivo .msi)
- Siga o assistente de instalação para concluir a instalação
- Após a instalação, verifique no prompt de comando:
```
node -v
npm -v
```
Usando nvm-windows:
- Baixe o nvm-windows
- Instale o nvm-windows
- Use o nvm para instalar o Node.js:
```
nvm install latest
nvm use <version_number>
```

Instalação

Instale a ferramenta lark-mcp globalmente:

npm install -g @larksuiteoapi/lark-mcp

Guia de Uso

Usando com Trae/Cursor/Claude

Para integrar a funcionalidade Feishu/Lark em ferramentas de IA como Trae, Cursor ou Claude, adicione o seguinte ao seu arquivo de configuração:

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

Para acessar APIs com identidade de usuário, você pode adicionar um token de acesso de usuário:

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

Configuração Personalizada de API

Por padrão, o serviço MCP habilita APIs comuns. Para habilitar outras ferramentas ou apenas APIs específicas ou predefinições, você pode especificá-las usando o parâmetro -t (separadas por vírgulas):

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

Coleções de Ferramentas Predefinidas em Detalhe

A tabela a seguir detalha cada ferramenta de API e sua inclusão em diferentes coleções predefinidas, ajudando você a escolher a predefinição apropriada para suas necessidades:

Nome da Ferramenta	Descrição da Função	preset.light	preset.default (Padrão)	preset.im.default	preset.base.default	preset.base.batch	preset.doc.default	preset.task.default	preset.calendar.default
im.v1.chat.create	Criar um chat em grupo		✓	✓
im.v1.chat.list	Obter lista de chats em grupo		✓	✓
im.v1.chat.search	Pesquisar chats em grupo	✓
im.v1.chatMembers.get	Obter membros do grupo		✓	✓
im.v1.message.create	Enviar mensagens	✓	✓	✓
im.v1.message.list	Obter lista de mensagens	✓	✓	✓
bitable.v1.app.create	Criar base		✓		✓	✓
bitable.v1.appTable.create	Criar tabela de dados da base		✓		✓	✓
bitable.v1.appTable.list	Obter lista de tabelas de dados da base		✓		✓	✓
bitable.v1.appTableField.list	Obter lista de campos da tabela de dados da base		✓		✓	✓
bitable.v1.appTableRecord.search	Pesquisar registros da tabela de dados da base	✓	✓		✓	✓
bitable.v1.appTableRecord.create	Criar registros da tabela de dados da base		✓		✓
bitable.v1.appTableRecord.batchCreate	Criar registros da tabela de dados da base em lote	✓				✓
bitable.v1.appTableRecord.update	Atualizar registros da tabela de dados da base		✓		✓
bitable.v1.appTableRecord.batchUpdate	Atualizar registros da tabela de dados da base em lote					✓
docx.v1.document.rawContent	Obter conteúdo do documento	✓	✓				✓
docx.builtin.import	Importar documentos	✓	✓				✓
docx.builtin.search	Pesquisar documentos	✓	✓				✓
drive.v1.permissionMember.create	Adicionar permissões de colaborador		✓				✓
wiki.v2.space.getNode	Obter nó Wiki	✓	✓				✓
wiki.v1.node.search	Pesquisar nós Wiki		✓				✓
contact.v3.user.batchGetId	Obter IDs de usuários em lote	✓	✓
task.v2.task.create	Criar tarefa							✓
task.v2.task.patch	Modificar tarefa							✓
task.v2.task.addMembers	Adicionar membros à tarefa							✓
task.v2.task.addReminders	Adicionar lembretes à tarefa							✓
calendar.v4.calendarEvent.create	Criar evento de calendário								✓
calendar.v4.calendarEvent.patch	Modificar evento de calendário								✓
calendar.v4.calendarEvent.get	Obter evento de calendário								✓
calendar.v4.freebusy.list	Consultar status de disponibilidade								✓
calendar.v4.calendar.primary	Obter calendário principal								✓

Nota: Na tabela, "✓" indica que a ferramenta está incluída naquela predefinição. Usar -t preset.xxx habilitará apenas as ferramentas marcadas com "✓" na coluna correspondente.

Configuração Avançada

Parâmetros de Linha de Comando

A ferramenta lark-mcp mcp fornece vários parâmetros de linha de comando para configuração flexível do serviço MCP:

Parâmetro	Curto	Descrição	Exemplo
`--app-id`	`-a`	App ID do aplicativo Feishu/Lark	`-a cli_xxxx`
`--app-secret`	`-s`	App Secret do aplicativo Feishu/Lark	`-s xxxx`
`--domain`	`-d`	Domínio da API Feishu/Lark, padrão é https://open.feishu.cn	`-d https://open.larksuite.com`
`--tools`	`-t`	Lista de ferramentas de API a habilitar, separadas por vírgulas	`-t im.v1.message.create,im.v1.chat.create`
`--tool-name-case`	`-c`	Formato do nome da ferramenta, opções são snake, camel, dot ou kebab, padrão é snake	`-c camel`
`--language`	`-l`	Idioma das ferramentas, opções são zh ou en, padrão é en	`-l zh`
`--user-access-token`	`-u`	Token de acesso de usuário para chamar APIs como usuário	`-u u-xxxx`
`--token-mode`		Tipo de token de API, opções são auto, tenant_access_token ou user_access_token, padrão é auto	`--token-mode user_access_token`
`--mode`	`-m`	Modo de transporte, opções são stdio ou sse, padrão é stdio	`-m sse`
`--host`		Host de escuta no modo SSE, padrão é localhost	`--host 0.0.0.0`
`--port`	`-p`	Porta de escuta no modo SSE, padrão é 3000	`-p 3000`
`--config`		Caminho do arquivo de configuração, suporta formato JSON	`--config ./config.json`
`--version`	`-V`	Exibir número da versão	`-V`
`--help`	`-h`	Exibir informações de ajuda	`-h`

Exemplos de Uso de Parâmetros

Uso Básico (usando identidade de aplicativo):
```
lark-mcp mcp -a cli_xxxx -s yyyyy
```
Usando Identidade de Usuário:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -u u-zzzz
```
Nota: Tokens de acesso de usuário podem ser obtidos através do processo de autorização da Plataforma Aberta Feishu ou do processo de autorização da Plataforma Aberta Lark, ou você pode usar o console de depuração de API para obtê-los. Após usar um token de acesso de usuário, as chamadas de API serão feitas com a identidade desse usuário.
Definindo Modo de Token Específico:
```
lark-mcp mcp -a cli_xxxx -s yyyyy --token-mode user_access_token
```
Nota: Esta opção permite que você especifique explicitamente qual tipo de token usar ao chamar APIs. O modo auto (padrão) será determinado pelo LLM ao chamar a API.

Especificando Domínios Lark ou 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 Apenas Ferramentas de API Específicas ou Outras Ferramentas de API:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -t im.v1.chat.create,im.v1.message.create
```
Nota: O parâmetro -t suporta as seguintes coleções de ferramentas predefinidas:
- preset.light - Conjunto de ferramentas leve com menos ferramentas, porém comumente usadas, adequado para cenários que exigem uso reduzido de tokens
- preset.default - Conjunto de ferramentas padrão contendo todas as ferramentas predefinidas
- preset.im.default - Ferramentas relacionadas a mensagens instantâneas, como gerenciamento de grupos, envio de mensagens, etc.
- preset.base.default - Ferramentas relacionadas a bases, como criação de tabelas, gerenciamento de registros, etc.
- preset.base.batch - Ferramentas de operação em lote de bases, incluindo funções de criação e atualização de registros em lote
- preset.doc.default - Ferramentas relacionadas a documentos, como leitura de conteúdo de documentos, gerenciamento de permissões, etc.
- preset.task.default - Ferramentas relacionadas a gerenciamento de tarefas, como criação de tarefas, gerenciamento de membros, etc.
- preset.calendar.default - Ferramentas de gerenciamento de eventos de calendário, como criação de eventos de calendário, consulta de status de disponibilidade, etc.

Usando Modo SSE com Porta e Host Específicos:

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

Definindo o Idioma das Ferramentas para Chinês:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -l zh
```
Nota: Definir o idioma para chinês (-l zh) pode consumir mais tokens. Se você encontrar problemas de limite de tokens ao integrar com modelos de linguagem grandes, considere usar a configuração padrão em inglês (-l en).
Definindo o Formato do Nome da Ferramenta para Camel Case:
```
lark-mcp mcp -a cli_xxxx -s yyyyy -c camel
```
Nota: Ao definir o formato do nome da ferramenta, você pode alterar como os nomes das ferramentas aparecem no MCP. Por exemplo, im.v1.message.create em diferentes formatos:
- formato snake (padrão): im_v1_message_create
- formato camel: imV1MessageCreate
- formato kebab: im-v1-message-create
- formato dot: im.v1.message.create

Usando Variáveis de Ambiente em Vez de Parâmetros de Linha de Comando:

# 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 Arquivo de Configuração:

Além dos parâmetros de linha de comando, você também pode usar um arquivo de configuração em formato JSON para definir parâmetros:
```
lark-mcp mcp --config ./config.json
```
Exemplo de arquivo de configuração (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: Parâmetros de linha de comando têm prioridade maior que o arquivo de configuração. Ao usar tanto parâmetros de linha de comando quanto arquivo de configuração, os parâmetros de linha de comando substituirão as configurações correspondentes no arquivo de configuração.
Modos de Transporte:

O lark-mcp suporta dois modos de transporte:
1. Modo stdio (Padrão/Recomendado): Adequado para integração com ferramentas de IA como Trae/Cursor ou Claude, comunicando-se através de fluxos de entrada/saída padrão.
```
lark-mcp mcp -a <your_app_id> -s <your_app_secret> -m stdio
```

Modo SSE: Fornece uma interface HTTP baseada em Server-Sent Events, adequada para cenários onde a execução local não é possível.

# 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

Após a inicialização, o endpoint SSE estará acessível em http://<host>:<port>/sse.

FAQ

Problema: Não é possível conectar à API do Feishu/Lark Solução: Verifique sua conexão de rede e garanta que seu APP_ID e APP_SECRET estão corretos. Confirme que você consegue acessar a API da Plataforma Aberta do Feishu/Lark; talvez seja necessário configurar um proxy.
Problema: Erro ao usar user_access_token Solução: Verifique se o token expirou. O user_access_token geralmente tem validade de 2 horas e precisa ser atualizado periodicamente. Você pode implementar um mecanismo automático de renovação de token.
Problema: Não é possível chamar certas APIs após iniciar o serviço MCP, com erros de permissões insuficientes Solução: Verifique se seu aplicativo obteve as permissões de API correspondentes. Algumas APIs exigem permissões adicionais de alto nível, que podem ser configuradas no Console do Desenvolvedor ou no Console do Desenvolvedor Lark. Garanta que as permissões foram aprovadas.
Problema: Chamadas de API relacionadas a upload/download de imagens ou arquivos falham Solução: A versão atual não suporta funcionalidades de upload e download de arquivos e imagens. Essas APIs serão suportadas em versões futuras.
Problema: A linha de comando exibe caracteres ilegíveis no ambiente Windows Solução: Altere a codificação da linha de comando para UTF-8 executando chcp 65001 no prompt de comando. Se estiver usando PowerShell, talvez seja necessário alterar a fonte do terminal ou a configuração do PowerShell.
Problema: Erros de permissão durante a instalação Solução: No macOS/Linux, use sudo npm install -g @larksuiteoapi/lark-mcp para instalação, ou modifique as permissões do caminho de instalação global do npm. Usuários do Windows podem tentar executar o prompt de comando como administrador.
Problema: Limite de tokens excedido após iniciar o serviço MCP Solução: Tente usar -t para reduzir o número de APIs habilitadas, ou use um modelo que suporte mais tokens (como claude3.7).
Problema: Não é possível conectar ou receber mensagens no modo SSE Solução: Verifique se a porta já está em uso e tente mudar para uma porta diferente. Garanta que o cliente esteja corretamente conectado ao endpoint SSE e esteja processando o fluxo de eventos.

Links Relacionados

Feedback

Issues são bem-vindos para ajudar a melhorar esta ferramenta. Se você tiver alguma dúvida ou sugestão, por favor, levante-as no repositório do GitHub.