NocoDB MCP Server

Um servidor MCP para NocoDB, a alternativa open-source ao Airtable. Ele permite interação com sua instância NocoDB via API.

GitHub
5
Experimente este MCPPatrocinado

Documentação

Servidor MCP NocoDB

Um servidor Model Context Protocol (MCP) que fornece uma interface abrangente para o NocoDB - a alternativa open source ao Airtable. Este servidor permite que agentes de IA interajam com bancos de dados NocoDB, tornando-o perfeito para armazenar e gerenciar dados operacionais em múltiplas equipes de IA.

Recursos

  • Operações de Banco de Dados: Listar e gerenciar bases/projetos NocoDB
  • Gerenciamento de Tabelas: Criar, listar e excluir tabelas com esquemas personalizados
  • Gerenciamento de Colunas: Adicionar colunas a tabelas existentes com suporte completo a tipos
  • CRUD de Registros: Operações completas de criar, ler, atualizar e excluir registros
  • Consultas Avançadas: Filtrar, ordenar, pesquisar e agregar dados
  • Gerenciamento de Visualizações: Criar e usar diferentes visualizações (Grade, Galeria, Formulário, etc.)
  • Operações em Lote: Inserir múltiplos registros de uma vez
  • Anexos de Arquivos: Enviar arquivos localmente ou de URLs, anexar a registros

Instalação

Via NPM (Global)

npm install -g @andrewlwn77/nocodb-mcp

Via NPX (Sem instalação)

npx @andrewlwn77/nocodb-mcp

Configuração

Variáveis de Ambiente

Crie um arquivo .env na raiz do seu projeto:

# Required
NOCODB_BASE_URL=http://localhost:8080
NOCODB_API_TOKEN=your_api_token_here

# Optional
NOCODB_DEFAULT_BASE=your_default_base_id

Obtendo seu Token de API

  1. Faça login na sua instância NocoDB
  2. Clique no ícone do seu perfil
  3. Selecione "API Tokens"
  4. Crie um novo token com as permissões apropriadas

Configuração MCP

Adicione ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nocodb": {
      "command": "npx",
      "args": ["@andrewlwn77/nocodb-mcp"],
      "env": {
        "NOCODB_BASE_URL": "http://localhost:8080",
        "NOCODB_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Ou se instalado globalmente:

{
  "mcpServers": {
    "nocodb": {
      "command": "nocodb-mcp",
      "env": {
        "NOCODB_BASE_URL": "http://localhost:8080",
        "NOCODB_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Ferramentas Disponíveis

Operações de Banco de Dados

  • list_bases - Listar todos os bancos de dados/projetos disponíveis
  • get_base_info - Obter informações detalhadas sobre uma base específica

Gerenciamento de Tabelas

  • list_tables - Listar todas as tabelas em uma base
  • get_table_info - Obter esquema da tabela e informações das colunas
  • create_table - Criar uma nova tabela com esquema personalizado
  • delete_table - Excluir uma tabela
  • add_column - Adicionar uma nova coluna a uma tabela existente
  • delete_column - Excluir uma coluna de uma tabela

Operações de Registros

  • insert_record - Inserir um único registro
  • bulk_insert - Inserir múltiplos registros de uma vez
  • get_record - Recuperar um registro específico por ID
  • list_records - Listar registros com filtragem e paginação
  • update_record - Atualizar um registro existente
  • delete_record - Excluir um registro
  • search_records - Pesquisa de texto completo entre registros

Operações de Consulta

  • query - Filtragem avançada com múltiplas condições
  • aggregate - Executar operações SUM, COUNT, AVG, MIN, MAX
  • group_by - Agrupar registros por uma coluna

Gerenciamento de Visualizações

  • list_views - Listar todas as visualizações de uma tabela
  • create_view - Criar uma nova visualização
  • get_view_data - Obter registros de uma visualização específica

Anexos de Arquivos

  • upload_attachment - Enviar um arquivo local para o armazenamento NocoDB
  • upload_attachment_by_url - Enviar arquivos de URLs
  • attach_file_to_record - Enviar e anexar um arquivo a um registro
  • get_attachment_info - Obter informações de anexo de um registro

Exemplos de Uso

Criando uma Tabela

{
  "tool": "create_table",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "columns": [
      {
        "title": "Name",
        "uidt": "SingleLineText",
        "rqd": true
      },
      {
        "title": "Email",
        "uidt": "Email",
        "unique": true
      },
      {
        "title": "Revenue",
        "uidt": "Number",
        "dt": "decimal"
      },
      {
        "title": "Status",
        "uidt": "SingleSelect",
        "dtxp": "'active','inactive','pending'"
      }
    ]
  }
}

Adicionando Colunas a Tabelas Existentes

A ferramenta add_column permite adicionar colunas dinamicamente a tabelas existentes. Aqui estão alguns exemplos:

Tipos Básicos de Colunas

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Description",
    "uidt": "LongText"
  }
}

Coluna com Restrições

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Product Code",
    "uidt": "SingleLineText",
    "unique": true,
    "rqd": true
  }
}

