ComposioHQ/Excel-Automation

Automação de Excel

Automatize operações de planilhas, incluindo criação de pastas de trabalho, escrita de dados, formatação de células, atualização/inserção de linhas e gerenciamento de abas. Funciona com Microsoft Excel (OneDrive) e Google Sheets.

Documentação do toolkit: composio.dev/toolkits/excel

---

Configuração

Esta skill requer o servidor Rube MCP conectado em https://rube.app/mcp.

Antes de executar qualquer ferramenta, garanta que exista uma conexão ativa para o toolkit excel (e opcionalmente googlesheets). Se nenhuma conexão estiver ativa, inicie uma via RUBE_MANAGE_CONNECTIONS.

---

Fluxos Principais

1. Criar uma Nova Pasta de Trabalho do Excel

Use EXCEL_CREATE_WORKBOOK para gerar um novo arquivo .xlsx e enviá-lo para o OneDrive.

Ferramenta: EXCEL_CREATE_WORKBOOK

Passos:

1. Chame EXCEL_CREATE_WORKBOOK com os nomes das abas e dados
2. A ferramenta cria um arquivo .xlsx e o envia para o OneDrive
3. Use o caminho/URL do arquivo retornado para operações subsequentes

---

2. Escrever Dados em uma Planilha

Use GOOGLESHEETS_BATCH_UPDATE para escrever valores em um intervalo específico ou anexar linhas.

Ferramenta: GOOGLESHEETS_BATCH_UPDATE

Parâmetros Principais:

• spreadsheet_id (obrigatório) — O ID da planilha extraído da URL (sequência alfanumérica de 44 caracteres)
• sheet_name (obrigatório) — Nome da aba, ex.: "Sheet1", "Dados de Vendas"
• values (obrigatório) — Matriz 2D de valores de células, ex.: [["Nome","Valor"],["Alice",100]]
• first_cell_location — Célula inicial na notação A1 (ex.: "A1", "D3"). Omita para anexar linhas
• valueInputOption — "USER_ENTERED" (padrão, interpreta fórmulas) ou "RAW" (armazena como está)

Exemplo:

Ferramenta: GOOGLESHEETS_BATCH_UPDATE
Argumentos:
  spreadsheet_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
  sheet_name: "Sheet1"
  values: [["Item","Custo","Estocado"],["Roda",20.50,true],["Parafuso",0.50,true]]
  first_cell_location: "A1"

---

3. Atualizar/Inserir Linhas por Coluna Chave

Use GOOGLESHEETS_UPSERT_ROWS para atualizar linhas existentes combinando uma coluna chave, ou anexar novas linhas se nenhuma correspondência for encontrada. Ideal para sincronizações de CRM, atualizações de inventário e deduplicação.

Ferramenta: GOOGLESHEETS_UPSERT_ROWS

Parâmetros Principais:

• spreadsheetId (obrigatório) — O ID da planilha
• sheetName (obrigatório) — Nome da aba
• rows (obrigatório) — Matriz 2D de linhas de dados (mínimo 1 linha). Se headers for omitido, a primeira linha é tratada como cabeçalho
• headers — Nomes das colunas para os dados, ex.: ["Email","Telefone","Status"]
• keyColumn — Cabeçalho da coluna para correspondência, ex.: "Email", "SKU", "ID do Lead"
• strictMode — true (padrão) gera erro em colunas incompatíveis; false trunca silenciosamente

Exemplo:

Ferramenta: GOOGLESHEETS_UPSERT_ROWS
Argumentos:
  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
  sheetName: "Contatos"
  keyColumn: "Email"
  headers: ["Email","Telefone","Status"]
  rows: [["[email protected]","555-0101","Ativo"],["[email protected]","555-0102","Pendente"]]

---

4. Formatar Células

Use GOOGLESHEETS_FORMAT_CELL para aplicar negrito, itálico, tamanho da fonte e cores de fundo a intervalos.

Ferramenta: GOOGLESHEETS_FORMAT_CELL

Parâmetros Principais:

• spreadsheet_id (obrigatório) — O ID da planilha
• range — Intervalo de células na notação A1, ex.: "A1:D1", "B2:B10" (recomendado em vez de baseado em índice)
• sheet_name — Nome da aba, ex.: "Sheet1"
• bold — true/false
• italic — true/false
• fontSize — Tamanho da fonte em pontos, ex.: 12
• red, green, blue — Componentes da cor de fundo (escala float 0.0–1.0, NÃO 0–255)

Exemplo (linha de cabeçalho em negrito com fundo azul):

Ferramenta: GOOGLESHEETS_FORMAT_CELL
Argumentos:
  spreadsheet_id: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
  range: "A1:D1"
  sheet_name: "Sheet1"
  bold: true
  fontSize: 12
  red: 0.2
  green: 0.4
  blue: 0.9

---

5. Adicionar Novas Abas de Planilha

