본문으로 건너뛰기
MCP 서버 전체 목록

Supabase MCP Server

Supabase 프로젝트를 AI 에이전트에 연결하는 MCP 서버. 데이터베이스 · 마이그레이션 · 함수 관리를 맡겨요. Apache-2.0

원본:supabase-community/supabase-mcp

연결 · 설치 방법은 설치 탭에 정리했어요.

설명

Supabase MCP Server

MCP Registry Version

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

supabase-mcp-demo

Model Context Protocol(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 서버 문서를 보세요.

문서에는 설정 옵션을 대신 채워 주는 대화형 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 문서의 스키마 정의와 타입이 있는 도구 출력을 보세요.

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에서 가져옵니다. 코드가 이것을 직접 가져오므로 함께 설치하세요.

관측(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 });
    },
  }),
});

서버는 요청이나 응답 페이로드를 관찰자에게 자동으로 넘기지 않습니다. Supabase의 내장 사실은 닫힌 집합의 제한된 필드와 값을 쓰고, 사용자 정의 사실에는 자동 개인정보 검증이 없습니다. observer를 생략하면 모든 관측 작업을 건너뜁니다. 관찰자 · 분류기 · 싱크의 실패는 요청 동작을 바꾸지 않지만, 동기식 관찰자 · 분류기 작업은 요청을 막을 수 있습니다.

다른 MCP 서버

@supabase/mcp-server-postgrest

PostgREST MCP 서버는 앱의 사용자를 REST API로 앱에 연결하게 해 줍니다. 자세한 내용은 프로젝트 README를 보세요.

자료

개발자를 위한 안내

기여 방법은 CONTRIBUTING을 보세요.

라이선스

이 프로젝트는 Apache 2.0 라이선스로 배포됩니다. 자세한 조항은 LICENSE 파일을 보세요.


저장소: supabase-community/supabase-mcp