Coluna de Seleção com Opções

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Priority",
    "uidt": "SingleSelect",
    "meta": {
      "options": [
        {"title": "Low", "color": "#059669"},
        {"title": "Medium", "color": "#d97706"},
        {"title": "High", "color": "#dc2626"},
        {"title": "Critical", "color": "#7c3aed"}
      ]
    }
  }
}

Coluna de Moeda

{
  "tool": "add_column",
  "arguments": {
    "table_id": "table_id_here",
    "title": "Price",
    "uidt": "Currency",
    "meta": {
      "currency_code": "USD"
    }
  }
}

Para mais exemplos de tipos de colunas, veja Exemplos de Tipos de Colunas.

Excluindo Colunas

A ferramenta delete_column permite remover colunas de tabelas existentes. Você pode identificar a coluna a ser excluída pelo ID ou nome.

Excluir por ID da Coluna

{
  "tool": "delete_column",
  "arguments": {
    "table_id": "table_id_here",
    "column_id": "column_id_to_delete"
  }
}

Excluir por Nome da Coluna

{
  "tool": "delete_column",
  "arguments": {
    "table_id": "table_id_here",
    "column_name": "ColumnToDelete"
  }
}

Nota: A ferramenta buscará colunas que correspondam ao campo column_name ou title, tornando-a flexível para diferentes convenções de nomenclatura.

Inserindo Registros

{
  "tool": "insert_record",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "data": {
      "Name": "Acme Corp",
      "Email": "contact@acme.com",
      "Revenue": 50000,
      "Status": "active"
    }
  }
}

Consultando com Filtros

{
  "tool": "query",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "where": "(Status,eq,active)~and(Revenue,gt,10000)",
    "sort": ["-Revenue", "Name"],
    "fields": ["Name", "Email", "Revenue"],
    "limit": 10
  }
}

Agregando Dados

{
  "tool": "aggregate",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "customers",
    "column_name": "Revenue",
    "function": "sum",
    "where": "(Status,eq,active)"
  }
}

Exemplos de Upload de Arquivos

Enviar um Arquivo Local

{
  "tool": "upload_attachment",
  "arguments": {
    "file_path": "/path/to/document.pdf",
    "storage_path": "documents/2024"
  }
}

Enviar de URL

{
  "tool": "upload_attachment_by_url",
  "arguments": {
    "urls": [
      "https://example.com/image1.png",
      "https://example.com/image2.jpg"
    ],
    "storage_path": "images"
  }
}

Anexar Arquivo a Registro

{
  "tool": "attach_file_to_record",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "products",
    "record_id": "42",
    "attachment_field": "ProductImages",
    "file_path": "/path/to/product-photo.jpg"
  }
}

Obter Informações de Anexo

{
  "tool": "get_attachment_info",
  "arguments": {
    "base_id": "p_abc123",
    "table_name": "products",
    "record_id": "42",
    "attachment_field": "ProductImages"
  }
}

Tipos de Campos NocoDB

