Airtable

Servidor MCP do Airtable

Um servidor abrangente do Model Context Protocol (MCP) que fornece acesso completo à API Web do Airtable, incluindo recursos empresariais. Este servidor permite que assistentes de IA criem, gerenciem e interajam com bases, tabelas, campos, registros, visualizações e webhooks do Airtable.

Recursos

🏗️ Gerenciamento de Bases

• Listar Bases: Obter todas as bases acessíveis em um espaço de trabalho
• Obter Esquema da Base: Recuperar a estrutura completa da base com tabelas e campos
• Excluir Base: Remover bases (somente Enterprise)

📊 Gerenciamento de Tabelas

• Listar Tabelas: Obter todas as tabelas em uma base
• Criar Tabela: Criar novas tabelas com configurações abrangentes de campos
• Atualizar Tabela: Modificar propriedades e metadados da tabela
• Excluir Tabela: Remover tabelas (com permissões adequadas)

🔧 Gerenciamento de Campos

• Listar Campos: Obter todos os campos em uma tabela
• Criar Campo: Adicionar novos campos com suporte a mais de 25 tipos de campo
• Atualizar Campo: Modificar propriedades e opções de campos existentes
• Excluir Campo: Remover campos (com considerações sobre dados)

Tipos de Campo Suportados

• Campos Básicos: singleLineText, multilineText, email, phoneNumber, richText, url
• Campos Numéricos: number, currency, percent
• Campos de Data/Hora: date, dateTime, duration
• Campos de Seleção: singleSelect, multipleSelects
• Campos Interativos: rating, checkbox
• Campos Avançados: formula, rollup, lookup, multipleRecordLinks
• Campos Especializados: attachment, barcode, button, count, autoNumber

📝 Operações com Registros

• Listar Registros: Recuperação básica de registros
• Listar Registros Avançado: Filtragem completa, ordenação, paginação e seleção de campos
• Obter Registro: Buscar detalhes de um registro individual
• Criar Registro: Adicionar registros individuais
• Atualizar Registro: Modificar registros existentes
• Excluir Registro: Remover registros
• Criar Registros em Lote: Criar vários registros de forma eficiente
• Atualizar Registros em Lote: Atualizar vários registros em uma única solicitação
• Excluir Registros em Lote: Excluir vários registros de forma eficiente
• Pesquisar Registros: Encontrar registros usando pesquisa baseada em campos

👁️ Gerenciamento de Visualizações

• Listar Visualizações: Obter todas as visualizações em uma tabela
• Obter Visualização: Recuperar a configuração da visualização
• Criar Visualização: Criar novas visualizações (grade, formulário, calendário, galeria, kanban, linha do tempo, gantt)
• Atualizar Visualização: Modificar propriedades, filtros e ordenação da visualização
• Excluir Visualização: Remover visualizações

🔔 Gerenciamento de Webhooks

• Listar Webhooks: Obter todos os webhooks de uma base
• Criar Webhook: Configurar notificações em tempo real
• Atualizar Webhook: Modificar a configuração do webhook
• Excluir Webhook: Remover assinaturas de webhook
• Obter Payloads de Webhook: Recuperar histórico de notificações do webhook

🏢 Recursos Empresariais (Planos Enterprise Scale)

• Gerenciamento de Usuários: Criar, atualizar e desativar usuários
• Gerenciamento de Espaços de Trabalho: Gerenciar acesso e permissões do espaço de trabalho
• Logs de Auditoria: Criar e recuperar logs de auditoria abrangentes
• Gerenciamento de Links de Compartilhamento: Controlar o compartilhamento de bases na organização
• Gerenciamento de Colaboradores: Adicionar/remover usuários de bases e espaços de trabalho
• Operações em Massa: Realizar operações em lote em escala empresarial

Instalação

npm install @loticdigital/airtable-mcp-server

Configuração

Defina sua chave de API do Airtable como uma variável de ambiente:

export AIRTABLE_API_KEY=your_airtable_api_key_here

Uso

Com o Claude Desktop

Adicione à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["@loticdigital/airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "your_airtable_api_key_here"
      }
    }
  }
}

