Supabase MCP

Supabase MCP 서버

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

모델 컨텍스트 프로토콜(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은 제공하지 않습니다.

옵션

다음 옵션은 URL 쿼리 매개변수로 구성할 수 있습니다.

• read_only: 서버를 읽기 전용 쿼리 및 도구로 제한하는 데 사용됩니다. 기본적으로 권장됩니다. 읽기 전용 모드를 참조하세요.
• project_ref: 서버를 특정 프로젝트로 범위를 지정하는 데 사용됩니다. 기본적으로 권장됩니다. 이 옵션을 생략하면 서버가 Supabase 계정의 모든 프로젝트에 액세스할 수 있습니다. 프로젝트 범위 모드를 참조하세요.
• features: 활성화할 도구 그룹을 지정하는 데 사용됩니다. 기능 그룹을 참조하세요.

대시보드 또는 문서에서 URL을 사용하면 이러한 매개변수가 자동으로 채워집니다.

프로젝트 범위 모드

프로젝트 범위를 지정하지 않으면 MCP 서버가 Supabase 조직의 모든 프로젝트에 액세스할 수 있습니다. 서버 URL에 project_ref 쿼리 매개변수를 설정하여 서버를 특정 프로젝트로 제한하는 것이 좋습니다.

https://mcp.supabase.com/mcp?project_ref=<project-ref>

<project-ref>을 프로젝트 ID로 바꾸세요. Supabase 프로젝트 설정의 프로젝트 ID에서 찾을 수 있습니다.

서버를 프로젝트로 범위 지정한 후에는 list_projects 및 list_organizations과 같은 계정 수준 도구를 더 이상 사용할 수 없습니다. 서버는 지정된 프로젝트와 해당 리소스에만 액세스할 수 있습니다.

읽기 전용 모드

Supabase MCP 서버를 읽기 전용 쿼리로 제한하려면 서버 URL에 read_only 쿼리 매개변수를 설정하세요.

https://mcp.supabase.com/mcp?read_only=true

이 설정을 기본적으로 활성화하는 것이 좋습니다. 이렇게 하면 읽기 전용 Postgres 사용자(execute_sql를 통해)로 SQL을 실행하여 데이터베이스에 대한 쓰기 작업을 방지할 수 있습니다. 읽기 전용 모드에서는 다음을 포함한 다른 모든 변경 도구가 비활성화됩니다. apply_migration create_project pause_project restore_project deploy_edge_function create_branch delete_branch merge_branch reset_branch rebase_branch update_storage_config.

기능 그룹

MCP 서버에 features 쿼리 매개변수를 전달하여 특정 도구 그룹을 활성화하거나 비활성화할 수 있습니다. 이를 통해 LLM에서 사용할 수 있는 도구를 사용자 지정할 수 있습니다. 예를 들어 데이터베이스 및 문서 도구만 활성화하려면 서버 URL을 다음과 같이 지정합니다.

https://mcp.supabase.com/mcp?features=database,docs

사용 가능한 그룹: account, docs, database, debugging, development, functions, storage, branching.

이 매개변수가 설정되지 않은 경우 기본 기능 그룹은 account, database, debugging, development, docs, functions, branching입니다.

도구

참고: 이 서버는 1.0 이전 버전이므로 버전 간에 일부 주요 변경 사항이 있을 수 있습니다. LLM은 사용 가능한 도구에 자동으로 적응하므로 대부분의 사용자에게는 영향을 미치지 않습니다.

다음 Supabase 도구는 기능별로 그룹화되어 LLM에서 사용할 수 있습니다.

계정

project_ref이 설정되지 않은 경우 기본적으로 활성화됩니다. features 옵션과 함께 account을 사용하여 이 도구 그룹을 대상으로 지정하세요.

참고: 서버가 프로젝트로 범위 지정된 경우 이러한 도구를 사용할 수 없습니다.

• list_projects: 사용자의 모든 Supabase 프로젝트를 나열합니다.
• get_project: 프로젝트의 세부 정보를 가져옵니다.
• create_project: 새 Supabase 프로젝트를 만듭니다.
• pause_project: 프로젝트를 일시 중지합니다.
• restore_project: 프로젝트를 복원합니다.
• list_organizations: 사용자가 구성원인 모든 조직을 나열합니다.
• get_organization: 조직의 세부 정보를 가져옵니다.
• get_cost: 조직의 새 프로젝트 또는 브랜치 비용을 가져옵니다.
• confirm_cost: 새 프로젝트 또는 브랜치 비용에 대한 사용자의 이해를 확인합니다. 새 프로젝트 또는 브랜치를 만들려면 이 작업이 필요합니다.

지식 베이스

기본적으로 활성화됩니다. features 옵션과 함께 docs을 사용하여 이 도구 그룹을 대상으로 지정하세요.

• search_docs: 최신 정보를 위해 Supabase 문서를 검색합니다. LLM은 이를 사용하여 질문에 대한 답변을 찾거나 특정 기능을 사용하는 방법을 배울 수 있습니다.

데이터베이스

기본적으로 활성화됩니다. features 옵션과 함께 database를 사용하여 이 도구 그룹을 대상으로 지정하세요.

• list_tables: 지정된 스키마 내의 모든 테이블을 나열합니다.
• list_extensions: 데이터베이스의 모든 확장을 나열합니다.
• list_migrations: 데이터베이스의 모든 마이그레이션을 나열합니다.
• apply_migration: 데이터베이스에 SQL 마이그레이션을 적용합니다. 이 도구에 전달된 SQL은 데이터베이스 내에서 추적되므로 LLM은 DDL 작업(스키마 변경)에 사용해야 합니다.
• execute_sql: 데이터베이스에서 원시 SQL을 실행합니다. LLM은 스키마를 변경하지 않는 일반 쿼리에 사용해야 합니다.

디버깅

기본적으로 활성화됩니다. features 옵션과 함께 debugging을 사용하여 이 도구 그룹을 대상으로 지정하세요.

• get_logs: 서비스 유형(api, postgres, edge functions, auth, storage, realtime)별로 Supabase 프로젝트의 로그를 가져옵니다. LLM은 이를 사용하여 디버깅 및 서비스 성능 모니터링에 도움을 줄 수 있습니다.
• get_advisors: Supabase 프로젝트에 대한 권고 알림 목록을 가져옵니다. LLM은 이를 사용하여 보안 취약점 또는 성능 문제를 확인할 수 있습니다.

개발

기본적으로 활성화됩니다. features 옵션과 함께 development를 사용하여 이 도구 그룹을 대상으로 지정하세요.

• get_project_url: 프로젝트의 API URL을 가져옵니다.
• get_publishable_keys: 프로젝트의 익명 API 키를 가져옵니다. 레거시 anon 키와 최신 게시 가능 키를 포함한 클라이언트 안전 API 키 배열을 반환합니다. 새 애플리케이션에는 게시 가능 키가 권장됩니다.
• generate_typescript_types: 데이터베이스 스키마를 기반으로 TypeScript 유형을 생성합니다. LLM은 이를 파일에 저장하고 코드에서 사용할 수 있습니다.

Edge Functions

기본적으로 활성화됩니다. features 옵션과 함께 functions을 사용하여 이 도구 그룹을 대상으로 지정하세요.

• list_edge_functions: Supabase 프로젝트의 모든 Edge Functions를 나열합니다.
• get_edge_function: Supabase 프로젝트의 Edge Function에 대한 파일 내용을 검색합니다.
• deploy_edge_function: Supabase 프로젝트에 새 Edge Function을 배포합니다. LLM은 이를 사용하여 새 함수를 배포하거나 기존 함수를 업데이트할 수 있습니다.

분기 (실험적, 유료 플랜 필요)

기본적으로 활성화됩니다. features 옵션과 함께 branching를 사용하여 이 도구 그룹을 대상으로 지정하세요.

• create_branch: 프로덕션 브랜치의 마이그레이션을 사용하여 개발 브랜치를 만듭니다.
• list_branches: 모든 개발 브랜치를 나열합니다.
• delete_branch: 개발 브랜치를 삭제합니다.
• merge_branch: 개발 브랜치의 마이그레이션 및 Edge Functions를 프로덕션에 병합합니다.
• reset_branch: 개발 브랜치의 마이그레이션을 이전 버전으로 재설정합니다.
• rebase_branch: 마이그레이션 드리프트를 처리하기 위해 개발 브랜치를 프로덕션에 리베이스합니다.

스토리지

도구 수를 줄이기 위해 기본적으로 비활성화되어 있습니다. features 옵션과 함께 storage을 사용하여 이 도구 그룹을 대상으로 지정하세요.

• list_storage_buckets: Supabase 프로젝트의 모든 스토리지 버킷을 나열합니다.
• get_storage_config: Supabase 프로젝트의 스토리지 구성을 가져옵니다.
• update_storage_config: Supabase 프로젝트의 스토리지 구성을 업데이트합니다(유료 플랜 필요).

보안 위험

[!TIP] MCP 서버를 사용하기 전에 Supabase 문서에서 보안 위험 및 권장 완화 방법을 검토하세요.

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-postgrest

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

리소스

• 모델 컨텍스트 프로토콜: MCP 및 그 기능에 대해 자세히 알아보세요.
• 개발에서 프로덕션까지: 프로덕션 환경으로 변경 사항을 안전하게 승격하는 방법을 알아보세요.

개발자용

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

라이선스

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