Supabase MCP

Supabase MCP 서버

Supabase 프로젝트를 Cursor, Claude, Windsurf 및 기타 AI 어시스턴트에 연결하세요.

MCP(Model Context Protocol)는 LLM(Large Language Model)이 Supabase와 같은 외부 서비스와 통신하는 방식을 표준화합니다. AI 어시스턴트를 Supabase 프로젝트에 직접 연결하여 테이블 관리, 구성 가져오기, 데이터 쿼리 등의 작업을 수행할 수 있게 합니다. 전체 도구 목록을 참조하세요.

설정
1. 보안 모범 사례를 따르세요
MCP 서버를 설정하기 전에, LLM을 Supabase 프로젝트에 연결할 때의 위험과 이를 완화하는 방법을 이해하기 위해 보안 모범 사례를 읽어보실 것을 권장합니다.

2. MCP 클라이언트 구성
클라이언트에서 Supabase MCP 서버를 구성하려면 설정 문서를 방문하세요. Supabase 대시보드의 MCP 연결 탭을 방문하여 프로젝트에 대한 사용자 지정 MCP URL을 생성할 수도 있습니다.

MCP 클라이언트는 설정 중에 자동으로 Supabase 로그인을 요청합니다. 작업하려는 프로젝트가 포함된 조직을 선택해야 합니다.

대부분의 MCP 클라이언트는 다음 정보를 필요로 합니다:

{
"mcpServers" : {
"supabase" : {
"type" : " http " ,
"url" : " https://mcp.supabase.com/mcp "
}
}
}
문서에 나열되지 않은 MCP 클라이언트를 사용하는 경우, 해당 클라이언트의 MCP 문서를 확인하고 위의 MCP 정보를 클라이언트가 요구하는 형식(json, yaml 등)으로 복사하세요.

CLI
Supabase CLI로 Supabase를 로컬에서 실행하는 경우, http://localhost:54321/mcp 에서 MCP 서버에 접근할 수 있습니다. 현재 CLI 환경의 MCP 서버는 제한된 도구 하위 집합을 제공하며 OAuth 2.1을 지원하지 않습니다.

셀프 호스팅
셀프 호스팅 Supabase의 경우, MCP 서버 활성화 페이지를 확인하세요. 현재 셀프 호스팅 환경의 MCP 서버는 제한된 도구 하위 집합을 제공하며 OAuth 2.1을 지원하지 않습니다.

구성 옵션 및 도구
사용 가능한 도구와 구성 옵션의 전체 목록은 Supabase MCP 서버 문서를 참조하세요.

문서에는 구성 옵션을 채워주는 대화형 URL 빌더도 있습니다.

AI SDK의 MCP 클라이언트와 함께 사용하기
@supabase/mcp-server-supabase 패키지는 Vercel AI SDK의 MCP 클라이언트에 대한 입력 및 출력 스키마를 채우기 위해 createToolSchemas()를 내보냅니다. 이를 통해 Supabase MCP 도구를 클라이언트 측 유효성 검사와 입력 및 출력에 대한 추론된 TypeScript 타입을 갖춘 정적 도구로 취급할 수 있습니다.

import { createToolSchemas } from '@supabase/mcp-server-supabase' ;
import { createMCPClient } from '@ai-sdk/mcp' ;
import { streamText } from 'ai' ;

const mcpClient = await createMCPClient ( {
transport : {
type : 'http' ,
url : 'https://mcp.supabase.com/mcp' ,
} ,
} ) ;

const tools = await mcpClient . tools ( {
schemas : createToolSchemas ( ) ,
} ) ;

const result = streamText ( { model , tools , prompt : '...' } ) ;

for ( const step of await result . steps ) {
for ( const toolResult of step . staticToolResults ) {
if ( toolResult . toolName === 'get_project_url' ) {
toolResult . input ; // { project_id: string }
toolResult . output ; // { url: string }
}
}
}
createToolSchemas()는 MCP 서버의 URL 매개변수와 유사한 필터링 옵션을 허용합니다:

features : 특정 기능 그룹으로 제한합니다(예: ['database', 'docs'] ). 기본값은 모든 기본 기능 그룹입니다.
projectScoped : true 인 경우, 도구 입력 스키마에서 project_id를 생략하고 계정 수준 도구를 제외합니다. project_ref로 구성된 서버에 연결할 때 사용하세요. 기본값은 false 입니다.
readOnly : true 인 경우, 변경 도구를 제외합니다. read_only=true로 구성된 서버에 연결할 때 사용하세요. 기본값은 false 입니다.

const mcpClient = await createMCPClient ( {
transport : {
type : 'http' ,
url : 'https://mcp.supabase.com/mcp?project_ref=<project-ref>&read_only=true&features=database,docs' ,
} ,
} ) ;

