Airtable User MCP

---

Principais Recursos

Recurso	O que faz	Tipos de arquivo
Editor de Fórmulas	Realce de sintaxe, IntelliSense, beautify / minify	.formula, .min.formula
Editor de Scripts	Completions, documentação ao passar o mouse, diagnósticos	.ats, .script
Editor de Automação	Completions, documentação ao passar o mouse, diagnósticos	.ata, .automation
Servidor MCP (72 ferramentas + manage_tools)	API interna completa do Airtable — esquema, visualizações, campos, registros, extensões, modelos	—
Servidor de Linguagem (LSP)	Suporte multi-editor independente — Neovim, Zed, Helix, OpenCode	Todos acima
Configuração Automática de IDE	Configuração MCP com um clique para Cursor, Windsurf, Claude Desktop, Cline, Amp	—
Habilidades de IA	Regras e fluxos de trabalho pré-construídos específicos do Airtable para assistentes de codificação de IA	—
Daemon + Túnel	Servidor de fundo persistente; acesso remoto opcional via Cloudflare ou ngrok	—
Perfis de Ferramentas	read-only (12 ferramentas) / safe-write (54 ferramentas) / full (72 ferramentas) / custom escopos de permissão	—
Autenticação via Chaveiro do SO	Login no Airtable baseado em navegador com SSO/2FA — credenciais no chaveiro do seu SO	—

---

Por que isso existe

A API Web pública do Airtable nunca expôs algumas das tarefas mais comuns que os desenvolvedores realmente precisam: criar um campo de fórmula, ajustar o conjunto de filtros de uma visualização, instalar uma extensão ou validar uma fórmula antes de quebrar a produção. O servidor MCP oficial do Airtable é um wrapper fino sobre essa mesma API REST, então ele herda todas essas lacunas.

airtable-user-mcp é um complemento ao MCP oficial do Airtable, não um substituto. Ele usa a API interna do próprio Airtable (a mesma que a interface web usa) para cobrir exatamente a área que a API REST não alcança. Registre ambos os servidores no seu cliente de IA e seu assistente terá a experiência completa de automação do Airtable — registros via HTTP pelo MCP oficial, além de esquema, fórmulas, visualizações e extensões por meio deste.

---

O que o airtable-user-mcp adiciona além do MCP oficial do Airtable

Este é um mapa de cobertura, não uma decisão de "escolha um" — os dois servidores são complementares e projetados para rodar lado a lado.

Capacidade	MCP oficial do Airtable	airtable-user-mcp
Total de ferramentas	~17	73 (72 + manage_tools)
Modelo de autenticação	Token de Acesso Pessoal ou OAuth, configuração por escopo	Faça login uma vez com sua conta normal do Airtable (SSO/2FA suportado)
Transporte	HTTP (remoto)	stdio (local, privado)
Os dados nunca saem da sua máquina	❌ As solicitações passam pelo mcp.airtable.com	✅ Executa localmente contra a API do Airtable
Leitura de esquema (bases, tabelas, campos, visualizações)	Parcial (sem configuração de visualização)	Completa — filtros, classificações, agrupamentos, visibilidade, altura da linha, descrições
Leitura de registros com valores de campo resolvidos	Parcial	✅ query_records — retorna campos de lookup/rollup/fórmula totalmente resolvidos
Pesquisa de registros por texto (incl. campos de lookup)	❌ filterByFormula com FIND()/SEARCH() falha silenciosamente em campos de lookup	✅ query_records.search — correspondência de substring em todos os valores resolvidos
Duplicar registros	❌	✅ duplicate_records
Criar campos de fórmula	❌ UNSUPPORTED_FIELD_TYPE_FOR_CREATE	✅
Criar campos de rollup	❌	✅
Criar campos de lookup / multipleLookupValues	❌	✅
Criar campos de contagem	❌	✅
Atualizar o texto da fórmula de um campo existente	❌	✅
Validar uma fórmula antes de aplicar	❌	✅
Renomear / duplicar / excluir campos com segurança	Parcial (sem duplicação, sem resumo de dependências)	✅ com proteção expectedName + pré-visualização de dependências
Criar visualizações (grade/formulário/kanban/calendário/galeria/gantt/lista)	❌ (a API não tem endpoint de criação de visualização)	✅
Definir/anexar filtros de visualização (AND/OR aninhados)	❌	✅
Definir classificações de visualização	❌	✅
Definir agrupamento de visualização	❌	✅
Alterar ordem das colunas	❌	✅
Mostrar/ocultar colunas em uma visualização	❌	✅
Alterar altura da linha	❌	✅
Duplicar uma visualização com sua configuração completa	❌	✅
Descrições de visualização, quebra de célula, capas, configuração de cores, datas de calendário, colunas congeladas	❌	✅
Seções da barra lateral (criar, renomear, mover, excluir)	❌	✅
Modelos de registro (criar, pré-preencher, duplicar, aplicar, excluir)	❌	✅
Metadados de formulário (descrição, redirecionamento, atribuição, branding)	❌	✅
Gerenciamento de extensões / blocos (instalar, habilitar, renomear, duplicar, remover)	❌	✅
Criar páginas de painel	❌	✅
Autodiagnóstico do daemon (sessão morta? navegador ocupado? daemon ausente?)	❌	✅ manage_daemon action=status, além de iniciar / reiniciar / parar / túnel / rotação de token
Perfis de ferramentas e alternâncias por ferramenta	❌	✅ somente leitura (12) / escrita segura (54) / completo (72) / personalizado
Proteções de segurança para ações destrutivas	Depende dos escopos do token	✅ correspondência expectedName, resumo de dependências, sinalizador force
Limite de criação de registros em lote	10 / solicitação	Usa o mesmo limite do Airtable; sem restrição adicional
Instalação com um clique em VS Code / Cursor / Windsurf / Cline / Amp	Edição manual de JSON por IDE	✅ Um clique via a extensão complementar
Editor de fórmulas com IntelliSense	❌	✅ (extensão do VS Code)
Armazenamento de credenciais	Você gerencia o PAT	Chaveiro do SO, atualização automática
Requisito de plano	Plano Airtable com acesso à API + escopos de token	Qualquer plano em que você possa fazer login
Preço	Gratuito	Gratuito, MIT

