Claude Code용 Supabase MCP 읽기 전용 1개 프로젝트 설정

Claude Code에게 Supabase 데이터베이스에 대한 쿼리를 작성하라고 하면, 코드의 변수명에서 컬럼명을 추측하고, 실제로는 owner_id인데 user_id라고 가정하며, 이미 실행한 마이그레이션과 충돌하는 마이그레이션을 만들어 냅니다. 스키마를 볼 수 없기 때문에 결국 테이블 정의를 채팅에 붙여넣게 됩니다.

Supabase MCP는 Supabase의 공식 서버입니다. Claude Code가 테이블을 나열하고, SQL을 실행하고, 로그를 읽고, 보안 어드바이저를 확인하고, 실제 데이터베이스에서 바로 TypeScript 타입을 생성할 수 있게 해줍니다. 이 서버는 호스팅되어 있고, OAuth로 로그인하며, 이 가이드는 Supabase가 권장하는 시작 방식인 읽기 전용이고 기본적으로 하나의 프로젝트에만 범위를 제한한 설정으로 구성합니다.

다른 옵션과 비교 중이신가요? database and backend MCP roundup에서 대안들을 다룹니다.

빠른 시작

프로젝트 폴더에서 아래를 실행하되, 자리표시자 대신 프로젝트 ref를 넣으세요:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"

Claude Code를 시작하고 /mcp를 실행한 다음, supabase를 선택하고 브라우저에서 접근을 승인하세요. 총 소요 시간은 약 2분입니다. 생성하거나 붙여넣을 토큰은 없습니다.

⚡ 이 프롬프트를 복사하세요: Claude Code가 직접 설치하고 확인하게 하기

아래의 수동 단계를 건너뛰고, 대신 에이전트에게 전체 작업을 맡기세요:

12345678910You have shell access and the `claude mcp` CLI on this machine. Connect the Supabase MCP server to Claude Code for this project in read-only mode and report back. Do not tell me it's done unless step 4 actually confirms it:

1. Run `claude mcp list`. If a supabase entry already exists, show me its URL and stop instead of adding a second one.
2. Ask me for my project ref (Project Settings > General in the Supabase dashboard, or the part before .supabase.co in my project URL). Then run:
   `claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"`
   with the placeholder replaced.
3. Tell me to run `/mcp` in Claude Code, pick supabase, and finish the Supabase sign-in in my browser, choosing the organization that owns this project. Wait until I say it's done, then run `claude mcp list` and confirm supabase shows Connected.
4. Call `list_tables` and summarize the tables in the public schema with their row counts. Don't run any other SQL yet.

Never ask me to paste an access token or database password into this chat. If any step fails, give me the exact error and the command that produced it. Do not skip ahead.

마지막 단계는 테이블 이름만 읽으므로, 단일 쿼리를 실행하기 전에 Claude가 무엇을 보는지 확인할 수 있습니다.

필요한 것

단계별 설정

에이전트에 맡기지 않고 직접 하고 싶으신가요? 수동 버전은 다음과 같습니다.

1단계 — URL 만들기

약 30초

호스팅된 서버는 https://mcp.supabase.com/mcp에서 쿼리 매개변수로 세 가지 옵션을 받습니다:

Supabase 대시보드에도 URL 빌더가 있습니다: 프로젝트를 열고 Connect를 클릭한 다음 MCP 탭을 여세요.

2단계 — 서버 추가하기

약 30초

--scope project는 항목을 저장소의 .mcp.json에 기록하므로, 이 프로젝트에만 적용되고 팀원들도 같은 설정을 사용하게 됩니다:

claude mcp add --scope project --transport http supabase "https://mcp.supabase.com/mcp?project_ref=<your-project-ref>&read_only=true"

따옴표는 그대로 유지하세요. 그렇지 않으면 셸이 &를 “백그라운드에서 실행”으로 처리해 URL 뒤쪽을 잘라버립니다.

실제 실행 예시, 2026년 10월, 자리표시자 프로젝트 ref 사용(1단계에서 자신의 것을 사용하세요). 확인 줄에서는 쿼리 문자열이 빠지지만 .mcp.json에는 read_only=true가 유지되므로, 메시지가 아니라 파일을 확인하세요. 승인 대기 중은 프로젝트 범위 서버에서는 정상입니다. claude를 시작하고 승인한 뒤, /mcp로 로그인하세요.

3단계 — OAuth로 로그인하기

약 1분

Claude Code 안에서 /mcp를 실행하고 supabase를 선택한 다음 Authenticate를 고르세요. 브라우저에서 프로젝트를 소유한 조직을 선택한 뒤 승인합니다. Claude Code가 토큰을 저장하므로 한 번만 하면 됩니다.

