Servidor Airtable MCP

🤖 Agente IA Revolucionario v3.2.7 - Servidor Airtable MCP avanzado impulsado por IA con integración FastMCP moderna, transporte HTTP/SSE para streaming en tiempo real, despliegue optimizado en Railway, y arquitectura multi-lenguaje con compatibilidad completa.

📑 Tabla de Contenidos

• Últimas Versiones
• Suite de Inteligencia IA
• Características Principales
• Requisitos Previos
• Inicio Rápido
• Ejemplos de Uso
• Herramientas Disponibles
• Configuración Avanzada
• Pruebas
• Solución de Problemas
• Documentación

Últimas Versiones

🚀 v3.2.7 - Integración Completa OAuth + FastMCP

Mejoras Principales con compatibilidad completa con versiones anteriores:

• ⚡ FastMCP Moderno - Integración completa con FastMCP para transporte HTTP/SSE
• 🌐 Transporte HTTP con SSE - Streaming en tiempo real para aplicaciones de producción
• 🚂 Despliegue Railway Optimizado - Configuración Docker builder con manejo dinámico de puertos
• 🏗️ Arquitectura Multi-Lenguaje - Soporte completo para Python, Node.js y TypeScript
• 🔧 Configuración Automática - Auto-detección de STDIO/HTTP según entorno
• 📦 Sin Compilación en GitHub Actions - Ejecución directa sin pasos de build
• 🐳 Docker Producción - Imágenes optimizadas para Railway y entornos de producción
• 🔄 Comandos Diferenciados - npm run dev para desarrollo, npm start para producción

🚀 v3.2.5 - ID de Base Opcional y Soporte Mejorado para Múltiples Bases

Mejoras Principales con compatibilidad completa con versiones anteriores:

• �� ID de Base Opcional - Comience sin especificar una base, descúbralas usando la herramienta list_bases
• 🔍 Descubrimiento de Base Mejorado - Nueva herramienta list_bases completamente implementada en TypeScript
• 🎯 Selección de Base Dinámica - Especifique IDs de base por llamada de herramienta, sin requisito de inicio
• ✅ Problema #9 Resuelto - Resolvió la limitación "base requerida al inicio"
• 🔧 Gobernanza Mejorada - Manejo inteligente de lista blanca de base para flujos de trabajo multi-base
• 📦 Soporte Completo de STDIO - Compatibilidad confirmada con Claude Desktop/Code

📋 v3.2.4 - Corrección de Seguridad XSS y Protección Completa

Mejoras Principales con compatibilidad completa con versiones anteriores:

• 🔧 Arquitectura TypeScript Reparada - Se resolvieron problemas de compilación, separación adecuada de tipos y código en tiempo de ejecución
• 📁 Organización de Clase Mundial - Proyecto reestructurado con src/typescript, src/javascript, src/python
• 🔒 Corrección de Seguridad Completa - Vulnerabilidad de inyección de comandos completamente resuelta con validación integral
• 🔷 Implementación de TypeScript - Servidor completamente seguro de tipos con validación estricta
• 📘 Definiciones de Tipo Integrales - Todos los 33 herramientas y 10 mensajes de IA completamente tipificados
• 🛡️ Seguridad en Tiempo de Compilación - Detecte errores antes de la ejecución con verificación de tipos avanzada
• 🎯 Experiencia del Desarrollador - Soporte para IntelliSense, autocompletado y refactorización
• 🔄 Distribución Dual - Use con JavaScript o TypeScript, su elección

🤖 Suite de Inteligencia IA

Inteligencia Completa Impulsada por IA con capacidades empresariales:

• 🤖 10 Plantillas de Mensajes IA - Análisis avanzado, predicciones y automatización
• 🔮 Análisis Predictivo - Pronóstico y análisis de tendencias con intervalos de confianza
• 🗣️ Procesamiento de Lenguaje Natural - Consulte sus datos usando lenguaje humano
• �� Inteligencia Empresarial - Información automatizada y recomendaciones
• 🏗️ Diseño de Esquema Inteligente - Arquitectura de base de datos optimizada para IA
• ⚡ Automatización de Flujos de Trabajo - Optimización de procesos inteligente
• 🔍 Auditoría de Calidad de Datos - Evaluación de calidad integral y correcciones
• 📈 Análisis Estadístico - Análisis avanzado con pruebas de significancia

✨ Características

🔍 Datos y Consultas

• Consultas de Lenguaje Natural - Haga preguntas sobre sus datos en inglés simple
• Operaciones CRUD Completas - Crear, leer, actualizar y eliminar registros
• Descubrimiento de Bases - Explore todas las bases accesibles y sus esquemas

🏗️ Gestión de Estructura

• Gestión Avanzada de Esquemas - Crear tablas, campos y gestionar la estructura de base
• Gestión de Campos - Agregue, modifique y elimine campos programáticamente
• Operaciones por Lotes - Crear, actualizar, eliminar hasta 10 registros a la vez

🌐 Integración y Webhooks

• Gestión de Webhooks - Crear y gestionar webhooks para notificaciones en tiempo real
• Gestión de Adjuntos - Cargue archivos a través de URLs a campos de adjuntos
• Herramientas de Colaboración - Gestione colaboradores de base y vistas compartidas

🔐 Seguridad y Rendimiento

• Autenticación Segura - Utiliza variables de entorno para credenciales
• Seguridad Empresarial - OAuth2, limitación de velocidad, validación integral
• Rápido y Confiable - Construido con Node.js para rendimiento óptimo

🎯 Herramientas y APIs

• 33 Herramientas Potentes - Cobertura completa de API Airtable con operaciones por lotes
• Integración IA - Mensajes y muestreo para operaciones de datos inteligentes
• Configuración Fácil - Múltiples opciones de instalación disponibles

📋 Requisitos Previos

• Node.js 14+ instalado en su sistema
• Una cuenta Airtable con Token de Acceso Personal
• Su ID de Base Airtable (opcional en v3.2.5+)

🚀 Inicio Rápido

Paso 1: Obtenga sus Credenciales de Airtable

#### 1. Token de Acceso Personal Visite Cuenta de Airtable → Cree un token con los siguientes ámbitos:

• data.records:read - Leer registros de tablas
• data.records:write - Crear, actualizar, eliminar registros
• schema.bases:read - Ver esquemas de tablas
• schema.bases:write - Nuevo en v1.5.0 - Crear/modificar tablas y campos
• webhook:manage - (Opcional) Para características de webhook

#### 2. ID de Base Abra su base Airtable y copie el ID de la URL:

https://airtable.com/[BASE_ID]/...

Paso 2: Instalación

Elija uno de estos métodos de instalación:

#### 🚀 FastMCP (Recomendado - v3.2.x+)

Nueva versión con FastMCP moderno:

# Instalar FastMCP CLI
pip install fastmcp

# Ejecutar el servidor
fastmcp run

# Para desarrollo con auto-reload
npm run dev

# Para producción (Railway)
npm start

Características de FastMCP:

• ✅ Transporte HTTP con SSE para streaming en tiempo real
• ✅ Configuración automática de STDIO/HTTP según entorno
• ✅ Compatible con Railway, Docker y desarrollo local
• ✅ No requiere compilación en GitHub Actions

#### 🔷 TypeScript (Desarrollo Avanzado)

# Instalar con soporte de TypeScript
npm install -g @rashidazarang/airtable-mcp

# Para desarrollo con tipos
npm install --save-dev typescript @types/node

#### 📦 JavaScript (Legacy)

Opción A: Instalar a través de NPM

npm install -g @rashidazarang/airtable-mcp

Opción B: Clonar desde GitHub

git clone https://github.com/rashidazarang/airtable-mcp.git
cd airtable-mcp
npm install