Com o MCP Inspector

npx @modelcontextprotocol/inspector npx @loticdigital/airtable-mcp-server

Capacidades da API

Limites de Taxa e Boas Práticas

• Limite de Taxa: 5 solicitações por segundo por base
• Limites de Chamadas de API:
  • Gratuito: 1.000 chamadas por espaço de trabalho por mês
  • Equipe: 100.000 chamadas por espaço de trabalho por mês
  • Business/Enterprise: Chamadas ilimitadas
• Paginação: Tratamento automático de respostas paginadas
• Operações em Lote: Processamento em massa eficiente para vários registros
• Tratamento de Erros: Recuperação abrangente de erros com backoff exponencial

Recursos Avançados

• Mapeamento de ID Externo: Suporte para operações de upsert
• Validação de Dados: Validação abrangente de campos
• Resolução de Conflitos: Tratar atualizações concorrentes de forma graciosa
• Rastreamento de Alterações: Monitorar e registrar todas as modificações de dados
• Otimização de Desempenho: Cache e solicitações seletivas de campos

Recursos de Segurança

• Gerenciamento de Tokens: Tratamento seguro de PAT
• Proteção de Dados: Validação e sanitização de entrada
• Segurança Empresarial: Suporte a logs de auditoria e conformidade
• Controles de Acesso: Tratamento adequado de permissões

Exemplos de Configuração de Campos

Campos Básicos

{
  "name": "Title",
  "type": "singleLineText",
  "description": "Main title field"
}

Campos Numéricos

{
  "name": "Price",
  "type": "currency",
  "options": {
    "precision": 2,
    "symbol": "$"
  }
}

Campos de Seleção

{
  "name": "Status",
  "type": "singleSelect",
  "options": {
    "choices": [
      { "name": "Active", "color": "greenBright" },
      { "name": "Pending", "color": "yellowBright" },
      { "name": "Inactive", "color": "redBright" }
    ]
  }
}

Campos Avançados

{
  "name": "Full Name",
  "type": "formula",
  "options": {
    "formula": "CONCATENATE({First Name}, ' ', {Last Name})"
  }
}

Configuração de Webhook

{
  "notificationUrl": "https://your-server.com/webhook",
  "specification": {
    "options": {
      "filters": {
        "dataTypes": ["tableData"],
        "recordChangeScope": "tblXXXXXXXXXXXXXX"
      }
    }
  }
}

Tratamento de Erros

O servidor implementa tratamento abrangente de erros:

• 401 Não Autorizado: Token inválido ou expirado
• 403 Proibido: Permissões insuficientes
• 404 Não Encontrado: O recurso não existe
• 422 Entidade Não Processável: Configuração de campo inválida
• 429 Muitas Solicitações: Limite de taxa excedido
• 500 Erro Interno do Servidor: Problema no serviço do Airtable

Desenvolvimento

# Clone the repository
git clone https://github.com/loticdigital/airtable-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run with inspector
npm run inspector

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

Para problemas e perguntas:

• Problemas no GitHub: https://github.com/loticdigital/airtable-mcp/issues
• Documentação: API Web do Airtable

Changelog

v0.6.0 (Mais recente)

• ✨ Grande Expansão de Recursos: Adicionado suporte abrangente à API Web do Airtable
• 🔧 Mais de 25 Tipos de Campo: Suporte para todos os tipos de campo do Airtable, incluindo campos avançados
• 👁️ Gerenciamento de Visualizações: Operações CRUD completas de visualizações
• 🔔 Suporte a Webhooks: Notificações em tempo real e gerenciamento de webhooks
• 📊 Operações Avançadas de Registros: Operações em lote, filtragem avançada, paginação
• 🏢 Recursos Empresariais: Gerenciamento de usuários, logs de auditoria, gerenciamento de espaços de trabalho
• 🛡️ Segurança Aprimorada: Validação abrangente e tratamento de erros
• ⚡ Desempenho: Operações em lote otimizadas e estratégias de cache

v0.5.1

• Gerenciamento básico de tabelas e campos
• Operações CRUD simples de registros
• Suporte limitado a tipos de campo