Claude Code와 Supabase MCP: 30분 설정으로 스키마 설명 불필요

Cosoado Lab Blog에 동시 게재 예정: https://cosoado-lab.com/blog/mcp-supabase-claude-code/

매번 "이 users 테이블의 스키마는 이렇습니다..."라고 붙여넣곤 했다. SparMate, NetaPair, BoardLink 이렇게 3개의 Supabase 프로젝트를 가지고 있어서, Claude Code에게 마이그레이션(migration)을 작성하게 할 때마다 테이블 정의를 복사해야 했다. 지난주에는 정말 귀찮아져서 Supabase의 MCP 서버를 연결했다.

MCP (Model Context Protocol)는 Claude 같은 LLM이 외부 도구나 데이터에 연결하기 위한 프로토콜이다. Supabase는 supabase-community/supabase-mcp라는 공식 MCP 서버를 제공하며, 이를 연결하면 Claude가 프로젝트의 DB 스키마를 직접 참조할 수 있다.

내가 '연동 서버'를 만드는 것이 아니다. Supabase 측에서 호스팅하는 서버에 Claude Code만 연결해 주면 된다.

프로젝트 루트에 .mcp.json 파일을 만든다.

{
"mcpServers": {
"supabase": {
...

저장하고 Claude Code를 재시작하면, 처음 한 번만 "Supabase에 로그인하시겠습니까?"라는 프롬프트가 뜬다. 브라우저가 열리고 OAuth 인증을 완료하면 끝이다.

CLI에서 할 경우에는 다음 명령어를 사용한다:

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

claude mcp list로 연결 상태를 확인할 수 있다.

설정 직후, SparMate의 마이그레이션을 요청했더니 Claude의 출력에 "NetaPair의 matches 테이블은..."이라는 내용이 섞여 나왔다.

URL에 파라미터를 추가하지 않았기 때문이다. https://mcp.supabase.com/mcp 상태로는 계정 내 모든 프로젝트에 접근할 수 있는 상태가 된다.

{
"mcpServers": {
"supabase": {
...

project_ref는 대시보드 URL에서 가져올 수 있다 (https://supabase.com/dashboard/project/<여기에값>). 또한, read_only=true도 반드시 추가해야 한다. 마이그레이션 생성 용도로만 사용한다면 쓰기 권한은 필요하지 않으며, 만약 Claude가 오작동하더라도 DB는 변경되지 않는다.

프로젝트별로 .mcp.json을 따로 관리하는 것이 올바른 방법이었다. '30분이면 끝날 줄 알았는데'라 생각했던 것이 원인 조사만으로 1시간이 걸렸다.

[이전]
나:": 이 posts 테이블의 스키마입니다: (150줄 분량의 테이블 정의를 붙여넣음)"
Claude: "알겠습니다. 마이그레이션은 이렇게 합니다"
...

이제 Claude가 스키마 획득 도구를 호출하여 확인한 후에 마이그레이션을 작성한다. 테이블 수가 늘어날수록 차이가 크다. SparMate는 14개의 테이블이 있었고, 전부 붙여넣는 것이 지루했다.

외부 키 관계가 얽힌 변경이나 여러 테이블을 넘나드는 RLS(Row Level Security) 정책을 작성할 때도, 스키마 전체를 파악한 상태에서 제안해 준다.

.mcp.json에 3줄만 작성하고 재시작하면 Supabase MCP에 연결된다 -
(반드시 범위를 제한해야 한다) project_ref를 지정하지 않으면 모든 프로젝트가 보일 수 있다 -
read_only=true도 함께 설정하는 것이 좋다 - 프로젝트별로 .mcp.json을 분리하여 리포지토리 관리하는 것이 개인적인 베스트 프랙티스이다 - 테이블 수가 많을수록, 스키마 설명을 생략하는 효과가 크다