Use GOOGLESHEETS_ADD_SHEET para criar novas abas dentro de uma planilha existente.

Ferramenta: GOOGLESHEETS_ADD_SHEET

Parâmetros Principais:

• spreadsheetId (obrigatório) — O ID da planilha
• title — Nome da nova aba, ex.: "Relatório Q4"
• forceUnique — true (padrão) anexa sufixo automaticamente se o nome já existir

Exemplo:

Ferramenta: GOOGLESHEETS_ADD_SHEET
Argumentos:
  spreadsheetId: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
  title: "Relatório Q4"
  forceUnique: true

---

6. Ler Dados e Verificar Conteúdo

Use GOOGLESHEETS_BATCH_GET para recuperar dados de intervalos de células especificados para validação ou processamento adicional.

Ferramenta: GOOGLESHEETS_BATCH_GET

Passos:

1. Chame GOOGLESHEETS_BATCH_GET com o ID da planilha e os intervalos alvo
2. Valide cabeçalhos e alinhamento dos dados
3. Use os resultados para informar operações subsequentes de escrita ou atualização

Ferramentas de Suporte:

• GOOGLESHEETS_GET_SHEET_NAMES — Lista todos os nomes de abas em uma planilha
• GOOGLESHEETS_GET_SPREADSHEET_INFO — Obtém metadados (IDs de abas, propriedades)
• GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE — Verifica se uma aba específica existe

---

Plano de Execução Recomendado

1. Crie ou localize a planilha usando GOOGLESHEETS_CREATE_GOOGLE_SHEET1 ou reutilizando um spreadsheetId existente
2. Confirme a aba de destino usando GOOGLESHEETS_GET_SHEET_NAMES ou GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE; crie-a com GOOGLESHEETS_ADD_SHEET se estiver ausente
3. Leia cabeçalhos existentes (opcional) usando GOOGLESHEETS_BATCH_GET para alinhar colunas
4. Escreva ou atualize/insira dados usando GOOGLESHEETS_BATCH_UPDATE ou GOOGLESHEETS_UPSERT_ROWS
5. Aplique formatação (opcional) usando GOOGLESHEETS_FORMAT_CELL
6. Verifique resultados (opcional) usando GOOGLESHEETS_BATCH_GET
7. Fallback: Se a criação do Google Sheets for bloqueada (HTTP 403), use EXCEL_CREATE_WORKBOOK para saída local .xlsx

---

Armadilhas Conhecidas

Armadilha	Detalhe
HTTP 403 na criação de planilha	GOOGLESHEETS_CREATE_GOOGLE_SHEET1 falha quando o escopo de criação do Drive está ausente. Reutilize um spreadsheetId existente ou recorra a EXCEL_CREATE_WORKBOOK.
Limite de células e limitação de taxa	O Google Sheets tem um limite de ~5.000.000 células por planilha. Frequência excessiva de escrita gera HTTP 429. Agrupe alterações e divida grandes escritas (~500 linhas/chamada).
Intervalo de formatação fora por um	GOOGLESHEETS_FORMAT_CELL usa intervalos baseados em 0, com endIndex exclusivo ao usar modo índice. A cor de fundo usa RGB float 0–1, NÃO RGB inteiro 0–255.
Unicidade do título da aba	Títulos de abas não são garantidos como únicos nas respostas da API. Prefira operar pelo sheetId numérico e verifique a aba resolvida antes de escrever.
Forma do payload upsert	GOOGLESHEETS_UPSERT_ROWS requer cabeçalhos + matriz 2D de linhas. Enviar lista-de-dicionários ou rows vazio causa erros de validação. Garanta pelo menos 1 linha de dados.

---

Referência Rápida

Slug da Ferramenta	Descrição
EXCEL_CREATE_WORKBOOK	Criar uma nova pasta de trabalho .xlsx e enviar para o OneDrive
GOOGLESHEETS_BATCH_UPDATE	Escrever valores em um intervalo ou anexar novas linhas
GOOGLESHEETS_UPSERT_ROWS	Atualizar linhas existentes por chave ou anexar novas
GOOGLESHEETS_FORMAT_CELL	Aplicar formatação de texto/fundo a intervalos de células
GOOGLESHEETS_ADD_SHEET	Adicionar uma nova aba de planilha a uma planilha existente
GOOGLESHEETS_CREATE_GOOGLE_SHEET1	Criar uma nova planilha Google no Drive
GOOGLESHEETS_GET_SHEET_NAMES	Listar todos os nomes de abas em uma planilha
GOOGLESHEETS_GET_SPREADSHEET_INFO	Recuperar metadados da planilha
GOOGLESHEETS_FIND_WORKSHEET_BY_TITLE	Verificar se uma aba existe pelo título
GOOGLESHEETS_BATCH_GET	Ler dados de intervalos de células especificados

---

Desenvolvido por Composio