읽기 전용이고 하나의 프로젝트로 범위가 제한되어 있으므로, Claude Code는 데이터베이스를 볼 수는 있지만 변경할 수는 없습니다.

각 구성 요소의 역할

read_only=true로 설정하면, 변경을 수행하는 도구(apply_migration, deploy_edge_function, 브랜치 변경)는 아예 사용할 수 없습니다.

실제로 작동하는지 확인하기

claude mcp list

✔ supabase https://mcp.supabase.com/mcp?project_ref=… (HTTP) – 연결됨

! supabase 인증이 필요합니다 → /mcp를 실행하고 로그인하세요(3단계)

✘ supabase 연결 실패 → URL이 따옴표로 감싸져 있는지, 전송 방식이 http인지 확인하세요

그다음 라이브 데이터베이스만 아는 것을 물어보세요:

List the tables in my public schema, then generate TypeScript types for them and tell me which tables have Row Level Security disabled.

Claude가 list_tables, generate_typescript_types, get_advisors를 호출했고 답이 대시보드와 일치한다면, 정상적으로 작동하는 것입니다.

흔히 저지르는 실수

• 처음부터 프로덕션에 연결하는 것. Supabase의 권장사항은 개발 프로젝트나 개발 브랜치에 연결하고, 프로덕션 데이터가 정말 필요한 작업일 때만 프로덕션을 사용하는 것입니다.

• 읽기 전용이면 RLS가 적용된다고 생각하는 것. 읽기 전용 모드는 Row Level Security를 무시하고, 모든 데이터를 읽을 수 있는 역할로 쿼리합니다. 쓰기만 막을 뿐 읽기는 막지 않습니다. 데이터베이스 안의 모든 내용이 모델에 보입니다.

• 모든 도구 호출을 자동 승인하는 것. 테이블 행에는 사용자가 작성한 텍스트가 들어갈 수 있고, LLM은 그 텍스트 안에 숨겨진 지시에 속을 수 있습니다. Supabase는 SQL 결과를 경고와 함께 감싸지만, execute_sql에 대해서는 수동 승인을 유지하세요. Claude Code hook으로 이를 강제할 수 있습니다.

• 로그인할 때 잘못된 조직을 선택하는 것. 서버는 승인한 조직만 볼 수 있습니다. list_tables에서 프로젝트가 존재하지 않는다고 나오면 /mcp를 다시 실행하고 올바른 조직을 선택하세요.

• URL을 따옴표로 감싸지 않는 것. 매개변수 사이의 &가 bash와 zsh에서 명령을 분리하므로, read_only=true가 조용히 설정에 들어가지 못합니다.

Q&A

무료인가요?

네. MCP 서버는 추가 비용이 들지 않습니다. Supabase 프로젝트 비용만 평소처럼 지불하면 됩니다. 프로젝트나 브랜치를 생성하는 도구는 비용을 추가할 수 있으며, Claude는 먼저 그 비용에 대해 확인해야 합니다.

쓰기, 마이그레이션 실행, 함수 배포를 허용하려면 어떻게 하나요?

URL에서 read_only=true를 제거하세요(claude mcp remove supabase를 실행한 뒤 다시 추가). 프로덕션이 아니라 개발 브랜치에서 하세요.

로컬 Supabase와도 작동하나요?

네. Supabase CLI가 실행 중이면 서버는 http://localhost:54321/mcp에 있습니다. 도구 수가 더 적고 OAuth 로그인은 없습니다.

브라우저 로그인 없이 CI에서 사용할 수 있나요?

네. Supabase 대시보드에서 개인 액세스 토큰을 만들고 이를 Authorization: Bearer 헤더로 전달하세요. 저장소가 아니라 환경 변수에 보관하세요.

어떻게 제거하나요?

claude mcp remove supabase --scope project.

공식 자료

• Supabase MCP 문서 — 클라이언트별 설정, 옵션, 보안

• GitHub의 supabase/mcp — 소스와 변경 로그

• Supabase 브랜칭 — 에이전트가 대상으로 삼을 수 있는 데이터베이스의 안전한 복사본

• Claude Code MCP 문서 — claude mcp add, 범위, /mcp를 통한 OAuth

원문은 quickpromptco.com에 처음 게시되었으며, 이 가이드는 그곳에서 계속 최신 상태로 유지됩니다.

출처

• 원문: https://dev.to/juholee/supabase-mcp-for-claude-code-a-read-only-one-project-setup-in-2-minutes-3ha (2026-10-19 · quickpromptco)