에어테이블 MCP → SDK 스킬 전환 가이드

에어테이블 MCP의 한계(삭제 불가, 토큰 비효율)를 해결하는 airtable-sdk 스킬로 전환합니다.

왜 바꾸나요?

요약: 더 적은 토큰, 더 많은 기능, 더 안전.

Claude Code에서:

에어테이블 MCP 삭제해줘

또는 터미널에서 직접:

# MCP 설정 파일 열기
code ~/.claude/mcp.json
# → airtable 관련 항목 삭제

airtable-sdk는 Bun이라는 도구가 필요합니다.

Claude Code에게:

Bun 설치해줘

또는 터미널에서:

curl -fsSL https://bun.sh/install | bash

💡 Bun이 뭔가요? Node.js 같은 자바스크립트 실행 환경인데 더 빠릅니다. 몰라도 됩니다 — 그냥 설치만 하면 끝!

Claude Code에게:

https://github.com/daht-mad/airtable-sdk 이 스킬을 전역으로 설치해줘

또는 터미널에서:

cd ~/.claude/skills
git clone https://github.com/daht-mad/airtable-sdk.git
cd airtable-sdk
bun install

Airtable 토큰 발급 페이지 접속
Create new token 클릭
이름: 아무거나 (예: claude-code)
Scopes (권한) 설정 — 아래 4개 체크:
- ✅ data.records:read — 레코드 읽기
- ✅ data.records:write — 레코드 생성/수정/삭제
- ✅ schema.bases:read — 스키마 조회
- ✅ schema.bases:write — 필드/테이블 생성
Access — 사용할 베이스 선택 (또는 All current and future bases)
Create token 클릭 → 토큰 복사!

⚠️ 토큰은 pat으로 시작합니다. 한 번만 보여주니까 꼭 복사하세요!

Claude Code에게:

내 홈 디렉토리의 .zshrc 파일에 AIRTABLE_API_KEY 환경변수 추가해줘.
값은 patXXXXXXXX... (아까 복사한 토큰)

또는 직접:

# ~/.zshrc 맨 아래에 추가
echo 'export AIRTABLE_API_KEY="patXXXXXXXX..."' >> ~/.zshrc

# 적용
source ~/.zshrc

에어테이블 URL에서 Base ID를 확인합니다:

https://airtable.com/appXXXXXXXXXXXXXXX/tblYYYYY/...
                      ↑ 이게 Base ID

환경변수로 설정:

echo 'export AIRTABLE_BASE_ID="appXXXXXXXXXXXXXXX"' >> ~/.zshrc
source ~/.zshrc

이 단계가 airtable-sdk의 핵심! 내 에어테이블의 테이블/필드 구조를 캐싱합니다.

cd ~/.claude/skills/airtable-sdk/scripts
bun run sync-schema.ts

💡 이렇게 하면 Claude가 내 에어테이블의 테이블 이름, 필드 이름, 필드 타입을 정확히 알게 됩니다. MCP처럼 매번 로딩하지 않아서 토큰이 절약되는 거예요!

Claude Code에서:

내 에어테이블에서 [테이블이름] 테이블의 데이터 5개만 보여줘

결과가 나오면 성공! 🎉

설치가 끝나면, 그냥 평소처럼 Claude에게 말하면 됩니다:

"Users 테이블에서 활성 상태인 사람 조회해줘"
"새 레코드 만들어줘 - 이름: 홍길동"
"recXXX 레코드 삭제해줘"          ← MCP에서는 안 되던 것!
"새 필드 추가해줘 - 등급(선택)"

증상	해결
”AIRTABLE_API_KEY가 없어요”	`echo $AIRTABLE_API_KEY`로 확인, 없으면 Step 5 다시
”스키마 동기화 에러”	토큰 권한에 `schema.bases:read` 있는지 확인
”필드명이 안 맞아요”	`bun run sync-schema.ts` 다시 실행
”Bun이 없어요”	Step 2 실행

💡 막히면 카톡방에 질문해주세요! 스크린샷과 함께 올려주시면 더 빠르게 도와드릴 수 있어요.