Supabase MCP

npx add-mcp 'https://mcp.supabase.com/mcp'

Supabase MCP 서버

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

Model Context Protocol(MCP)은 대규모 언어 모델(LLM)이 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,
  }),
});

[!NOTE] 이 서버는 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이 공유되도록 의도된 경우(예: 서비스 계정 토큰) 장기 실행 핸들러가 적합합니다. 응답별로 생성하는 대신 한 번 생성하고 종료 시 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에서 제공됩니다. 코드에서 직접 가져오므로 함께 설치하세요.

관찰 가능성

observer을 createSupabaseMcpServer에 전달하여 요청 수명 주기 결과와 Supabase의 내장 팩트를 수집하세요. 여기서 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를 참조하세요.

리소스

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

개발자용

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

라이선스

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