본문으로 건너뛰기

Claude Code에서 Supabase MCP 연동

Claude Code(CLI)에서 Supabase MCP 서버를 연결하면, 자연어로 데이터베이스를 조작하고 프로젝트를 관리할 수 있습니다.

Supabase MCP란?​

MCP(Model Context Protocol) 는 AI 어시스턴트가 외부 서비스에 접근할 수 있게 해주는 표준 프로토콜입니다. Supabase는 공식 MCP 서버를 제공하며, Claude Code와 연결하면 다음과 같은 작업을 자연어로 수행할 수 있습니다.

기능예시
SQL 실행"posts 테이블에서 최근 10개 글 조회해줘"
테이블 관리"users 테이블 만들어줘"
마이그레이션"created_at 컬럼 추가하는 마이그레이션 적용해줘"
TypeScript 타입 생성"현재 DB 스키마로 타입 생성해줘"
Edge Function 배포"이 함수를 Edge Function으로 배포해줘"
프로젝트 관리"내 Supabase 프로젝트 목록 보여줘"

사전 준비​

  • Supabase 계정 및 프로젝트 생성 완료 (Supabase 소개 참고)
  • Claude Code 설치 완료
  • Node.js >= 20.0

연동 방법​

방법 A: Remote MCP (권장)​

Supabase가 호스팅하는 원격 MCP 서버에 연결하는 방식입니다. 별도 설치 없이 바로 사용할 수 있습니다.

claude mcp add --transport http supabase https://mcp.supabase.com/mcp

실행하면 브라우저가 자동으로 열리며 Supabase OAuth 로그인 화면이 표시됩니다. 로그인하면 연동이 완료됩니다.

:::tip PAT(Personal Access Token) 불필요 Remote MCP는 OAuth 2.1 방식으로 인증하므로 별도의 토큰을 생성할 필요가 없습니다. :::

방법 B: npx 로컬 실행​

MCP 서버를 로컬에서 직접 실행하는 방식입니다.

claude mcp add supabase -- npx -y @supabase/mcp-server-supabase@latest

특정 프로젝트에만 적용하려면 -s project 옵션을 추가합니다.

claude mcp add -s project supabase -- npx -y @supabase/mcp-server-supabase@latest

방법 C: 로컬 개발 환경 (Supabase CLI)​

Supabase CLI로 로컬 인스턴스를 실행 중인 경우:

claude mcp add --transport http supabase http://localhost:54321/mcp

설정 파일로 직접 추가​

CLI 대신 설정 파일에 직접 추가할 수도 있습니다.

프로젝트 레벨 (.mcp.json):

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

글로벌 레벨 (~/.claude.json):

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp"
    }
  }
}

연결 확인​

Claude Code를 실행한 후 아래와 같이 테스트합니다.

> 내 Supabase 프로젝트 목록 보여줘

프로젝트 목록이 표시되면 연동이 정상적으로 완료된 것입니다.

주요 도구(Tools)​

MCP 연결 시 Claude가 사용할 수 있는 도구 목록입니다.

프로젝트 관리​

도구기능
list_projects프로젝트 목록 조회
get_project프로젝트 상세 정보
create_project새 프로젝트 생성
pause_project프로젝트 일시 중지
restore_project중지된 프로젝트 복원

데이터베이스​

도구기능
execute_sqlSQL 직접 실행
list_tables테이블 목록 조회
list_extensionsPostgreSQL 확장 목록
apply_migration마이그레이션 적용
list_migrations마이그레이션 내역 조회

개발 도구​

도구기능
generate_typescript_typesDB 스키마 기반 TypeScript 타입 자동 생성
get_publishable_keysAPI 키(anon key 등) 조회
get_project_url프로젝트 URL 조회

Edge Functions​

도구기능
list_edge_functionsEdge Function 목록
get_edge_function함수 상세 정보
deploy_edge_function함수 배포

디버깅​

도구기능
get_logs서비스 로그 조회
get_advisors성능/보안 권고사항 확인
search_docsSupabase 공식 문서 검색

보안 설정​

읽기 전용 모드​

프로덕션 데이터베이스에 연결할 때는 반드시 읽기 전용 모드를 사용하세요.

claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?read_only=true"

특정 프로젝트만 접근 허용​

여러 프로젝트가 있을 때 특정 프로젝트로 접근을 제한할 수 있습니다.

claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF"

파라미터 조합​

읽기 전용 + 특정 프로젝트 제한을 동시에 적용할 수 있습니다.

claude mcp add --transport http supabase "https://mcp.supabase.com/mcp?read_only=true&project_ref=YOUR_PROJECT_REF"
파라미터설명
read_only=true읽기 전용 (INSERT/UPDATE/DELETE 차단)
project_ref=<id>특정 프로젝트에만 접근

CI/헤드리스 환경 (PAT 사용)​

브라우저 인증이 불가능한 환경에서는 Personal Access Token을 사용합니다.

{
  "mcpServers": {
    "supabase": {
      "type": "http",
      "url": "https://mcp.supabase.com/mcp?project_ref=YOUR_PROJECT_REF",
      "headers": {
        "Authorization": "Bearer YOUR_SUPABASE_ACCESS_TOKEN"
      }
    }
  }
}

사용 예시​

테이블 생성​

> posts 테이블을 만들어줘. id, title, content, created_at 컬럼이 필요하고 RLS도 활성화해줘

Claude가 SQL을 생성하고 execute_sql 도구로 직접 실행합니다.

TypeScript 타입 생성​

> 현재 DB 스키마 기반으로 TypeScript 타입 생성해줘

generate_typescript_types 도구가 실행되어 타입 정의를 생성합니다.

데이터 조회​

> users 테이블에서 최근 가입한 10명 보여줘

Claude가 적절한 SQL을 작성하여 결과를 보여줍니다.

로그 확인​

> 최근 Edge Function 에러 로그 보여줘

get_logs 도구로 서비스 로그를 조회합니다.

주의사항​

:::danger 프로덕션 데이터베이스 주의

  • MCP 서버는 개발/테스트 환경 전용으로 설계되었습니다.
  • 프로덕션 DB에 연결할 때는 반드시 ?read_only=true 파라미터를 추가하세요.
  • Claude가 예상치 못한 INSERT/UPDATE/DELETE를 실행할 수 있으므로 주의하세요. :::

:::tip MCP 서버 제거 연동을 해제하려면 아래 명령어를 실행합니다.

claude mcp remove supabase

:::

참고 자료​