Fontes: Documentação oficial do MCP do Airtable, Referência da API Web do Airtable e o tópico de resumo UNSUPPORTED_FIELD_TYPE_FOR_CREATE.

---

Use os dois MCPs juntos

npx -y airtable-user-mcp login          # one-time browser login
claude mcp add airtable --scope user -- npx -y airtable-user-mcp   # Claude Code

airtable-user-mcp é aditivo. Registre o MCP oficial do Airtable seguindo o guia de configuração do Airtable e adicione este ao lado dele no mesmo bloco mcpServers:

{
  "mcpServers": {
    "airtable-user-mcp": {
      "command": "npx",
      "args": ["-y", "airtable-user-mcp"]
    }
  }
}

Seu cliente MCP exporá todas as ferramentas de ambos os servidores. As duas entradas são independentes — renomeie as chaves (airtable, airtable-official, airtable-user-mcp, etc.) como fizer sentido para seu fluxo de trabalho.

---

O Que Há Neste Repositório

Este monorepo entrega três produtos a partir de uma única árvore de código-fonte:

---

Demonstração

---

Recursos

Servidor MCP (72 Ferramentas + manage_tools)

Gerencie bases do Airtable com capacidades não disponíveis através da API REST oficial:

Categoria	Ferramentas	Destaques
Leitura de Esquema	11	Inspeção completa do esquema — bases, tabelas, campos, visualizações, seções da barra lateral, modelos de registro; baixar todos os campos de fórmula para arquivos locais
Leitura de Registros	1	query_records — até 1 000 registros/chamada com valores de campo resolvidos; o parâmetro search funciona em campos de lookup/rollup (a API REST filterByFormula não funciona)
Escrita de Registros	4	create_records / update_records / duplicate_records / upload_attachment (a única forma de escrever células multipleAttachments por URL)
Registros Destrutivos	1	delete_records — excluir registros em lote de uma tabela
Gerenciamento de Tabelas	3	criar / renomear / excluir tabelas
Gerenciamento de Campos	9	Criar campos de fórmula / rollup / lookup / contagem, validar fórmulas, atualizar descrições, excluir individualmente ou em massa
Configuração de Visualizações	20	Filtros, classificações, agrupamento, colunas, congelamento, altura da linha, capas, regras de cores, datas de calendário, criar / duplicar / renomear / excluir
Seções da Barra Lateral	4	Criar, renomear, mover para seção, excluir (promove automaticamente as visualizações contidas para não agrupadas)
Modelos de Registro	8	Criar / renomear / descrever / definir células / definir colunas / duplicar / aplicar / excluir scaffolds de linha salvos
Metadados de Formulário	2	Descrição, URL de redirecionamento, atribuição, cópia para o respondente, branding (visualizações de formulário legadas)
Gerenciamento de Extensões	7	Criar, instalar, habilitar/desabilitar, renomear, duplicar, remover extensões
Gerenciamento de Ferramentas	1	Listar perfis, alternar perfil, alternar ferramentas/categorias (meta-ferramenta, sempre habilitada — não faz parte de nenhum perfil)
Sincronização de Base	1	sync_base — copiar o esquema, as visualizações e os registros de uma base para outra. mode=plan/diff/status são somente leitura; mode=apply modifica o destino e, com policy=mirror mais os sinalizadores de confirmação, pode excluir tabelas, campos, visualizações, seções e registros; mode=reconcile atualiza o estado de mapeamento local. Protegido contra desvios e retomável via diário.
Controle do Daemon	1	manage_daemon — action=status é um autodiagnóstico somente leitura: atividade do daemon, transporte, tempo de atividade, URL do túnel e o estado da sessão ao vivo (sessão morta, último disparo do disjuntor com o corpo de resposta do próprio Airtable, fila de navegador ocupado) que distingue "daemon ausente" de "sessão morta" de "navegador ocupado". Também start / restart / stop / tunnel_enable / tunnel_disable / token_rotate. Somente perfil full.

