Supabase MCP Server — Claude Code MCP 서버

Supabase 프로젝트(PostgreSQL DB, 테이블, 마이그레이션, 로그)를 자연어로 조회·관리하는 공식 MCP 서버. SQL 실행과 스키마 탐색을 지원한다.

Supabase MCP Server는 Claude Code 같은 AI 어시스턴트를 Supabase 프로젝트에 연결해, PostgreSQL 데이터베이스와 프로젝트 설정을 자연어로 조회·관리하게 해주는 Supabase 측 공식(커뮤니티 관리) MCP 서버입니다. AI가 SQL을 직접 실행하고 스키마를 탐색할 수 있어, "테이블 목록 보여줘", "이 쿼리 돌려줘", "스키마에서 TypeScript 타입 생성해줘" 같은 요청을 별도 콘솔 전환 없이 대화 안에서 처리할 수 있습니다.

핵심 기능은 크게 나뉩니다. 데이터베이스 영역에서는 테이블·확장(extension) 조회, SQL 쿼리 및 마이그레이션 실행, 스키마 기반 TypeScript 타입 생성을 지원합니다. 프로젝트 관리 영역에서는 프로젝트 목록·생성·일시정지, 조직·비용 조회, 프로젝트 URL/API 키 접근이 가능합니다. 개발 지원으로는 Edge Functions 배포·관리, 로그·어드바이저(advisor) 점검을 통한 디버깅을 돕고, 유료 플랜에서는 개발 브랜치 생성·머지(branching), 선택적으로 스토리지 버킷 관리도 제공합니다. Supabase 공식 문서 검색 도구도 포함돼 작업 중 레퍼런스 확인이 쉽습니다.

동작 범위는 설정으로 제어합니다. read-only 모드는 읽기 전용 Postgres 사용자로 SQL을 실행해 변경성(mutating) 도구를 비활성화하고, 프로젝트 스코프(project_ref)는 특정 프로젝트로 접근을 한정합니다. 기능 그룹(feature groups)으로 database/functions/storage/branching 등 도구 카테고리를 켜고 끌 수 있어 최소 권한 구성을 만들기 좋습니다.

Supabase로 백엔드를 운영하며 스키마 작업, 데이터 점검, 마이그레이션, 로그 디버깅을 AI와 함께 빠르게 반복하려는 개발자에게 적합합니다. 다만 프로덕션 데이터에 직접 붙이는 용도로는 권장되지 않으므로, 정확한 옵션과 최신 도구 목록은 공식 문서 확인을 권장합니다.

언제 쓰나

Supabase를 백엔드로 쓰면서 Claude Code 안에서 테이블·스키마를 탐색하거나, 임시 SQL 조회·집계, 마이그레이션 작성·적용, 로그/어드바이저 기반 디버깅, 스키마→TypeScript 타입 생성을 반복할 때 유용합니다. 콘솔과 에디터를 오가지 않고 대화로 DB 작업을 진행하고 싶을 때, 특히 개발/스테이징 프로젝트에서 효율이 큽니다. 운영 데이터 직접 조작에는 권장되지 않습니다.

설치

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase@latest --access-token $SUPABASE_ACCESS_TOKEN

설치 전 Supabase에서 개인 액세스 토큰(SUPABASE_ACCESS_TOKEN)을 발급해 환경변수로 준비해야 합니다. Node.js와 npx 실행 환경이 필요합니다(서버를 npx로 받아 구동). 모든 프로젝트에 광범위하게 붙이기보다 read-only 모드와 프로젝트 스코프(project_ref), 기능 그룹 제한을 함께 적용해 최소 권한으로 구성하는 것을 권장합니다. 정확한 플래그와 최신 옵션은 공식 문서 확인을 권장합니다.

필요 키(직접 발급, 플레이스홀더): SUPABASE_ACCESS_TOKEN

보안 주의

SUPABASE_ACCESS_TOKEN은 토큰 소유자 권한으로 프로젝트·DB·API 키·비용 정보에 접근하므로 사실상 광범위한 자격증명입니다. 출력·커밋·로그 노출을 금하고 환경변수/시크릿으로만 관리하세요. read-only 모드와 프로젝트 스코프로 권한 범위를 좁히는 것이 안전합니다. 변경성 도구는 데이터 삭제·스키마 변경·프로젝트 생성 등 파괴적·과금성 작업이 가능하니 실행 전 도구 호출을 직접 검토하세요. DB에 저장된 신뢰할 수 없는 데이터가 프롬프트 인젝션으로 LLM을 유도할 수 있어, 공식 권고대로 프로덕션 데이터가 아닌 개발 프로젝트 사용을 권장합니다.

자주 묻는 질문

read-only 모드는 무엇을 막아주나요?

읽기 전용 Postgres 사용자로 SQL을 실행해 INSERT/UPDATE/DELETE나 마이그레이션 같은 변경성 도구를 비활성화합니다. 데이터 조회·디버깅 위주 작업에서 실수로 인한 변경을 차단하는 기본 안전장치로 권장됩니다.

프로덕션 DB에 바로 연결해도 되나요?

공식적으로는 권장되지 않습니다. 토큰 권한이 넓고 프롬프트 인젝션 위험이 있어, 프로덕션이 아닌 개발/스테이징 프로젝트에 연결하고 read-only·프로젝트 스코프·기능 그룹으로 범위를 좁히는 것이 안전합니다.

특정 프로젝트로만 접근을 제한할 수 있나요?

네. 프로젝트 스코프(project_ref)로 한 프로젝트에만 접근하도록 한정할 수 있고, 기능 그룹으로 database/functions/storage/branching 등 도구 카테고리를 선택적으로 켜고 끌 수 있습니다. 자세한 설정은 공식 문서 확인을 권장합니다.