Paso 3: Configurar Variables de Entorno

Cree un archivo .env en su directorio de proyecto:

AIRTABLE_TOKEN=su_token_de_acceso_personal_aqui
AIRTABLE_BASE_ID=su_id_de_base_aqui  # OPCIONAL - puede ser descubierto usando la herramienta list_bases

Nuevo en v3.2.5: ¡El AIRTABLE_BASE_ID ahora es opcional! Puede:

• Comenzar sin un ID de base y usar la herramienta list_bases para descubrir sus bases accesibles
• Especificar IDs de base dinámicamente en cada llamada de herramienta
• Establecer una base predeterminada por conveniencia (recomendado)

Nota de Seguridad: ¡Nunca confirme archivos .env al control de versiones!

Paso 4: Configure su Cliente MCP

#### 🚀 FastMCP (Recomendado - v3.2.x+)

Configuración moderna con FastMCP:

{
  "mcpServers": {
    "airtable-fastmcp": {
      "command": "fastmcp",
      "args": ["run"],
      "env": {
        "AIRTABLE_TOKEN": "SU_TOKEN_AIRTABLE",
        "AIRTABLE_BASE_ID": "SU_ID_DE_BASE"
      }
    }
  }
}

Ventajas de FastMCP:

• ✅ Auto-detección de transporte (STDIO para desarrollo, HTTP para producción)
• ✅ Soporte SSE para streaming en tiempo real
• ✅ Configuración simplificada
• ✅ Compatible con Railway y Docker

#### 🔷 TypeScript (Experiencia Mejorada del Desarrollador)

