Airtable용 Model Context Protocol (MCP) 서버

Airtable과 연동되는 Model Context Protocol (MCP) 서버로, 전체 CRUD 작업, 스키마 관리, 레코드 코멘트, 웹훅(webhooks), 배치 작업(batch operations), 거버넌스 제어(governance controls), 그리고 AI 기반 분석 기능을 제공합니다.

Version 5.1.0 | MCP 프로토콜 2026-07-28 (상태 비저장형 코어, 레거시 2025년도 클라이언트 여전히 지원) | Claude, Codex, Cursor, Windsurf, VS Code 및 모든 MCP 클라이언트와 작동 |

설치가 필요 없습니다. 이 내용을 Claude Desktop 설정에 추가하고 다시 시작하기만 하면 됩니다:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
"mcpServers": {
"airtable": {
...

이것이 전부입니다. npx가 서버를 자동으로 다운로드하고 실행합니다. git clone이나 npm install이 필요 없습니다.

토큰은 airtable.com/create/tokens에서 받으세요 — 아래 토큰 범위(Token Scopes)에 나열된 모든 권한을 부여해야 합니다. 베이스 ID는 베이스를 볼 때 URL에서 가져오거나: https://airtable.com/[BASE_ID]/... (또는 생략하고 list_bases를 사용하여 베이스를 동적으로 발견할 수 있습니다).

curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash

이 스크립트는 전제 조건을 확인하고, Airtable 토큰을 요청하며, MCP 설정을 ~/.claude.json에 작성합니다. Claude Code를 다시 시작하거나 (/mcp) 실행하여 연결하세요.

토큰을 직접 전달할 수도 있습니다:

curl -fsSL https://raw.githubusercontent.com/rashidazarang/airtable-mcp/main/setup.sh | bash -s -- YOUR_AIRTABLE_TOKEN

~/.claude.json의 mcpServers 아래에 추가하세요:

{
"airtable": {
"type": "stdio",
...

왜 bash 래퍼(wrapper)를 사용하나요? npx가 동일한 패키지 이름의 package.json을 포함하는 디렉토리에서 실행될 때 바이너리를 해결하지 못할 수 있기 때문입니다. cd /tmp && 접두사는 이 예외 케이스를 방지합니다.

이 서버는 모든 MCP 클라이언트와 작동합니다. 최신 2026-07-28 프로토콜과 2025년도 클라이언트를 모두 자동으로 지원하므로, 어느 쪽에도 설정할 필요가 없습니다.

한 명령어만으로 가능합니다:

codex mcp add airtable -- npx -y @rashidazarang/airtable-mcp

또는 ~/.codex/config.toml (또는 .codex/config.toml)에 편집하세요.

신뢰할 수 있는 프로젝트를 위해 직접:

[mcp_servers.airtable]
command = "npx"
args = ["-y", "@rashidazarang/airtable-mcp"]
...

~/.cursor/mcp.json에 추가합니다.

(전역) 또는 .cursor/mcp.json

(프로젝트별):

{
"mcpServers": {
"airtable": {
...

WhyCursor는 에이전트를 AIRTABLE_TOOLSET=core에서 제한할까요?
모든 서버에 걸쳐 40개의 활성화된 도구를 제공하며, 이 서버는 42개를 노출합니다. core 프로필은 기록 중심의 도구(읽기, 쓰기, 배치, 거버넌스) 18개를 등록하여 다른 서버를 위한 여지를 남깁니다. Airtable이 유일한 MCP 서버이고 Cursor의 Tools & MCP 설정에서 개별 도구를 비활성화하여 제한을 관리하는 경우 이를 생략하거나 (full로 설정합니다). 또한 참고하세요: Cursor는 Agent 및 Plan 모드에서만 MCP 도구를 제공하며 (Ask/Edit 제외), 도구와 리소스를 소비하지만 MCP 프롬프트는 소비하지 않습니다.

동일한 JSON 블록을 ~/.codeium/windsurf/mcp_config.json에 추가합니다.
(Cascade → MCP 설정). Windsurf는 전체 도구 세트가 필요할 경우 개별 도구 토글링을 지원합니다.

.vscode/mcp.json에 추가합니다.

:

{
"servers": {
"airtable": {
...

두 프로토콜 시대 모두 서비스됨— 최신 2026-07-28 클라이언트와 레거시 2025년 클라이언트(Codex, Cursor, Windsurf, Cline, Zed 및 오늘날 대부분의 다른 클라이언트)가 자동으로 협상합니다.도구 이름은 클라이언트 안전함— 순수한 snake_case이며 길이 제한보다 훨씬 짧고 : 및 * (Cursor의 allowlist 문법에 의해 예약됨: server:tool)가 없습니다.로그는 절대 stdout을 건드리지 않음— 모든 로깅은 stderr로 가므로 stdio 프레이밍이 손상되지 않습니다.원격/HTTP 클라이언트— 서버를 PORT 또는 MCP_HTTP_PORT를 설정하여 시작하고 클라이언트를 http://host:port/mcp에 지정합니다 (스트리밍 가능한 HTTP, 상태 비저장; 오케스트레이터용 /health).도구 제한— 활성화된 도구를 제한하는 클라이언트의 경우 또는 에이전트의 컨텍스트를 간소화하기 위해 AIRTABLE_TOOLSET=core 또는 명시적인 allowlist(예: AIRTABLE_TOOLSET=describe,query,list_records)를 사용합니다.

이 서버는 Model Context Protocol을 통해 Airtable에 대한 포괄적인 통합 기능을 제공하여, 사용자의 Airtable 데이터와 자연어 상호작용을 가능하게 합니다. 여기에는 모든 Airtable PAT 범위(scope)를 다루는 42개의 도구와 지능형 분석을 위한 10개의 AI 프롬프트 템플릿이 포함되어 있습니다.

전체 CRUD 작업— 필터링 및 페이지네이션 기능을 갖춘 레코드 생성, 읽기, 업데이트, 삭제 기능
레코드 댓글— 레코드에 대한 댓글 목록 조회, 생성, 업데이트, 삭제 기능
스키마 관리— 테이블, 필드, 뷰를 프로그래밍 방식으로 생성 및 수정하는 기능
배치 작업— 성능 향상을 위해 한 번의 작업으로 최대 10개의 레코드를 처리하는 기능
웹훅 관리— 데이터 변경에 대한 실시간 알림을 설정하는 기능
거버넌스 및 규정 준수— 허용 목록 거버넌스(allow-list governance), PII 마스킹, 예외 추적 기능을 제공합니다.
사용자 식별— whoami 도구를 사용하여 토큰 신원을 확인합니다.
AI 분석— 예측 분석, 자연어 질의 및 자동화된 통찰력을 위한 10개 프롬프트 템플릿
다중 베이스 지원— 여러 베이스를 동적으로 검색하고 작업할 수 있습니다.
타입 안정성— 포괄적인 타입 정의와 함께 전체 TypeScript 지원을 제공합니다.

MCP 2026-07-28 사양과 v2 TypeScript SDK(@modelcontextprotocol/server) 기반으로 구축되었습니다:

무상태 코어(Stateless core)— 모든 요청은 공유 팩토리에서 새로 생성된 서버 인스턴스로 처리됩니다. 세션이나 고정 라우팅이 없습니다. HTTP 모드에서는 어떤 요청이든 어떤 복제본에 도달할 수 있으므로, 이 서버는 서버리스 및 수평 확장 환경에 깔끔하게 배포될 수 있습니다.
두 시대 모두 지원(Both eras served)— 최신 2026-07-28 클라이언트(요청별 엔벨로프)와 레거시 2025년 클라이언트(initialize 핸드셰이크)가 동일한 팩토리에 의해 처리됩니다. stdio를 통한 연결별 시대 고정(per-connection era pinning)과 HTTP를 통한 요청별 무상태 폴백이 제공됩니다.
전송 계층(Transports)— 로컬 클라이언트(Claude Desktop/Code 등)를 위한 stdio(serveStdio)와, PORT/MCP_HTTP_PORT가 설정된 경우 스트리밍 가능한 HTTP(createMcpHandler + Node adapter)를 지원하며, /health 엔드포인트를 제공합니다.

오케스트레이터용 엔드포인트입니다. Tasks 확장은 의도적으로 구현되지 않았습니다. 2026년 7월 28일 사양에서 Tasks를 핵심 기능에서 io.modelcontextprotocol/tasks 확장으로 이동시켰으며, 이 서버가 노출하는 모든 작업은 서브초(sub-second) Airtable API 호출입니다 (배치는 최대 10개 레코드로 제한). 따라서 백그라운드 작업 의미론(background-task semantics)은 아무것도 추가하지 않습니다. 장시간 실행되는 도구가 추가되면 이 부분은 재검토될 것입니다.

• Node.js 20 이상 버전 (MCP v2 SDK에서 필수)
• 개인 액세스 토큰이 있는 Airtable 계정
• 사용자의 Airtable Base ID (선택 사항 — list_bases 도구를 통해 확인할 수 있음)

airtable.com/create/tokens에서 개인 액세스 토큰을 생성하고 다음 스코프를 설정하세요:

설정 후, 자연어(natural language)를 사용하여 Airtable 데이터와 상호 작용할 수 있습니다:

• "접근 가능한 모든 Airtable 베이스 목록을 보여줘"

• "Projects 테이블의 모든 레코드를 보여줘"

• "우선순위 'High' 및 마감일 내일인 새 작업을 생성해줘"

• "작업 ID rec123의 상태를 'Completed'로 업데이트해줘"

• "상태가 'Active'인 레코드를 검색해줘"

• "이 베이스의 전체 스키마를 보여줘"

• "Name, Priority, Due Date 필드가 있는 'Tasks'라는 새 테이블을 생성해줘"

• "Projects 테이블에 Status 필드를 추가해줘"

• "레코드 rec123에 대한 모든 댓글을 보여줘"

• "이 레코드에 댓글 추가: '검토 및 승인됨'"

• "내 댓글을 '수정 필요'로 업데이트해줘"

• "Tasks 테이블에 새 레코드를 한 번에 5개 생성해줘"

• "여러 레코드를 새로운 상태 값으로 업데이트해줘"

• "이 3개 레코드를 한 작업으로 삭제해줘"

• "내 베이스의 모든 활성 웹훅을 목록화해줘"

• "Projects 테이블 변경에 대한 웹훅을 생성해줘

고급 분석을 위한 10가지 AI 프롬프트 템플릿:

{
"mcpServers": {
"airtable": {
...

| Variable | Required | Description |
|---|---|---|
`AIRTABLE_TOKEN` | Yes | Personal Access Token |
`AIRTABLE_BASE_ID` | No | Default base ID (discoverable via `list_bases` ) |
`AIRTABLE_TOOLSET` | No | Which tools to register: `full` (default, all 42), `core` (18 record-centric tools — fits Cursor's 40-tool cap), or a comma-separated allowlist of tool names |
`LOG_LEVEL` | No | Logging level (default: `info` ) |
`MCP_HTTP_PORT` | No | Enable HTTP transport for hosted deployments |

사용자에게는 필수가 아닙니다. 서버에 기여하거나 수정하려면 리포지토리를 복제(Clone)하세요. 최종 사용자는 위 빠른 시작 섹션에서 보여주듯이 `npx`를 사용해야 합니다.

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

npm run test:types # 타입 검사 (Type checking)
npm test # 테스트 스위트 실행 (Run test suite)

airtable-mcp/
├── src/typescript/ # TypeScript 구현체
│ ├── app/
...

**연결 문제 (Connection Issues)**

- MCP 서버가 실행 중인지 확인하세요.
- MCP 클라이언트를 재시작하세요.
- 토큰에 필요한 스코프(scopes)가 포함되어 있는지 확인하세요.

**유효하지 않은 토큰 (Invalid Token)**

- Personal Access Token이 정확한지 확인하세요.
- 토큰에 필요한 스코프가 포함되어 있는지 확인하세요.
- 자격 증명(credentials)에 추가 공백이 없는지 확인하세요.

**베이스를 찾을 수 없음 (Base Not Found)**