Tipos de dados de interface suportados (uidt) para colunas:

Tipos Básicos

  • SingleLineText - Campo de texto curto
  • LongText - Texto multilinha
  • Number - Valores numéricos inteiros
  • Decimal - Números decimais com precisão
  • Checkbox - Booleano verdadeiro/falso

Data e Hora

  • Date - Data sem hora
  • DateTime - Data com hora
  • Time - Somente hora
  • Duration - Duração de tempo

Texto Especializado

  • Email - Endereços de e-mail com validação
  • URL - Links da web
  • PhoneNumber - Números de telefone (nota: use "PhoneNumber" não "Phone")

Tipos Numéricos

  • Currency - Valores monetários (requer meta.currency_code)
  • Percent - Valores percentuais
  • Rating - Classificação por estrelas

Tipos de Seleção

  • SingleSelect - Menu suspenso com seleção única (requer meta.options)
  • MultiSelect - Múltiplas seleções (requer meta.options)

Tipos Avançados

  • Attachment - Uploads de arquivos
  • JSON - Armazenamento de dados JSON

Colunas Virtuais/Calculadas

  • Formula - Campos calculados
  • Rollup - Agregar registros relacionados
  • Lookup - Valores de consulta de registros relacionados
  • QrCode - Gerar códigos QR (requer meta.fk_qr_value_column_id)
  • Barcode - Gerar códigos de barras (requer meta.fk_barcode_value_column_id)

Relacional

  • LinkToAnotherRecord - Relacionamentos entre tabelas
  • Links - Relacionamentos muitos-para-muitos

Parâmetros Especiais para Tipos de Colunas

Alguns tipos de colunas requerem parâmetros adicionais no campo meta:

  • SingleSelect/MultiSelect: Array meta.options com objetos {title, color}
  • Currency: meta.currency_code (ex.: "USD", "EUR")
  • QrCode: meta.fk_qr_value_column_id - ID da coluna a codificar
  • Barcode: meta.fk_barcode_value_column_id - ID da coluna a codificar, meta.barcode_format opcional

Sintaxe de Filtro

NocoDB usa uma sintaxe específica para filtragem:

  • (field,operator,value) - Condição básica
  • ~and - Operador AND
  • ~or - Operador OR
  • ~not - Operador NOT

Operadores

  • eq - Igual a
  • neq - Diferente de
  • gt - Maior que
  • ge - Maior ou igual a
  • lt - Menor que
  • le - Menor ou igual a
  • like - Contém (use % para curingas)
  • nlike - Não contém
  • null - É nulo
  • notnull - Não é nulo

Exemplos

  • (Status,eq,active) - Status igual a "ativo"
  • (Revenue,gt,1000)~and(Status,eq,active) - Receita > 1000 E Status = "ativo"
  • (Name,like,%Corp%) - Nome contém "Corp"

Desenvolvimento

Compilando a partir do Código Fonte

# Clone the repository
git clone https://github.com/your-org/nocodb-mcp.git
cd nocodb-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Executando Testes

npm test

Tratamento de Erros

O servidor fornece mensagens de erro detalhadas para problemas comuns:

  • Token de API inválido
  • Base/tabela não encontrada
  • Tipos de colunas inválidos
  • Problemas de conectividade de rede
  • Limitação de taxa

Melhores Práticas

  1. Use Visualizações: Crie visualizações para subconjuntos de dados acessados com frequência
  2. Operações em Lote: Use bulk_insert para múltiplos registros
  3. Seleção de Campos: Especifique apenas os campos necessários para reduzir o tamanho do payload
  4. Paginação: Use limite/deslocamento para grandes conjuntos de dados
  5. Cache: Considere armazenar em cache dados acessados com frequência no lado do cliente

Limitações

  • Alguns recursos avançados do NocoDB podem não estar expostos através desta interface
  • Os limites de taxa dependem da configuração da sua instância NocoDB

Contribuindo

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

Licença

MIT

Suporte

Para problemas e solicitações de recursos, por favor crie uma issue no repositório do GitHub.