{
  "mcpServers": {
    "airtable-typescript": {
      "command": "npx",
      "args": ["@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "SU_TOKEN_AIRTABLE",
        "AIRTABLE_BASE_ID": "SU_ID_DE_BASE",
        "NODE_ENV": "production",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

#### 📦 JavaScript (Legacy)

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["@rashidazarang/airtable-mcp"],
      "env": {
        "AIRTABLE_TOKEN": "SU_TOKEN_AIRTABLE",
        "AIRTABLE_BASE_ID": "SU_ID_DE_BASE"
      }
    }
  }
}

#### Sin ID de Base (¡Nuevo!)

Comience sin especificar una base y descúbralas dinámicamente:

{
  "mcpServers": {
    "airtable": {
      "command": "fastmcp",
      "args": ["run"],
      "env": {
        "AIRTABLE_TOKEN": "SU_TOKEN_AIRTABLE"
      }
    }
  }
}

¡Luego use la herramienta list_bases para descubrir sus bases accesibles!

Paso 5: Reinicie su Cliente MCP

Después de la configuración, reinicie Claude Desktop o su cliente MCP para cargar el servidor de Airtable.

🎯 Ejemplos de Uso

Una vez configurado, puede interactuar con sus datos de Airtable naturalmente:

🔷 Desarrollo con TypeScript

import { 
  AirtableMCPServer, 
  ListRecordsInput, 
  AnalyzeDataPrompt 
} from '@rashidazarang/airtable-mcp/types';

const server = new AirtableMCPServer();

// Operaciones de datos seguras de tipos
const params: ListRecordsInput = {
  table: 'Tasks',
  maxRecords: 10,
  filterByFormula: "Status = 'Active'"
};

const records = await server.handleToolCall('list_records', params);

// Análisis IA seguro de tipos
const analysis: AnalyzeDataPrompt = {
  table: 'Sales',
  analysis_type: 'predictive',
  confidence_level: 0.95
};

const insights = await server.handlePromptGet('analyze_data', analysis);

📦 Interacciones en Lenguaje Natural

Operaciones Básicas

"Listar todas mis bases Airtable accesibles"
"Mostrarme todos los registros en la tabla Proyectos"
"Crear una nueva tarea con prioridad 'Alta' y fecha de vencimiento mañana"
"Actualizar el estado de la tarea ID rec123 a 'Completado'"
"Eliminar todos los registros donde el estado sea 'Archivado'"
"¿Qué tablas hay en mi base?"
"Buscar registros donde Estado sea igual a 'Activo'"

Operaciones de Webhook (v1.4.0+)

"Crear un webhook para mi tabla que notifique a https://mi-app.com/webhook"
"Listar todos los webhooks activos en mi base"
"Mostrarme los webhooks recientes"
"Eliminar webhook ach123xyz"

Gestión de Esquemas (v1.5.0+)

"Listar todas mis bases Airtable accesibles"
"Mostrarme el esquema completo para esta base"
"Describir la tabla Proyectos con todos los detalles de campo"
"Crear una nueva tabla llamada 'Tareas' con campos Nombre, Prioridad y Fecha de Vencimiento"
"Agregar un campo de Estado a la tabla Proyectos existente"
"¿Qué tipos de campos están disponibles en Airtable?"

Operaciones por Lotes y Adjuntos (v1.6.0+)

"Crear 5 registros nuevos a la vez en la tabla Tareas"
"Actualizar múltiples registros con nuevos valores de estado"
"Eliminar estos 3 registros en una operación"
"Adjuntar esta URL de imagen al campo de foto del registro"
"¿Quiénes son los colaboradores en esta base?"
"Mostrarme todas las vistas compartidas en esta base"

🛠️ Herramientas Disponibles (33 Total)

📊 Operaciones de Datos (7 herramientas)

🪝 Gestión de Webhooks (5 herramientas)

🔍 Descubrimiento de Esquema (6 herramientas) - Nuevo en v1.5.0

🏗️ Gestión de Tablas (3 herramientas) - Nuevo en v1.5.0

🔧 Gestión de Campos (3 herramientas) - Nuevo en v1.5.0

⚡ Operaciones por Lotes (4 herramientas) - Nuevo en v1.6.0

📎 Gestión de Adjuntos (1 herramienta) - Nuevo en v1.6.0

👁️ Vistas Avanzadas (2 herramientas) - Nuevo en v1.6.0

🏢 Gestión de Base (3 herramientas) - Nuevo en v1.6.0

🤖 Suite de Inteligencia IA (10 prompts) - Nuevo en v3.0.0

🔧 Configuración Avanzada

Usando con Smithery Cloud

Para servidores MCP alojados en la nube:

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": [
        "@smithery/cli",
        "run",
        "@rashidazarang/airtable-mcp",
        "--token",
        "SU_TOKEN",
        "--base",
        "SU_ID_DE_BASE"
      ]
    }
  }
}

Ejecución Directa de Node.js

Si clonó el repositorio:

{
  "mcpServers": {
    "airtable": {
      "command": "node",
      "args": [
        "/ruta/a/airtable-mcp/airtable_simple.js",
        "--token",
        "SU_TOKEN",
        "--base",
        "SU_ID_DE_BASE"
      ]
    }
  }
}

🧪 Pruebas

🔷 TypeScript

Ejecute el conjunto de pruebas integral de TypeScript:

# Instale las dependencias primero
npm install

# Ejecutar verificación de tipos de TypeScript
npm run test:types

# Ejecutar conjunto de pruebas completo de TypeScript
npm run test:ts

# Construir y probar servidor de TypeScript
npm run build
npm run start:ts

El conjunto de pruebas valida:

• Seguridad de Tipos - Validación en tiempo de compilación de todas las interfaces
• Pruebas Empresariales - 33 herramientas con verificación de tipos estricta
• Validación de Prompts IA - Todos los 10 templates de IA con tipificación adecuada
• Manejo de Errores - Gestión de errores segura de tipos
• Rendimiento - Operaciones concurrentes con seguridad de tipos
• Integración - Cumplimiento completo del protocolo MCP

📦 JavaScript

Ejecute el conjunto de pruebas integral para verificar todas las 33 herramientas:

