NocoDB MCP Server

Un servidor MCP para NocoDB, la alternativa de código abierto a Airtable. Permite la interacción con tu instancia de NocoDB a través de la API.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Servidor MCP de NocoDB

Un servidor de Model Context Protocol (MCP) que proporciona una interfaz integral para NocoDB, la alternativa de código abierto a Airtable. Este servidor permite a los agentes de IA interactuar con bases de datos de NocoDB, lo que lo hace perfecto para almacenar y gestionar datos operativos en múltiples equipos de IA.

Características

  • Operaciones de Base de Datos: Listar y gestionar bases/proyectos de NocoDB
  • Gestión de Tablas: Crear, listar y eliminar tablas con esquemas personalizados
  • Gestión de Columnas: Añadir columnas a tablas existentes con soporte completo de tipos
  • CRUD de Registros: Operaciones completas de crear, leer, actualizar y eliminar registros
  • Consultas Avanzadas: Filtrar, ordenar, buscar y agregar datos
  • Gestión de Vistas: Crear y utilizar diferentes vistas (Cuadrícula, Galería, Formulario, etc.)
  • Operaciones Masivas: Insertar múltiples registros a la vez
  • Archivos Adjuntos: Subir archivos localmente o desde URL, adjuntar a registros

Instalación

Vía NPM (Global)

npm install -g @andrewlwn77/nocodb-mcp

Vía NPX (Sin instalación)

npx @andrewlwn77/nocodb-mcp

Configuración

Variables de Entorno

Crea un archivo .env en la raíz de tu proyecto:

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

# Optional
NOCODB_DEFAULT_BASE=your_default_base_id

Obtención de tu Token de API

  1. Inicia sesión en tu instancia de NocoDB
  2. Haz clic en el icono de tu perfil
  3. Selecciona "Tokens de API"
  4. Crea un nuevo token con los permisos adecuados

Configuración de MCP

Añade a tu archivo de configuración de 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"
      }
    }
  }
}

O si está instalado globalmente:

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

Herramientas Disponibles

Operaciones de Base de Datos

  • list_bases - Listar todas las bases de datos/proyectos disponibles
  • get_base_info - Obtener información detallada sobre una base específica

Gestión de Tablas

  • list_tables - Listar todas las tablas en una base
  • get_table_info - Obtener el esquema de la tabla e información de columnas
  • create_table - Crear una nueva tabla con esquema personalizado
  • delete_table - Eliminar una tabla
  • add_column - Añadir una nueva columna a una tabla existente
  • delete_column - Eliminar una columna de una tabla

Operaciones de Registros

  • insert_record - Insertar un solo registro
  • bulk_insert - Insertar múltiples registros a la vez
  • get_record - Recuperar un registro específico por ID
  • list_records - Listar registros con filtrado y paginación
  • update_record - Actualizar un registro existente
  • delete_record - Eliminar un registro
  • search_records - Búsqueda de texto completo en registros

Operaciones de Consulta

  • query - Filtrado avanzado con múltiples condiciones
  • aggregate - Realizar operaciones SUM, COUNT, AVG, MIN, MAX
  • group_by - Agrupar registros por una columna

Gestión de Vistas

  • list_views - Listar todas las vistas de una tabla
  • create_view - Crear una nueva vista
  • get_view_data - Obtener registros de una vista específica

Archivos Adjuntos

  • upload_attachment - Subir un archivo local al almacenamiento de NocoDB
  • upload_attachment_by_url - Subir archivos desde URL
  • attach_file_to_record - Subir y adjuntar un archivo a un registro
  • get_attachment_info - Obtener información de adjuntos de un registro

Ejemplos de Uso

Crear una Tabla

{
  "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'"
      }
    ]
  }
}

Añadir Columnas a Tablas Existentes

La herramienta add_column te permite añadir columnas dinámicamente a tablas existentes. Aquí tienes algunos ejemplos:

Tipos de Columna Básicos

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

Columna con Restricciones

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

Columna de Selección con Opciones

{
  "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"}
      ]
    }
  }
}

Columna de Moneda

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

Para más ejemplos de tipos de columna, consulta Ejemplos de Tipos de Columna.

Eliminar Columnas

La herramienta delete_column te permite eliminar columnas de tablas existentes. Puedes identificar la columna a eliminar por su ID o nombre.

Eliminar por ID de Columna

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

Eliminar por Nombre de Columna

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

