🧠 Airtable Brain MCP

Servidor Model Context Protocol (MCP) para conectar asistentes de IA con Airtable de forma segura, extensible y orientada a automatización.

<p align="center"> <strong>Datos de Airtable disponibles para tus agentes, con control de acceso, validación y varios transportes MCP.</strong> </p>

📌 ¿Qué es este proyecto?

Airtable Brain MCP es una copia evolucionada y una base de experimentación del servidor airtable-mcp, adaptada para mejorar sus capacidades y facilitar su ejecución en entornos locales, Replit, Docker y Railway.

Expone Airtable como herramientas MCP para que clientes como Claude, ChatGPT, Cursor, Windsurf u otros agentes compatibles puedan:

• 🔎 Descubrir bases, tablas y registros.
• ✍️ Crear y actualizar datos desde lenguaje natural.
• 🧩 Consultar esquemas y metadatos.
• 🔐 Aplicar reglas de gobernanza, listas permitidas y políticas PII.
• 🌐 Ejecutar el servidor mediante STDIO o HTTP.
• 🔌 Integrar OAuth, webhooks y almacenamiento auxiliar.

Importante: este repositorio no es una copia oficial de Airtable ni del protocolo MCP. Se mantiene como una base mejorada para adaptar, probar y ampliar funcionalidades sobre el proyecto MCP original.

✨ Capacidades principales

🧱 Implementaciones disponibles

Las variantes comparten el objetivo, pero no exponen exactamente las mismas herramientas.

✅ FastMCP Python — recomendada

Entrada principal: src/python/inspector_server.py

Es la ruta usada por npm run dev y por app.py. Utiliza FastMCP 2.x, httpx y transporte HTTP.

🔐 MCP Python extendido

Entrada: src/python/auth/src/server.py

Añade get_record, delete_records, recursos airtable://, roots MCP para exportaciones, prompts guiados, completions y parseo JSON/TOON. También contiene puntos de integración para autenticación y OAuth.

🔷 TypeScript — gobernanza y operaciones estructuradas

Entrada: src/typescript/airtable-mcp-server.ts

Herramientas registradas:

list_bases · describe · query · list_governance · list_exceptions · create · update · upsert · list_webhooks · create_webhook · refresh_webhook

Incluye:

• ✅ Validación estricta con Zod.
• ✅ dryRun para revisar cambios antes de escribir.
• ✅ Idempotency keys y chunking según límites de Airtable.
• ✅ Allowlist de bases y tablas.
• ✅ Políticas PII mask, hash y drop.
• ✅ Rate limiting y registro de excepciones.
• ✅ Transporte STDIO y HTTP/SSE.

📦 JavaScript y OAuth — compatibilidad

• src/javascript/airtable_simple_production.js: servidor JavaScript con validación, rate limiting y compatibilidad HTTP histórica.
• src/javascript/airtable_simple.js: implementación JavaScript simple/legacy.
• src/oauth_server.js: servidor OAuth separado para autorización y callbacks.

Estas variantes se conservan para compatibilidad y migración. Para nuevos cambios, prioriza FastMCP Python o TypeScript.

🗺️ Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│ Cliente MCP: Claude · ChatGPT · Cursor · Windsurf · Inspector   │
└───────────────────────────────┬─────────────────────────────────┘
                                │ MCP / STDIO / HTTP
┌───────────────────────────────▼─────────────────────────────────┐
│ FastMCP Python · MCP SDK TypeScript · JavaScript legacy          │
└───────────────────────────────┬─────────────────────────────────┘
                                │ Validación · gobernanza · auth
┌───────────────────────────────▼─────────────────────────────────┐
│ Airtable Metadata API · Records API · Webhooks · OAuth           │
└─────────────────────────────────────────────────────────────────┘

🧰 Stack tecnológico

Backend y protocolo

• Python 3.10+ y FastMCP 2.x para la ruta principal.
• MCP Python SDK para la variante extendida.
• Node.js 18+ para JavaScript, TypeScript y OAuth.
• TypeScript 5.3 con @modelcontextprotocol/sdk.
• Zod para validar entradas y salidas estructuradas.

Integración y operación

• Airtable Web API para metadata, registros y webhooks.
• `httpx`, requests y aiohttp para comunicación HTTP.
• Redis y Back4App/Parse como almacenamiento opcional.
• Jest, ts-jest, ESLint y Prettier.
• Docker, Docker Compose, Railway y Replit.

📁 Estructura del proyecto

.
├── app.py                         # Entrada web para Railway/Nixpacks
├── main.py                        # Entrada Python alternativa
├── package.json                   # Scripts y dependencias Node/TypeScript
├── requirements.txt               # Dependencias Python/FastMCP
├── fastmcp.json                   # Configuración FastMCP
├── src/
│   ├── python/
│   │   ├── inspector_server.py    # FastMCP recomendado
│   │   ├── server.py              # Variante FastMCP base
│   │   └── auth/                  # Recursos, prompts y OAuth
│   ├── typescript/                # Servidor tipado y gobernado
│   ├── javascript/                # Servidores JavaScript
│   └── oauth_server.js            # Servicio OAuth
├── routes/                        # Rutas HTTP auxiliares
├── services/                      # Airtable, auth y almacenamiento
├── middleware/                    # Seguridad y formato TOON
├── tests/                         # Smoke tests e integración
├── examples/                      # Configuraciones de clientes
├── docs/                          # Guías ampliadas
├── docker/                        # Dockerfiles alternativos
└── bin/                           # CLI de servidor y CRUD

🚀 Inicio rápido

1. Requisitos

