Supabase MCP vs supabase CLI — AI가 DB를 직접 다루면 무엇이 달라지나
32개 MCP Tool vs 20+ CLI 명령어 — 로컬 개발 스택부터 프로덕션 DB 관리까지, 어느 쪽이 더 나은지 시나리오로 비교한다.
이 글을 쓰게 된 이유 지난번 Supabase MCP 설치 및 활용 가이드를 작성하면서, Supabase가 제공하는 또 다른 공식 도구인 supabase CLI와의 경계가 궁금해졌다. MCP는 AI 에이전트로 원격 DB를 조작하는 도구고, CLI는 로컬 개발 환경과 마이그레이션 파이프라인을 담당한다. 둘은 겹치는 기능도 있지만 역할이 충분히 다르다. 구체적으로 어디서 겹치고 어디서 갈라지는지, 시나리오별로 어느 쪽을 선택해야 하는지 정리해봤다.
안녕하세요! 갓대희입니다.
오늘은 Supabase MCP와 supabase CLI를 직접 비교해보려고 한다. "AI 기반 DB 관리는 MCP, 로컬 개발과 마이그레이션 파이프라인은 CLI" — 이 프레임이 실제로 맞는지 검증해보자.
한눈에 보는 결론
AI 기반 DB 설계/쿼리: MCP 우위 → LLM이 스키마를 읽고 SQL을 작성하여 apply_migration까지 자동 처리
로컬 개발 환경: CLI만 가능 → supabase start로 Docker 기반 전체 스택(DB, Auth, Storage, Realtime, Studio) 구동
TypeScript 타입 생성: 양쪽 모두 가능 → MCP generate_typescript_types / CLI supabase gen types --lang typescript
claude mcp add --transport http supabase https://mcp.supabase.com/mcp
brew install supabase/tap/supabase 또는 npm i -g supabase
인증
OAuth (브라우저) 또는 PAT
supabase login (브라우저) 또는 --token
호출 방식
MCP 프로토콜을 통해 Tool 호출 (자연어)
supabase [command] (Bash)
호환 환경
Claude Code, Claude Desktop, Cursor, Windsurf
터미널 (Claude Code에서 Bash로 실행 가능)
주요 역할
AI 에이전트 기반 DB 관리, 스키마 설계, 쿼리
로컬 개발 환경, 마이그레이션, CI/CD 파이프라인
supabase CLI는 Supabase 프로젝트의 로컬 개발부터 프로덕션 배포까지 전체 라이프사이클을 관리하는 도구이다. supabase start 한 줄이면 Docker로 PostgreSQL, Auth, Storage, Realtime, Studio까지 로컬에서 전부 띄울 수 있다.
반면 Supabase MCP는 AI 에이전트가 원격 Supabase 프로젝트에 직접 접근하여 SQL을 실행하고, 스키마를 변경하고, 프로젝트를 관리하는 데 초점을 맞춘다. 32개 Tool을 8개 그룹으로 제공하며, DDL/DML을 분리하여 안전한 스키마 관리가 가능하다.
주의: supabase CLI ≠ Supabase JS Client supabase CLI는 프로젝트 관리/개발용 도구이고, @supabase/supabase-js는 앱에서 Supabase API를 호출하는 클라이언트 라이브러리다. 이 글에서 비교하는 CLI는 전자를 의미한다.
MCP 프로토콜 기초 MCP(Model Context Protocol)는 LLM이 외부 서비스와 상호작용하는 표준 프로토콜이다. Supabase MCP는 HTTP Remote MCP(Server-Sent Events 기반) 방식으로 동작하며, LLM이 Tool을 호출하면 결과가 context window에 직접 삽입된다. MCP 프로토콜 구조(JSON-RPC 2.0, 3대 Primitive, Tool Schema, Transport)에 대한 상세 설명은 Playwright MCP vs CLI 편에서 자세히 다루고 있으니 참고하자.
여기서 잠깐 supabase mcp는 이전글에서 설치했는데 supabase cli 도 설치해보겠다.
AI에게 단순히 설치 요청해도 설치 가능하다.
ex) brew install supabase/tap/supabase
supabase --version
2.75.0
A new version of Supabase CLI is available: v2.78.1 (currently installed v2.75.0)
We recommend updating regularly for new features and bug fixes: https://supabase.com/docs/guides/cli/getting-started#updating-the-supabase-cli
ex) supabase login
- 상기 터미널에 하기 웹 화면에서 복사한 인증 코드를 입력해 주자.
- 인증완료 되었다.
2. 한눈에 보는 전체 비교표
30개 이상의 기능 항목을 직접 비교했다. 우위 컬럼의 색상 배지를 기준으로 빠르게 판단할 수 있다.
기능
Supabase MCP
supabase CLI
우위
기본 설정
설치 방법
claude mcp add (원클릭)
brew install 또는 npm -g
동등
인증 방식
OAuth / PAT
supabase login / --token
동등
도구 수
32개 Tool (8개 그룹)
20+ 명령어
동등
Claude Desktop 호환
✔ 지원
✘ 미지원
MCP
Read-only 모드
✔ ?read_only=true URL 파라미터
✘ 없음
MCP
데이터베이스 쿼리 / 실행
SQL 실행 (DML)
execute_sql
psql 또는 supabase 대시보드
MCP
테이블 목록 조회
list_tables
psql \dt 또는 대시보드
MCP
확장 목록 조회
list_extensions
psql \dx
MCP
AI가 SQL 자동 작성
✔ LLM이 스키마 읽고 SQL 생성
✘ 수동 SQL 작성
MCP
스키마 & 마이그레이션
마이그레이션 적용 (DDL)
apply_migration
supabase db push
동등
마이그레이션 이력 조회
list_migrations
supabase migration list
동등
스키마 차이 감지 (diff)
✘ 없음
supabase db diff
CLI
마이그레이션 압축 (squash)
✘ 없음
supabase migration squash
CLI
DDL/DML 분리 관리
✔ apply_migration vs execute_sql
✘ 수동으로 구분
MCP
DB 테스트 (pgTAP)
✘ 없음
supabase test db
CLI
DB 린트
✘ 없음 (get_advisors와 다름)
supabase db lint
CLI
로컬 개발 환경
로컬 전체 스택 구동
✘ 없음 (CLI 로컬 MCP는 제한적)
supabase start (Docker)
CLI
로컬 Studio (GUI)
✘ 없음
✔ localhost:54323
CLI
원격 프로젝트 링크
project_ref URL 파라미터
supabase link
동등
DB 성능 분석 (inspect)
✘ 없음
supabase inspect db (bloat, locks, outliers 등 13개 서브커맨드)
CLI
Edge Functions
Edge Function 목록
list_edge_functions
supabase functions list
동등
Edge Function 배포
deploy_edge_function
supabase functions deploy
동등
Edge Function 로컬 실행
✘ 없음
supabase functions serve
CLI
타입 생성 & 코드 연동
TypeScript 타입 생성
generate_typescript_types
supabase gen types --lang typescript
동등
프로젝트 URL 조회
get_project_url
supabase status
동등
API 키 조회
get_publishable_keys
supabase status (로컬) / supabase projects api-keys (원격)
// LLM이 자동으로 생성하는 SQL: SELECT date_trunc('day', event_at)::dateAS day, count(*) AS total_count, count(*) FILTER (WHERE event_type = 'PRICE_SPIKE') AS price_spike, count(*) FILTER (WHERE event_type = 'NEW_DISCLOSURE') AS new_disclosure FROM public.alert_events WHERE event_at >= now() - interval'7 days' GROUP BY day ORDER BY day;
ex)
CLI에서는 동일한 작업을 하려면 직접 SQL을 작성하고 psql이나 Supabase 대시보드에서 실행해야 한다. Claude Code에서 Bash로 psql을 호출할 수 있지만, 연결 문자열 설정이 필요하고 MCP만큼 매끄럽지 않다.
토큰 효율성 주의 Supabase MCP는 HTTP Remote MCP로 동작하므로 execute_sql 결과 전체가 LLM의 context window에 포함된다. 수백~수천 행을 반환하는 쿼리를 반복적으로 실행하면 토큰 소모가 급격히 증가해 비용 부담으로 이어질 수 있다.
권장 패턴:
조회 시 항상 LIMIT을 명시한다. 예: SELECT ... LIMIT 20
전체 행 대신 집계 쿼리(COUNT, AVG, SUM)를 활용한다.
대량 데이터 분석이 필요할 때는 MCP 대신 CLI + psql을 사용한다.
3.2 스키마 변경 & 마이그레이션
MCP는 DDL/DML 분리를 권장한다. 스키마 변경은 apply_migration을 통해 마이그레이션 이력에 자동 기록되며, 일반 쿼리는 execute_sql을 사용하도록 LLM에 안내한다. ?read_only=true URL 파라미터를 설정하면 execute_sql이 읽기 전용 Postgres 사용자로 실행되어 쓰기 작업이 차단되고, apply_migration, create_project, deploy_edge_function 등 모든 변경 도구가 비활성화된다.
# CLI 방식: 마이그레이션 파일 생성 → 로컬 테스트 → 원격 적용 supabase migration new add_user_profile
# supabase/migrations/TIMESTAMP_add_user_profile.sql 편집 supabase db reset # 로컬에서 마이그레이션 테스트 supabase db push # 원격 DB에 적용
CLI는 마이그레이션 파일을 로컬에 생성하고, db reset으로 로컬에서 검증한 뒤 db push로 원격에 적용하는 워크플로우다. db diff로 원격/로컬 간 스키마 차이를 감지하고, migration squash로 여러 마이그레이션을 하나로 합칠 수도 있다. 이런 파이프라인 기능은 CLI에서만 가능하다.
3.3 로컬 개발 환경
CLI만의 영역이다. supabase start 하나로 Docker 컨테이너들이 올라오면서 로컬에 완전한 Supabase 스택이 구성된다.
PostgreSQL (localhost:54322)
API 엔드포인트 (localhost:54321) — Auth, Storage, Realtime, REST 통합
Storage (localhost:54321)
Realtime (localhost:54321)
Studio (localhost:54323) — 브라우저 기반 GUI
Mailpit (localhost:54324) — 이메일 테스트
MCP는 기본적으로 원격 Supabase 프로젝트에 연결된다. CLI로 로컬 Supabase를 구동한 경우 http://localhost:54321/mcp로 로컬 MCP 서버에 접근할 수 있지만, 제한된 도구만 제공되며 OAuth 2.1 인증은 지원되지 않는다. 오프라인 환경이나 전체 로컬 개발 스택이 필요한 경우 CLI가 핵심 도구다.
3.4 보안 & 어드바이저
MCP의 get_advisors는 프로젝트에 대한 보안 및 성능 관련 어드바이저 알림(advisory notices)을 제공한다. LLM이 이를 활용하여 보안 취약점이나 성능 이슈를 확인할 수 있다.
// MCP 방식: 자연어로 보안 점검 요청 "현재 DB의 보안 취약점을 점검해줘"
// LLM이 get_advisors 호출 → 결과 분석 → execute_sql로 확인 // → 수정 SQL 생성 → apply_migration으로 적용 // 전체 과정이 하나의 대화 흐름에서 자동 처리
CLI의 db lint는 Postgres 린트 규칙을 적용하지만, MCP의 get_advisors가 제공하는 보안/성능 분석과는 다른 영역이다. 두 가지를 함께 활용하면 더 포괄적인 점검이 가능하다.
3.5 타입 생성 & 문서 검색
supabase gen types --lang typescript는 DB 스키마에서 TypeScript 타입을 자동 생성하는 CLI 명령어다. MCP에도 generate_typescript_types Tool이 있어 동일한 기능을 제공한다. CLI는 파일로 직접 저장하기 편하고 CI/CD 자동화에 적합하며, MCP는 LLM이 생성된 타입을 바로 코드에 활용하는 워크플로우에 적합하다.
반대로 search_docs는 MCP 전용 기능이다. LLM이 Supabase 공식 문서를 검색하여 올바른 API 사용법을 참조할 수 있다. 이는 할루시네이션을 줄이는 데 효과적이다.
미사용 인덱스는 쓰기 성능을 떨어뜨리면서 공간만 차지한다. 이런 건 주기적으로 inspect로 확인하고 정리해주는 게 좋다.
정리하면 MCP는 AI가 스키마를 읽고 SQL을 생성하거나 보안을 점검하는 작업에 적합하다. CLI는 로컬 환경 구동, 마이그레이션 파이프라인, pgTAP 테스트처럼 스크립트로 반복할 수 있는 작업에 맞는다.
7. 선택 가이드 & 결론
언제 MCP를 쓸까?
새로운 테이블/스키마를 설계할 때 (AI가 기존 스키마를 이해하고 제안)
복잡한 SQL을 자연어로 요청하고 싶을 때
DB 보안/성능 점검이 필요할 때 (get_advisors)
로그를 분석하고 싶을 때 (get_logs)
Claude Desktop에서 DB를 관리하고 싶을 때
프로덕션 DB를 read_only 모드로 안전하게 조회할 때
언제 CLI를 쓸까?
로컬 개발 환경을 구성할 때 (supabase start)
마이그레이션 파이프라인을 관리할 때 (diff, squash, push)
TypeScript 타입을 생성할 때
pgTAP 테스트를 실행할 때
Edge Function을 로컬에서 개발/테스트할 때
CI/CD에서 자동 배포할 때
DB 성능을 상세 분석할 때 (inspect)
매트릭스
- 계속 업데이트가 되면 달라지겠지만 현재로서는 이런 식의 조합이 될 것 같다.
작업 유형
추천 도구
이유
스키마 설계/변경
MCP
AI가 기존 스키마를 이해하고 SQL 자동 생성
데이터 조회/분석
MCP
자연어로 복잡한 쿼리 요청 가능
로컬 개발 환경
CLI
Docker 기반 전체 스택 구동
마이그레이션 관리
CLI
diff, squash, test 등 파이프라인 기능
보안 점검
MCP
get_advisors + execute_sql 조합
CI/CD 배포
CLI
비대화형 자동화에 적합
타입 생성
동등
양쪽 모두 가능 (CLI: gen types / MCP: generate_typescript_types)
로그 분석
MCP
API/Postgres/Edge Functions/Auth/Storage/Realtime 로그 통합 조회
CLI 사용 시 주의사항 및 트러블슈팅
CLI를 처음 쓸 때 빠지기 쉬운 함정들이다. 실제로 이 글 작성하면서 겪은 것들을 정리했다.
supabase login — non-TTY 환경에서 실패 Claude Code 내부 Bash에서 supabase login을 실행하면 interactive TTY가 아니라서 브라우저 로그인이 안 된다:
Cannot use automatic login flow inside non-TTY environments. Please provide --token flag or set the SUPABASE_ACCESS_TOKEN environment variable.
해결: 별도 터미널에서 supabase login을 실행하거나, SUPABASE_ACCESS_TOKEN 환경 변수를 설정한다.
supabase inspect db — --project-ref 플래그 미지원 inspect 명령어는 linked 프로젝트에서만 동작한다. --project-ref를 직접 넘기면 unknown flag 에러가 난다. 해결: 먼저 supabase init → supabase link --project-ref <ref> 후 inspect를 실행한다.
table-sizes deprecated → table-stats 사용 supabase inspect db table-sizes는 deprecated 되었다. table-stats로 변경해서 사용하자. 기존 스크립트나 블로그에서 table-sizes로 안내하는 경우가 아직 많으니 주의.
macOS에서 psql 미설치 CLI 일부 기능이나 직접 DB 접속 시 psql이 필요한데 macOS에 기본 설치되어 있지 않다. 해결:brew install libpq 후 export PATH="/opt/homebrew/opt/libpq/bin:$PATH"를 ~/.zshrc에 추가한다.
결론: CLI로 로컬 스택 띄우고, MCP로 스키마 설계/쿼리
MCP와 CLI는 잘하는 게 다르다. MCP는 대화 흐름 안에서 스키마를 설계하고 보안을 점검하는 데 쓰고, CLI는 로컬 환경과 CI/CD처럼 자동화가 필요한 곳에 쓰면 된다. 둘 다 쓰는 게 맞다.
CLI로 supabase start → 로컬 개발 → MCP로 원격 DB 스키마 설계/점검 → CLI로 db push 배포