const tools = await mcpClient . tools ( {
schemas : createToolSchemas ( {
features : [ 'database' , 'docs' ] ,
projectScoped : true ,
readOnly : true ,
} ) ,
} ) ;
참고

이 서버는 MCP 도구 결과에 structuredContent를 전송하지 않습니다. AI SDK는 content 텍스트에서 JSON을 파싱하는 것으로 대체합니다.

자세한 내용은 AI SDK 문서의 Schema Definition and Typed Tool Outputs를 참조하세요.

MCP 엔드포인트 셀프 호스팅
@supabase/mcp-server-supabase 패키지는 자체 엔드포인트에서 HTTP를 통해 도구를 제공하기 위해 createSupabaseMcpHandler()를 내보냅니다. 이는 createSupabaseMcpServer()와 동일한 SupabaseMcpServerOptions를 허용하며, 가장 중요한 것은 platform 입니다.

이 핸들러는 현재 프로토콜 개정판만 지원합니다. legacy: 'reject'로 생성되므로, 2025년대 프로토콜만 지원하는 클라이언트는 서비스되는 대신 HTTP 400을 받습니다.

platform이 요청별 자격 증명을 포함하는 경우, 요청마다 핸들러를 생성하고 응답이 완료되면 닫으세요. 핸들러는 제공한 platform을 클로저로 캡처하므로, 공유 핸들러는 모든 요청을 해당 platform으로 처리합니다.

platform이 공유되도록 의도된 경우(예: 서비스 계정 토큰)에는 장기 실행 핸들러가 적합합니다. 응답마다가 아니라 한 번 생성하고 종료 시 close()를 호출하세요. close()는 구독 라우터를 해제하고 이후 요청을 거부하기 때문입니다.

import { createServer } from 'node:http' ;
import { toNodeHandler } from '@modelcontextprotocol/node' ;
import { createSupabaseMcpHandler } from '@supabase/mcp-server-supabase' ;
import { createSupabaseApiPlatform } from '@supabase/mcp-server-supabase/platform/api' ;

const server = createServer ( ( req , res ) => {
const accessToken = getAccessTokenFromRequest ( req ) ; // your own auth

const handler = createSupabaseMcpHandler ( {
platform : createSupabaseApiPlatform ( { accessToken } ) ,
} ) ;

// `close()` aborts in-flight exchanges, so close on `res` finishing rather
// than when the handler resolves, which would cut streaming responses short.
res . on ( 'close' , ( ) => {
handler . close ( ) . catch ( ( error ) => console . error ( error ) ) ;
} ) ;

toNodeHandler ( handler ) ( req , res ) . catch ( ( error ) => console . error ( error ) ) ;
} ) ;
toNodeHandler는 @modelcontextprotocol/node에서 제공됩니다. 코드에서 직접 가져오므로 함께 설치하세요.

관찰 가능성
createSupabaseMcpServer에 observer를 전달하여 요청 수명 주기 결과와 Supabase의 내장 사실을 수집합니다. 여기서 platform은 기존 platform 어댑터입니다:

import { createSupabaseMcpServer } from '@supabase/mcp-server-supabase' ;

const server = createSupabaseMcpServer ( {
platform ,
observer : ( context ) => ( {
record ( fact ) {
console . info ( fact ) ;
} ,
end ( result ) {
console . info ( { ... context , ... result } ) ;
} ,
} ) ,
} ) ;
서버는 요청 또는 응답 페이로드를 observer에 자동으로 전달하지 않습니다. Supabase의 내장 사실은 제한된 필드와 값의 닫힌 집합을 사용합니다. 사용자 지정 사실은 자동 개인정보 검증을 받지 않습니다. observer를 생략하면 모든 관찰 작업을 건너뜁니다. observer, classifier 및 sink 실패는 요청 동작을 변경하지 않지만, 동기 observer 및 classifier 작업은 요청을 차단할 수 있습니다.

기타 MCP 서버
@supabase/mcp-server-postgrest
PostgREST MCP 서버를 사용하면 REST API를 통해 자체 사용자를 앱에 연결할 수 있습니다. 자세한 내용은 프로젝트 README를 참조하세요.

리소스

Model Context Protocol : MCP와 그 기능에 대해 자세히 알아보세요.
개발에서 프로덕션까지 : 변경 사항을 프로덕션 환경으로 안전하게 승격하는 방법을 알아보세요.

개발자를 위해
이 프로젝트에 기여하는 방법에 대한 자세한 내용은 CONTRIBUTING을 참조하세요.

라이선스
이 프로젝트는 Apache 2.0에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.