Supabase MCP Server
- 추천0
- GitHub 별3K
- 데이터베이스원격 연결라이선스Apache-2.0
Supabase 프로젝트를 AI 어시스턴트에 연결해 테이블 관리 · 설정 조회 · 데이터 질의를 맡겨요(원격 HTTP · CLI · 셀프 호스팅). Apache-2.0
원본:supabase/mcp
연결 · 설치 방법은 설치 탭에 정리했어요.
설명
Supabase MCP Server
이 글은 저장소 README(영어)를 한국어로 옮긴 것이에요. 원문: github.com/supabase/mcp
Supabase 프로젝트를 Cursor, Claude, Windsurf 같은 AI 어시스턴트에 연결하세요.
모델 컨텍스트 프로토콜(MCP)은 대규모 언어 모델(LLM)이 Supabase 같은 외부 서비스와 대화하는 방식을 표준으로 정해 둔 것입니다. AI 어시스턴트를 Supabase 프로젝트에 직접 연결해, 테이블 관리, 설정 가져오기, 데이터 질의 같은 작업을 시킬 수 있습니다. 전체 도구 목록을 확인하세요.
설정
1. 보안 모범 사례를 따르세요
MCP 서버를 설정하기 전에 보안 모범 사례를 읽어 보시기 바랍니다. LLM을 Supabase 프로젝트에 연결할 때의 위험과 그것을 줄이는 방법을 알 수 있습니다.
2. MCP 클라이언트 설정하기
사용하는 클라이언트에 Supabase MCP 서버를 설정하려면 설정 문서를 보세요. Supabase 대시보드의 MCP 연결 탭에서 프로젝트 전용 MCP 주소를 만들 수도 있습니다.
설정하는 동안 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 서버 문서를 보세요.
이 문서에는 설정 옵션을 대신 채워 주는 대화형 주소 만들기 도구도 있습니다.
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 서버의 주소 매개변수와 비슷한 걸러내기 옵션을 받습니다.
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 문서의 스키마 정의와 타입이 있는 도구 출력을 보세요.
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); // 내 인증 방식
const handler = createSupabaseMcpHandler({
platform: createSupabaseApiPlatform({ accessToken }),
});
// `close()`는 진행 중인 교환을 중단하므로, 핸들러가 결과를 돌려준 때가 아니라
// `res`가 끝났을 때 닫으세요. 그렇지 않으면 스트리밍 응답이 중간에 끊깁니다.
res.on('close', () => {
handler.close().catch((error) => console.error(error));
});
toNodeHandler(handler)(req, res).catch((error) => console.error(error));
});
toNodeHandler는 @modelcontextprotocol/node에서 옵니다. 코드가 이것을 직접 가져오므로 함께 설치하세요.
관측(Observability)
createSupabaseMcpServer에 observer를 넘기면 요청 수명주기 결과와 Supabase의 기본 제공 사실(fact)을 모을 수 있습니다. 여기서 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 · 분류기 · 싱크의 실패는 요청 동작을 바꾸지 않지만, observer나 분류기의 동기 작업은 요청을 막을 수 있습니다.
다른 MCP 서버
@supabase/mcp-server-postgrest
PostgREST MCP 서버를 쓰면 내 사용자를 REST API로 내 앱에 연결할 수 있습니다. 자세한 내용은 프로젝트 README를 보세요.
자료
- 모델 컨텍스트 프로토콜: MCP와 그 기능에 대해 더 알아보세요.
- 개발에서 운영까지: 변경 사항을 운영 환경에 안전하게 올리는 방법을 알아보세요.
개발자를 위해
이 프로젝트에 기여하는 방법은 CONTRIBUTING을 보세요.
라이선스
이 프로젝트는 Apache 2.0 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 보세요.