Consulte a referência completa de ferramentas em packages/mcp-server/README.md.

Um daemon compartilhado

A extensão inicia o daemon MCP compartilhado sempre que uma chamada de ferramenta precisar, então cada janela do VS Code usa uma sessão de navegador do Airtable em vez de uma por janela — essa duplicação era o que causava a maioria dos erros de "sessão morta". Um daemon que você parar pelo painel permanece parado e, se ele não puder iniciar, a extensão recorre a um servidor por janela para que suas ferramentas continuem funcionando. Como um daemon geralmente está em execução, outros clientes MCP na mesma máquina (Claude Desktop, Cursor, Cline, Amp) conectam-se a ele e, portanto, executam sob seu modo de autenticação e cliente HTTP em vez dos próprios — deliberadamente, pois dois navegadores em um perfil do Airtable travam. Cada um desses clientes imprime uma linha no stderr informando isso. Veja Compartilhando um daemon entre clientes.

Servidor LSP

airtable-user-lsp é um servidor de linguagem autônomo para arquivos de fórmula, script e automação do Airtable — funciona em qualquer editor compatível com LSP, não apenas no VS Code.

# stdio mode — works standalone, no daemon needed
npx airtable-user-lsp --stdio

Recursos: diagnósticos, autocompletar, documentação ao passar o mouse e ajuda de assinatura para arquivos .formula, .ats e .ata.

Quando o daemon está em execução, ele inicia automaticamente o airtable-user-lsp --tcp para que vários editores compartilhem uma única instância do servidor de linguagem. A porta TCP é gravada em ~/.airtable-user-mcp/daemon.lock como port_lsp.

Consulte packages/lsp-server/README.md para configuração por editor (Neovim, Zed, OpenCode, Helix).

---

IDEs Suportadas

A extensão configura automaticamente o MCP para todos os principais editores habilitados para IA:

Não usa VS Code? Use o servidor MCP autônomo diretamente:

npx airtable-user-mcp

---

Encontre-nos

---

Requisitos

• VS Code ^1.100.0 (ou qualquer fork que exponha a API McpServerDefinitionProvider)
• Node.js — incluído via o runtime do VS Code; nenhuma instalação separada é necessária
• Google Chrome (ou Edge / Chromium) — o fluxo de login do Airtable usa Patchright em modo headless. Recorre a msedge no Windows e a chromium no Linux. A extensão mostra um aviso acionável se nenhum navegador suportado for detectado.

---

Desenvolvimento

Este é um monorepo pnpm.

Pacote	Descrição
packages/extension	Host de extensão do VS Code (TypeScript + tsup)
packages/webview	Webview do painel React (Vite + Tailwind v4)
packages/shared	Tipos compartilhados e protocolo de mensagens
packages/mcp-server	airtable-user-mcp — servidor MCP Node ESM
packages/lsp-server	airtable-user-lsp — servidor LSP para arquivos de fórmula / script / automação
scripts/	Ferramentas de build (empacotador esbuild, fornecimento de dependências)