Nota: La herramienta buscará columnas que coincidan con el campo column_name o title, lo que la hace flexible para diferentes convenciones de nombres.

Insertar Registros

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

Consultar con 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
  }
}

Agregar Datos

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

Ejemplos de Subida de Archivos

Subir un Archivo Local

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

Subir desde URL

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

Adjuntar Archivo a un 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"
  }
}

Obtener Información de Adjuntos

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

Tipos de Campo de NocoDB

Tipos de datos de interfaz de usuario (uidt) soportados para columnas:

Tipos Básicos

  • SingleLineText - Campo de texto corto
  • LongText - Texto multilínea
  • Number - Valores numéricos enteros
  • Decimal - Números decimales con precisión
  • Checkbox - Booleano verdadero/falso

Fecha y Hora

  • Date - Fecha sin hora
  • DateTime - Fecha con hora
  • Time - Solo hora
  • Duration - Duración de tiempo

Texto Especializado

  • Email - Direcciones de correo electrónico con validación
  • URL - Enlaces web
  • PhoneNumber - Números de teléfono (nota: usa "PhoneNumber" no "Phone")

Tipos Numéricos

  • Currency - Valores monetarios (requiere meta.currency_code)
  • Percent - Valores porcentuales
  • Rating - Calificación por estrellas

Tipos de Selección

  • SingleSelect - Desplegable con selección única (requiere meta.options)
  • MultiSelect - Selecciones múltiples (requiere meta.options)

Tipos Avanzados

  • Attachment - Subidas de archivos
  • JSON - Almacenamiento de datos JSON

Columnas Virtuales/Calculadas

  • Formula - Campos calculados
  • Rollup - Agregar registros relacionados
  • Lookup - Valores de búsqueda de registros relacionados
  • QrCode - Generar códigos QR (requiere meta.fk_qr_value_column_id)
  • Barcode - Generar códigos de barras (requiere meta.fk_barcode_value_column_id)

Relacionales

  • LinkToAnotherRecord - Relaciones entre tablas
  • Links - Relaciones muchos a muchos

Parámetros Especiales para Tipos de Columna

Algunos tipos de columna requieren parámetros adicionales en el campo meta:

  • SingleSelect/MultiSelect: Array meta.options con objetos {title, color}
  • Currency: meta.currency_code (por ejemplo, "USD", "EUR")
  • QrCode: meta.fk_qr_value_column_id - ID de la columna a codificar
  • Barcode: meta.fk_barcode_value_column_id - ID de la columna a codificar, meta.barcode_format opcional

Sintaxis de Filtros

NocoDB utiliza una sintaxis específica para el filtrado:

  • (field,operator,value) - Condición básica
  • ~and - Operador AND
  • ~or - Operador OR
  • ~not - Operador NOT

Operadores

  • eq - Igual a
  • neq - No igual a
  • gt - Mayor que
  • ge - Mayor o igual que
  • lt - Menor que
  • le - Menor o igual que
  • like - Contiene (usa % para comodines)
  • nlike - No contiene
  • null - Es nulo
  • notnull - No es nulo

Ejemplos

  • (Status,eq,active) - Estado es igual a "activo"
  • (Revenue,gt,1000)~and(Status,eq,active) - Ingresos > 1000 Y Estado = "activo"
  • (Name,like,%Corp%) - Nombre contiene "Corp"

Desarrollo

Compilar desde el Código Fuente

# 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

Ejecutar Pruebas

npm test

Manejo de Errores

El servidor proporciona mensajes de error detallados para problemas comunes:

  • Token de API inválido
  • Base/tabla no encontrada
  • Tipos de columna inválidos
  • Problemas de conectividad de red
  • Limitación de velocidad

Mejores Prácticas

  1. Usa Vistas: Crea vistas para subconjuntos de datos de acceso frecuente
  2. Operaciones por Lotes: Usa bulk_insert para múltiples registros
  3. Selección de Campos: Especifica solo los campos necesarios para reducir el tamaño de la carga útil
  4. Paginación: Usa límite/desplazamiento para conjuntos de datos grandes
  5. Caché: Considera almacenar en caché los datos de acceso frecuente en el lado del cliente

Limitaciones

  • Algunas funciones avanzadas de NocoDB pueden no estar expuestas a través de esta interfaz
  • Los límites de velocidad dependen de la configuración de tu instancia de NocoDB

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Licencia

MIT

Soporte

Para problemas y solicitudes de funciones, crea un problema en el repositorio de GitHub.