🧠 Airtable Brain MCP

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

📌 ¿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.

Related MCP server: Airtable MCP Pro

✨ 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 install

En Windows:

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

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