pnpm install          # install all packages
pnpm build            # build shared → webview → mcp bundle → extension
pnpm package          # build + create airtable-formula-X.Y.Z.vsix
pnpm test             # run all unit tests
pnpm dev              # start webview dev server (browser preview)

Como o servidor MCP é empacotado: scripts/bundle-mcp.mjs compila com esbuild packages/mcp-server/src/ em packages/extension/dist/mcp/. Em seguida, scripts/prepare-package-deps.mjs fornece patchright, patchright-core, otpauth, impit e @ngrok/ngrok em dist/node_modules/ antes de vsce package ser executado, para que uma extensão instalada não precise de npm install em tempo de execução.

VSIXes específicos por plataforma. impit (o cliente HTTP Chrome-TLS) e @ngrok/ngrok (o provedor de túnel ngrok) mantêm seu binário nativo compilado em pacotes npm separados por plataforma, e apenas o que corresponde à máquina de build é instalado. Portanto, um único VSIX não pode conter binários nativos funcionais para todas as plataformas. Em vez disso, publicamos um VSIX por plataforma, cada um incluindo apenas seus próprios binários — VS Code e Open VSX entregam a cada usuário o build correspondente à sua máquina. Alvos suportados:

Alvo	impit	@ngrok/ngrok
win32-x64	impit-win32-x64-msvc	@ngrok/ngrok-win32-x64-msvc
win32-arm64	impit-win32-arm64-msvc	@ngrok/ngrok-win32-arm64-msvc
darwin-x64	impit-darwin-x64	@ngrok/ngrok-darwin-x64
darwin-arm64	impit-darwin-arm64	@ngrok/ngrok-darwin-arm64
linux-x64	impit-linux-x64-gnu	@ngrok/ngrok-linux-x64-gnu
linux-arm64	impit-linux-arm64-gnu	@ngrok/ngrok-linux-arm64-gnu
alpine-x64	impit-linux-x64-musl	@ngrok/ngrok-linux-x64-musl
alpine-arm64	impit-linux-arm64-musl	@ngrok/ngrok-linux-arm64-musl

linux-armhf (ARM de 32 bits) não é publicado: impit não inclui build arm-gnueabihf, então um VSIX armhf anunciaria airtableFormula.mcp.httpClient: "impit" e falharia com "Cannot find native binding". Nenhum fallback sem alvo é publicado também, pelo mesmo motivo.

A matriz é definida uma vez em scripts/vsix-targets.mjs; versões e hashes de tarball são fixados em pnpm-lock.yaml. scripts/package-targets.mjs compila cada alvo e scripts/assert-vsix-binaries.mjs verifica se cada artefato contém exatamente os arquivos .node da sua própria plataforma e nenhum outro — byte por byte, contra os hashes SHA-256 em scripts/native-binary-digests.json, que são registrados a partir de tarballs verificados contra os hashes de integridade de pnpm-lock.yaml. Nomes de arquivo, package.json os/cpu e um número mágico são todos rótulos que um artefato carrega sobre si mesmo e não podem distinguir um binário x64 de um ARM64, ou um build glibc de um musl; um hash exato pode.

Juntos, esses são oito testes de fumaça de empacotamento/verificação de artefatos de alvo — oito arquivos .vsix compilados e seus conteúdos verificados em uma máquina. Eles não são testes de fumaça de tempo de execução de oito bindings nativos: qualquer host individual só pode carregar o binding compilado para si mesmo, então apenas o binding do alvo do host recebe um carregamento real em tempo de execução. Verificar os outros sete por conteúdo exato é a afirmação mais forte que um build de host único pode fazer sobre eles.

O pacote npm autônomo airtable-user-mcp não é afetado e permanece universal — o npm resolve a dependência opcional correta na sua própria máquina no momento da instalação.

---

Apoie Este Projeto

Este projeto é construído e mantido com a ajuda de ferramentas de codificação por IA. Se você o acha útil e deseja apoiar o desenvolvimento contínuo (novas ferramentas, atualizações, correções de bugs), você pode contribuir presenteando créditos do Claude Code — a principal ferramenta usada para construir este projeto.

Interessado? Abra uma issue ou entre em contato para discutir solicitações de recursos e patrocínio.

---

Licença

MIT