Supabase MCP 설정하기 — Claude Code에서 Supabase 직접 제어

Supabase MCP를 연결하면 Claude Code에서 테이블 생성, RLS 정책 설정, 데이터 조회를 대화로 할 수 있어요.

MCP가 뭔가요?

MCP(Model Context Protocol)는 LLM이 외부 서비스와 통신하기 위한 표준 프로토콜이에요. Supabase MCP를 연결하면 Claude Code가 Supabase 프로젝트에 접근해서 DB 관리, 쿼리 실행 등을 할 수 있어요.

사전 준비

• Supabase 계정과 프로젝트 (없다면 supabase.com에서 만들어요)
• Claude Code 설치

1단계: Project Reference 확인

1. Supabase Dashboard에서 프로젝트를 골라요.
2. Settings > General로 이동해요.
3. Reference ID를 복사해요 (예: abcdefghijklmnop).

URL에 project_ref를 붙이면 MCP 서버가 그 프로젝트 하나에만 접근해요.

2단계: Claude Code에 MCP 서버 등록

방법 A: OAuth 로그인 (Supabase 문서의 기본 방법)

claude mcp add --scope project --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=<YOUR_PROJECT_REF>"

--scope project로 등록하면 프로젝트 루트의 .mcp.json에 저장돼요. 그다음 Claude Code에서 /mcp를 열고 supabase 서버를 골라 인증하면, 브라우저가 열리고 Supabase 계정으로 로그인해서 접근을 허용하면 돼요. 이 방법은 토큰을 따로 만들 필요가 없어요.

방법 B: Personal Access Token 헤더 (CI 등 브라우저 로그인이 안 되는 환경)

1. Supabase Access Tokens 페이지에서 Generate new token을 눌러요.
2. 용도가 드러나는 이름을 붙여요 (예: claude-code-mcp). 연결할 프로젝트로 범위를 좁히고, 필요한 권한만 줘요.
3. 생성된 토큰을 바로 복사해서 안전한 곳에 저장해요. 다시 볼 수 없어요.

claude mcp add --transport http supabase \
  "https://mcp.supabase.com/mcp?project_ref=<YOUR_PROJECT_REF>" \
  --header "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

설정 파일로 넣으려면 프로젝트 루트의 .mcp.json에 추가해요. 토큰을 파일에 직접 쓰지 말고 환경변수로 넘기는 게 안전해요.

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

주의: 토큰은 외부에 노출하지 마세요. .mcp.json은 저장소에 커밋되는 파일이라, 토큰 값을 그대로 쓰면 함께 공개돼요.

3단계: 연결 확인

Claude Code를 실행하고 이렇게 물어봐요.

데이터베이스에 어떤 테이블이 있어?

Supabase 프로젝트의 테이블 목록이 나오면 연결된 거예요. claude mcp get supabase로도 연결 상태를 확인할 수 있어요.

read_only 모드

Supabase 문서는 프로덕션 프로젝트에 연결할 때 범위를 좁히라고 권해요. URL에 read_only=true를 붙이면 모든 쿼리가 읽기 전용 Postgres 사용자로 실행돼요.

https://mcp.supabase.com/mcp?project_ref=<YOUR_PROJECT_REF>&read_only=true

features=database,docs처럼 쓸 도구 묶음을 제한할 수도 있어요.

정리

이제 Claude Code에서 "테이블 만들어줘", "RLS 정책 설정해줘" 같은 요청을 할 수 있어요.

참고 문서:

• Supabase MCP 공식 문서
• Claude Code MCP 문서
• Supabase Access Tokens