• Python 3.10+.
• Node.js 18+.
• Cuenta de Airtable.
• Personal Access Token con data.records:read, data.records:write y schema.bases:read.
• webhook:manage si utilizarás webhooks.

2. Instalar dependencias

git clone <URL_DEL_REPOSITORIO>
cd airtable-mcp

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

npm ci

En Windows:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
npm ci

3. Configurar el entorno

cp .env.example .env

Configuración mínima:

AIRTABLE_PERSONAL_ACCESS_TOKEN=patXXXXXXXXXXXXXX
AIRTABLE_BASE_ID=appXXXXXXXXXXXXXX
PORT=8000
HOST=0.0.0.0
LOG_LEVEL=INFO

AIRTABLE_BASE_ID puede omitirse para comenzar con list_bases; las operaciones sobre tablas y registros necesitarán una base activa. También se aceptan AIRTABLE_PAT, AIRTABLE_TOKEN y AIRTABLE_API_TOKEN en las variantes que los implementan.

🔒 Nunca guardes tokens en Git. Usa secretos del entorno en Replit, Railway o tu proveedor de despliegue.

4. Ejecutar

#### Desarrollo recomendado

npm run dev

Equivale a:

python3 src/python/inspector_server.py

#### FastMCP mediante configuración

source .venv/bin/activate
fastmcp run

La configuración se encuentra en fastmcp.json. Para producción, npm start configura HTTP, 0.0.0.0 y el puerto proporcionado por PORT.

#### TypeScript

npm run build
npm run start:http

#### JavaScript legacy

npm run start:js

🤖 Configurar un cliente MCP

Ejemplo genérico para Claude Desktop, Cursor u otro cliente que soporte comandos MCP:

{
  "mcpServers": {
    "airtable-brain": {
      "command": "fastmcp",
      "args": ["run"],
      "env": {
        "AIRTABLE_PERSONAL_ACCESS_TOKEN": "TU_TOKEN",
        "AIRTABLE_BASE_ID": "appXXXXXXXXXXXXXX"
      }
    }
  }
}

Para un servidor remoto, despliega la variante HTTP y configura la URL MCP entregada por FastMCP o tu plataforma. No expongas producción sin autenticación, proxy o allowlist.

💬 Ejemplos de interacción

Lista mis bases de Airtable accesibles.
Muéstrame las tablas de la base appXXXXXXXXXXXXXX.
Consulta los registros activos de Projects usando una fórmula de Airtable.
Prepara una actualización y muéstrame primero el dry run.
Describe el esquema de la base y aplica la política de privacidad definida.

⚙️ Variables de entorno

Consulta .env.example para OAuth, Back4App/Parse, TOON y variables adicionales.

🛡️ Seguridad y buenas prácticas

1. Usa secretos del entorno, nunca tokens en código, commits o ejemplos reales.
2. Limita bases y tablas con AIRTABLE_ALLOWED_BASES y AIRTABLE_ALLOWED_TABLES.
3. Activa dryRun antes de escribir desde TypeScript.
4. Usa idempotency keys cuando una operación pueda repetirse.
5. Separa tokens y bases de desarrollo y producción.
6. No expongas HTTP sin autenticación, proxy o red privada.
7. Otorga solo los scopes Airtable necesarios.
8. Configura políticas PII si procesas información sensible.

🧪 Calidad y pruebas

npm run build
npm run test:types
npm run lint
npm run format:check
npm test

Las pruebas de integración en tests/ pueden requerir un servidor disponible y acceso real a Airtable. No las ejecutes contra una base con datos críticos.

node tests/test_mcp_comprehensive.js
bash tests/test_all_features.sh

🐳 Docker

cp .env.example .env
docker compose up --build

O con la imagen principal:

docker build -t airtable-brain-mcp:latest .
docker run --rm --env-file .env -p 8000:8000 airtable-brain-mcp:latest

Los Dockerfiles específicos se encuentran en docker/.

🚂 Railway y Replit

Railway

El repositorio incluye railway.json, railway.toml y Procfile. railway.json usa python3 app.py y respeta PORT.

Variables mínimas:

AIRTABLE_PERSONAL_ACCESS_TOKEN
AIRTABLE_BASE_ID       # opcional para descubrimiento inicial
LOG_LEVEL=INFO

Replit

El workflow configurado es Iniciar y combina Fastmcp run con npm run dev. Para una ejecución local simple utiliza npm run dev. Si ejecutas dos servidores HTTP a la vez, usa puertos distintos para evitar colisiones.

📚 Documentación relacionada

• Guía de despliegue
• Estructura del proyecto
• Integración con Airtable
• Guía de instalación
• Inicio rápido
• Despliegue FastMCP
• Integración Claude
• Funciones mejoradas
• OAuth
• Contribución
• Aviso de seguridad
• Changelog

🤝 Contribuir

1. Revisa la implementación que vas a modificar.
2. Mantén compatibles las rutas y variables existentes cuando sea posible.
3. Añade o actualiza pruebas para nuevas herramientas.
4. Ejecuta build, tipos, lint y formato.
5. Documenta cambios de protocolo, seguridad o configuración.

Consulta CONTRIBUTING.md para el flujo completo.

📄 Licencia y atribución

Este proyecto se distribuye bajo la licencia MIT y utiliza:

• Model Context Protocol
• FastMCP
• Airtable Web API
• MCP TypeScript SDK

<p align="center"> <strong>Construido para explorar, automatizar y mejorar la conexión entre agentes de IA y Airtable.</strong><br> _{Versión del paquete Node: 3.2.7 · Licencia MIT} </p>