Airtable MCP Server
Provides tools for interacting with Airtable, enabling AI agents to manage bases, tables, records, fields, webhooks, and attachments, with support for natural language queries, batch operations, and schema management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Airtable MCP Server Show me the records in my Customers table"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🧠 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
Área | Capacidades |
🧠 MCP | Herramientas, recursos, prompts y transporte HTTP/STDIO según la implementación. |
🗂️ Airtable | Descubrimiento de bases, tablas, lectura y escritura de registros. |
🛡️ Gobernanza | Allowlist de bases/tablas, operaciones permitidas y redacción de PII en TypeScript. |
⚡ Rendimiento | Cliente asíncrono |
🔁 Integraciones | OAuth 2.0, ChatGPT, webhooks, Redis y Back4App/Mongo opcionales. |
🧰 Calidad | TypeScript, Zod, ESLint, Prettier, Jest, CLI y ejemplos para clientes MCP. |
🚀 Despliegue | Replit, Docker Compose, Railway y ejecución local con |
🧱 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.
Herramienta | Función |
| Lista las bases accesibles con el token configurado. |
| Lista las tablas de una base. |
| Consulta registros con límite y filtro por fórmula. |
| Crea uno o varios registros desde JSON. |
| Actualiza registros desde JSON o TOON. |
| Cambia la base activa durante la sesión. |
🔐 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.
✅
dryRunpara revisar cambios antes de escribir.✅ Idempotency keys y chunking según límites de Airtable.
✅ Allowlist de bases y tablas.
✅ Políticas PII
mask,hashydrop.✅ 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,requestsyaiohttppara 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:writeyschema.bases:read.webhook:managesi 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 ciEn Windows:
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
npm ci3. Configurar el entorno
cp .env.example .envConfiguración mínima:
AIRTABLE_PERSONAL_ACCESS_TOKEN=patXXXXXXXXXXXXXX
AIRTABLE_BASE_ID=appXXXXXXXXXXXXXX
PORT=8000
HOST=0.0.0.0
LOG_LEVEL=INFOAIRTABLE_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 devEquivale a:
python3 src/python/inspector_server.pyFastMCP mediante configuración
source .venv/bin/activate
fastmcp runLa 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:httpJavaScript 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
Variable | Req. | Uso |
| ✅* | Token PAT preferido por FastMCP Python. |
| ✅* | Alias aceptados por algunas implementaciones. |
| ❌ | Base predeterminada; puede configurarse durante la sesión. |
| ❌ | Base predeterminada para TypeScript. |
| ❌ | Bases permitidas separadas por comas. |
| ❌ | Allowlist TypeScript: |
| ❌ | Puerto HTTP; por defecto |
| ❌ | Host HTTP; por defecto |
| ❌ | Nivel |
| ❌ | Transporte de despliegue, normalmente |
| ❌ | Oculta detalles sensibles en errores TypeScript. |
| ❌ | Validación estricta; activa por defecto. |
| ❌ | Auth del servidor TypeScript. |
| ❌ | Integraciones opcionales. |
Consulta .env.example para OAuth, Back4App/Parse, TOON y variables adicionales.
🛡️ Seguridad y buenas prácticas
Usa secretos del entorno, nunca tokens en código, commits o ejemplos reales.
Limita bases y tablas con
AIRTABLE_ALLOWED_BASESyAIRTABLE_ALLOWED_TABLES.Activa
dryRunantes de escribir desde TypeScript.Usa idempotency keys cuando una operación pueda repetirse.
Separa tokens y bases de desarrollo y producción.
No expongas HTTP sin autenticación, proxy o red privada.
Otorga solo los scopes Airtable necesarios.
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 testLas 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 --buildO con la imagen principal:
docker build -t airtable-brain-mcp:latest .
docker run --rm --env-file .env -p 8000:8000 airtable-brain-mcp:latestLos 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=INFOReplit
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
🤝 Contribuir
Revisa la implementación que vas a modificar.
Mantén compatibles las rutas y variables existentes cuando sea posible.
Añade o actualiza pruebas para nuevas herramientas.
Ejecuta build, tipos, lint y formato.
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:
Available Tools
11 toolscreateB
Create Airtable records (requires diff-before-write via dryRun first).
Inputs: table (required), baseId (required), records (required), dryRun, +2 more. Returns: diff, dryRun, records, warnings
create_webhookB
Create a new webhook for a base.
Inputs: no named parameters.
describeC
Describe Airtable base or table schema.
Inputs: scope (required), baseId (required), table, includeViews, +1 more. Returns: base, views, tables
list_basesA
List all accessible Airtable bases with their names, IDs, and permission levels
Inputs: no named parameters. Returns: bases
list_exceptionsC
List recent exceptions and remediation proposals.
Inputs: limit, since, cursor, severity. Returns: items, cursor
list_governanceB
Return governance allow-lists and PII masking policies.
Inputs: no named parameters. Returns: piiFields, allowedBases, allowedTables, loggingPolicy, +3 more
list_webhooksB
List Airtable webhooks for the default base.
Inputs: no named parameters.
queryC
Query Airtable records with filtering, sorting, and pagination.
Inputs: table (required), baseId (required), view, sorts, +6 more. Returns: offset, records, summary
refresh_webhookB
Refresh webhook expiration.
Inputs: no named parameters.
updateB
Update Airtable records (requires diff-before-write via dryRun first).
Inputs: table (required), baseId (required), records (required), dryRun, +4 more. Returns: diff, dryRun, records, conflicts
upsertC
Upsert Airtable records using performUpsert.fieldsToMergeOn.
Inputs: table (required), baseId (required), records (required), performUpsert (required), +4 more. Returns: diff, dryRun, records, conflicts
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Most tools target clearly distinct operations: query vs. describe vs. list_bases separate records, schema, and base discovery, and the three webhook tools are well differentiated. However, the bare names create/update/upsert don't indicate the resource, so an agent could plausibly confuse create with create_webhook or wonder whether update touches records or schema.
Half the tools follow a clean verb_noun pattern (list_bases, list_webhooks, create_webhook, refresh_webhook, list_governance), but the core record operations are bare verbs with no object (create, update, upsert, query, describe). The convention is readable but clearly mixed within a single server.
Eleven tools is well within a healthy range for an Airtable surface covering bases, records, schema, webhooks, and governance. Each tool maps to a recognizable Airtable capability rather than padding the list.
Record creation, update, upsert, query, and schema description are covered, but there is no delete-record tool, which is a core lifecycle operation agents will need. Webhooks also lack a delete/deactivate operation, leaving dead ends in two areas.
Maintenance
Related MCP Connectors
Hosted Airtable MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Official Airtable MCP server — database and operations layer for agents.
Teable is an AI spreadsheet for business that combines a familiar spreadsheet interface with a structured database. Its remote MCP server lets AI agents inspect project and table structure, read and update records, and access the Teable API through OAuth with existing project permissions. Website: [teable.ai](https://teable.ai)
Query and update Teable records, manage tables, and access the Teable API with AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides tools for AI assistants to interact with Airtable databases, enabling CRUD operations on Airtable bases and tables.7 npmMIT
- -licenseNot gradedqualityNot gradedmaintenanceEnables comprehensive interaction with Airtable databases through MCP for ChatGPT Business/Projects. Supports full CRUD operations, querying, searching, and database management with pagination, filtering, and per-user authentication.-
- AlicenseNot gradedqualityCmaintenanceProvides read and write access to Airtable databases, enabling LLMs to inspect schemas, search, create, update, and delete records, tables, and fields, as well as manage comments on records.MIT
- AlicenseBqualityDmaintenanceEnables AI assistants and applications to interact with Airtable bases through a secure OAuth-authenticated MCP interface, providing complete API coverage for all Airtable operations.10MIT