# Establecer variables de entorno primero
export AIRTABLE_TOKEN=su_token
export AIRTABLE_BASE_ID=su_id_de_base

# Iniciar el servidor
node airtable_simple.js &

# Ejecutar pruebas integrales (v1.6.0+)
./test_v1.6.0_comprehensive.sh

El conjunto de pruebas valida:

• Todas las 33 herramientas con llamadas reales a API
• Operaciones CRUD completas
• Gestión avanzada de esquemas
• Operaciones por lotes (crear/actualizar/eliminar múltiples registros)
• Gestión de adjuntos a través de URLs
• Creación de vistas avanzadas y metadatos
• Herramientas de gestión de base y colaboración
• Gestión de webhooks
• Manejo de errores y casos límite
• Verificación de seguridad
• Cobertura de pruebas del 100%

🐛 Solución de Problemas

Error "Conexión Rechazada"

• Asegúrese de que el servidor MCP esté funcionando
• Compruebe que el puerto 8010 no esté bloqueado
• Reinicie su cliente MCP

Error "Token Inválido"

• Verifique que su Token de Acceso Personal sea correcto
• Compruebe que el token tenga los ámbitos requeridos
• Asegúrese de que no haya espacios adicionales en sus credenciales

Error "Base No Encontrada"

• Confirme que su ID de Base sea correcto
• Compruebe que su token tenga acceso a la base

Conflictos de Puerto

Si el puerto 8010 está en uso:

lsof -ti:8010 | xargs kill -9

📚 Documentación

🔷 Documentación de TypeScript

• 📘 Ejemplos de TypeScript - Ejemplos de uso completo seguro de tipos
• 🏗️ Definiciones de Tipo - Definiciones de tipo integrales para todas las características
• 🧪 Pruebas de TypeScript - Marco de pruebas de nivel empresarial

📦 Documentación General

• 🎆 Notas de la Versión v3.1.0 - Último lanzamiento de TypeScript
• Notas de la Versión v1.6.0 - Lanzamiento de características principales
• Notas de la Versión v1.5.0
• Notas de la Versión v1.4.0
• Guía de Configuración Detallada
• Guía de Desarrollo
• Aviso de Seguridad

📦 Historial de Versiones

📂 Estructura del Proyecto

airtable-mcp/
├── src/                    # Código fuente
│   ├── index.js           # Punto de entrada principal
│   ├── typescript/        # Implementación de TypeScript
│   ├── javascript/        # Implementación de JavaScript
│   └── python/            # Implementación de Python
├── dist/                  # Salida de TypeScript compilada
├── docs/                  # Documentación
│   ├── guides/           # Guías de usuario
│   └── releases/         # Notas de lanzamiento
├── tests/                # Archivos de prueba
├── examples/             # Ejemplos de uso
└── types/                # Definiciones de tipo de TypeScript

🤝 Contribuyendo

¡Las contribuciones son bienvenidas! Siéntase libre de enviar una Solicitud de Extracción. Para cambios principales, abra un problema primero para discutir lo que le gustaría cambiar.

Para más detalles, consulte CONTRIBUTING.md

📄 Licencia

Licencia MIT - vea el archivo LICENSE para más detalles

🙏 Agradecimientos

• Construido para el Protocolo de Contexto de Modelo
• Impulsado por API de Airtable
• Compatible con Claude Desktop y otros clientes MCP

�� Soporte

• Problemas: Problemas de GitHub
• Discusiones: Discusiones de GitHub

Versión: 3.2.7 | Estado: ⚡ FastMCP Moderno + 🔷 TypeScript Estable + 🤖 Agente IA + 🔐 OAuth Completo | Protocolo MCP: 2024-11-05 Completo | Seguridad de Tipos: Nivel Empresarial | Inteligencia: 10 Prompts de IA | Seguridad: Completamente Parcheada | OAuth: 34 Herramientas MCP | Última Actualización: 7 de Diciembre de 2025