Supabase MCP 서버

Cursor와 Windsurf가 Supabase 데이터베이스와 안전하게 상호 작용할 수 있도록 지원하는 풍부한 기능을 갖춘 MCP 서버입니다. 데이터베이스 관리, SQL 쿼리 실행, Supabase 관리 API 접근을 위한 도구를 제공하며, 내장된 안전 제어 기능도 갖추고 있습니다.

✨ 주요 특징

💻 stdio 프로토콜을 지원하는 Cursor, Windsurf, Cline 및 기타 MCP 클라이언트와 호환됩니다.
🔐 SQL 쿼리 실행의 읽기 전용 및 읽기-쓰기 모드를 제어합니다.
🔄 직접 및 풀링된 데이터베이스 연결 모두에 대한 강력한 트랜잭션 처리
💻 Supabase 관리 API를 사용하여 Supabase 프로젝트를 관리하세요
🧑‍💻 Python SDK를 통해 Supabase Auth Admin 메서드를 사용하여 사용자를 관리하세요
🔨 Cursor & Windsurf가 MCP와 더욱 효과적으로 작동하도록 돕는 사전 구축 도구
📦 패키지 관리자(uv, pipx 등)를 통한 매우 간단한 설치 및 설정

시작하기

필수 조건

서버를 설치하려면 시스템에 다음이 필요합니다.

파이썬 3.12+
포스트그레스SQL 16+

uv 를 통해 설치할 계획이라면, uv가 설치되어 있는지 확인하세요.

PostgreSQL 설치

⚠️ 중요 : psycopg2는 컴파일하는 동안 PostgreSQL 개발 라이브러리가 필요하므로 프로젝트 종속성을 설치하기 전에 PostgreSQL을 설치해야 합니다.

맥OS

지엑스피1

윈도우

https://www.postgresql.org/download/windows/ 에서 PostgreSQL 16+를 다운로드하고 설치하세요.
설치 중에 "PostgreSQL 서버" 및 "명령줄 도구"가 선택되었는지 확인하세요.

1단계. MCP 서버 설치

v0.2.0부터 패키지 설치 기능을 지원하게 되었습니다. 선호하는 Python 패키지 관리자를 사용하여 서버를 설치할 수 있습니다.

# if pipx is installed (recommended)
pipx install supabase-mcp-server

# if uv is installed
uv pip install supabase-mcp-server

pipx 각 패키지에 대해 격리된 환경을 생성하므로 권장됩니다.

저장소를 복제하고 루트 디렉토리에서 pipx install -editable .을 실행하여 서버를 수동으로 설치할 수도 있습니다.

⚠️ psycopg2 컴파일 문제가 발생하는 경우 PostgreSQL 개발 패키지가 누락되었을 수 있습니다. 위를 참조하세요.

소스에서 설치

예를 들어 로컬 개발을 위해 소스에서 설치하려는 경우:

uv venv
# On Mac
source .venv/bin/activate
# On Windows
.venv\Scripts\activate
# Install package in editable mode
uv pip install -e .

Smithery.ai를 통해 설치

아직 Smithery를 테스트하지 않았으므로 문제가 있으면 알려주시기 바랍니다.

Smithery를 통해 Claude Desktop에 Supabase MCP Server를 자동으로 설치하려면:

npx -y @smithery/cli install @alexander-zuev/supabase-mcp --client claude

2단계. 구성

패키지를 설치한 후에는 데이터베이스 연결 설정을 구성해야 합니다. 이 서버는 로컬 및 원격 Supabase 인스턴스를 모두 지원합니다.

로컬 Supabase 인스턴스(기본값)

서버는 기본 설정을 사용하여 로컬 Supabase 인스턴스에 연결하도록 미리 구성되어 있습니다.

Host : 127.0.0.1:54322
Password : postgres

💡 기본 설정을 수정하지 않고 로컬 인스턴스에 연결하려는 경우 환경 변수를 설정할 필요가 없습니다.

원격 Supabase 인스턴스

⚠️ 중요 경고 : 세션 풀링 연결은 지원되지 않으며, 아직 지원할 계획도 없습니다. MCP 서버에서 이 기능을 지원해야 할 사용 사례가 있다고 생각되시면 알려주세요.

원격 Supabase 프로젝트의 경우 다음을 구성해야 합니다.

SUPABASE_PROJECT_REF - 프로젝트 참조(프로젝트 URL에서 발견)
SUPABASE_DB_PASSWORD - 데이터베이스 비밀번호
SUPABASE_REGION - (선택 사항) 기본값은 us-east-1 입니다.
SUPABASE_ACCESS_TOKEN - (선택 사항) 관리 API 액세스용

프로젝트 대시보드 URL에서 SUPABASE_PROJECT_REF를 가져올 수 있습니다.

https://supabase.com/dashboard/project/<supabase-project-ref>

이 서버는 모든 Supabase 지역을 지원합니다.

us-west-1 - 미국 서부(북부 캘리포니아)
us-east-1 - 미국 동부(버지니아 북부) - 기본값
us-east-2 - 미국 동부(오하이오)
ca-central-1 - 캐나다(중부)
eu-west-1 - 서부 EU(아일랜드)
eu-west-2 - 서유럽(런던)
eu-west-3 - 서부 EU(파리)
eu-central-1 - 중앙 EU(프랑크푸르트)
eu-central-2 - 중부 유럽(취리히)
eu-north-1 - 북부 EU(스톡홀름)
ap-south-1 - 남아시아(뭄바이)
ap-southeast-1 - 동남아시아(싱가포르)
ap-northeast-1 - 동북아시아(도쿄)
ap-northeast-2 - 동북아시아(서울)
ap-southeast-2 - 오세아니아(시드니)
sa-east-1 - 남아메리카(상파울루)

Cursor와 Windsurf의 MCP 구성 방법은 서로 다릅니다. 연결 구성 방법을 이해하려면 관련 섹션을 참조하세요.

커서

v0.46부터 Cursor에서 MCP 서버를 구성하는 두 가지 방법이 있습니다.

프로젝트별 -> 프로젝트/저장소 폴더에 mcp.json 생성하고 .env 사용하여 연결을 구성합니다.
전역적으로 -> 설정에서 MCP 서버를 만들고 이 MCP 서버에서만 지원되는 .env 사용하여 구성합니다.

프로젝트별 MCP는 다음과 같은 방법으로 생성할 수 있습니다.

저장소에 .cursor 폴더가 없는 경우 생성
다음 설정으로 mcp.json 파일을 만들거나 업데이트합니다.

⚠ 환경 변수 : 프로젝트별로 MCP 서버를 구성하는 경우에도 연결 설정을 적용하려면 .env 파일을 만들어야 합니다. 환경 변수를 적용하도록 mcp.json을 설정할 수 없었습니다. 😔

{
	"mcpServers": {
	  "filesystem": {
		"command": "supabase-mcp-server",
	  }
	}
  }

또는 MCP 서버를 전역적으로 구성하려는 경우(즉, 각 프로젝트마다 구성하지 않는 경우), 다음 명령을 실행하여 글로벌 구성 폴더의 .env 파일을 업데이트하여 연결 설정을 구성할 수 있습니다.

# Create config directory and navigate to it
# On macOS/Linux
mkdir -p ~/.config/supabase-mcp
cd ~/.config/supabase-mcp

# On Windows (in PowerShell)
mkdir -Force "$env:APPDATA\supabase-mcp"
cd "$env:APPDATA\supabase-mcp"

이렇게 하면 환경 파일이 저장될 필수 구성 폴더가 생성됩니다.

# Create and edit .env file
# On macOS/Linux
nano ~/.config/supabase-mcp/.env

# On Windows (PowerShell)
notepad "$env:APPDATA\supabase-mcp\.env"

.env 파일이 열립니다. 파일이 열리면 다음을 복사하여 붙여넣으세요.

SUPABASE_PROJECT_REF=your-project-ref
SUPABASE_DB_PASSWORD=your-db-password
SUPABASE_REGION=us-east-1  # optional, defaults to us-east-1
SUPABASE_ACCESS_TOKEN=your-access-token  # optional, for management API

파일이 있는지 확인하세요. 방금 설정한 값이 표시되어야 합니다.

# On macOS/Linux
cat ~/.config/supabase-mcp/.env

# On Windows (PowerShell)
Get-Content "$env:APPDATA\supabase-mcp\.env"

글로벌 구성 파일은 다음에서 찾을 수 있습니다.

윈도우: %APPDATA%/supabase-mcp/.env
macOS/Linux: ~/.config/supabase-mcp/.env

윈드서핑

Windsurf는 MCP 서버 구성을 위한 사실상의 표준인 .json 형식을 지원합니다. mcp_config.json 파일에서 서버를 구성할 수 있습니다.

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // optional, for management API
        }
      }
    }
}

💡 서버 경로 찾기 :
macOS/Linux: which supabase-mcp-server 실행합니다.
Windows: where supabase-mcp-server 실행합니다.

구성 우선 순위

서버는 다음 순서로 구성을 찾습니다.

환경 변수(가장 높은 우선순위)
현재 디렉토리의 로컬 .env 파일
글로벌 구성 파일:
- 윈도우: %APPDATA%/supabase-mcp/.env
- macOS/Linux: ~/.config/supabase-mcp/.env
기본 설정(로컬 개발)

3단계. Cursor/Windsurf에서 MCP 서버 실행

일반적으로 stdio 프로토콜을 지원하는 모든 MCP 클라이언트는 이 MCP 서버(예: Cline)와 함께 작동해야 하지만 Cursor/Windsurf 외에는 테스트하지 않았습니다.

커서

설정 -> 기능 -> MCP 서버로 이동하여 다음 구성으로 새 서버를 추가합니다.

# can be set to any name
name: supabase
type: command
# if you installed with pipx
command: supabase-mcp-server
# if you installed with uv
command: uv run supabase-mcp-server

구성이 올바르면 녹색 점 표시기와 서버에서 노출된 도구 수가 표시됩니다.

윈드서핑

Cascade로 이동 -> 망치 아이콘을 클릭 -> 구성 -> 구성을 입력합니다.

{
    "mcpServers": {
      "supabase": {
        "command": "/Users/username/.local/bin/supabase-mcp-server",  // update path
        "env": {
          "SUPABASE_PROJECT_REF": "your-project-ref",
          "SUPABASE_DB_PASSWORD": "your-db-password",
          "SUPABASE_REGION": "us-east-1",  // optional, defaults to us-east-1
          "SUPABASE_ACCESS_TOKEN": "your-access-token"  // optional, for management API
        }
      }
    }
}

구성이 올바르면 사용 가능한 서버 목록에서 녹색 점 표시기와 클릭 가능한 supabase 서버를 볼 수 있습니다.

문제 해결

도움이 될 만한 몇 가지 팁과 요령은 다음과 같습니다.

디버그 설치 - 터미널에서 supabase-mcp-server 직접 실행하여 제대로 작동하는지 확인하세요. 작동하지 않으면 설치에 문제가 있을 수 있습니다.
MCP 서버 구성 - 위 단계가 제대로 작동하면 서버가 올바르게 설치 및 구성된 것입니다. 올바른 명령을 입력하면 IDE에서 연결할 수 있습니다. 서버 실행 파일의 경로를 정확하게 입력해야 합니다.
환경 변수 - 올바른 데이터베이스에 연결하려면 mcp_config.json 이나 글로벌 구성 디렉토리(macOS/Linux에서는 ~/.config/supabase-mcp/.env , Windows에서는 %APPDATA%\supabase-mcp\.env )에 있는 .env 파일에 환경 변수를 설정해야 합니다.
로그 액세스 - MCP 서버는 자세한 로그를 파일에 기록합니다.
- 로그 파일 위치:
  - macOS/Linux: ~/.local/share/supabase-mcp/mcp_server.log
  - Windows: %USERPROFILE%\.local\share\supabase-mcp\mcp_server.log
- 로그에는 연결 상태, 구성 세부 정보 및 작업 결과가 포함됩니다.
- 텍스트 편집기나 터미널 명령을 사용하여 로그를 확인하세요.
  # On macOS/Linux cat ~/.local/share/supabase-mcp/mcp_server.log # On Windows (PowerShell) Get-Content "$env:USERPROFILE\.local\share\supabase-mcp\mcp_server.log"

문제가 발생하거나 위의 지침이 올바르지 않은 경우 문제를 제기해 주세요.

MCP 검사관

MCP 서버 문제 디버깅에 매우 유용한 도구는 MCP Inspector입니다. 소스에서 설치한 경우, 프로젝트 저장소에서 supabase-mcp-inspector 실행하면 Inspector 인스턴스가 실행됩니다. 로그와 함께 서버에서 발생하는 상황을 전체적으로 파악할 수 있습니다.

📝 패키지에서 설치한 경우 supabase-mcp-inspector 실행하면 제대로 작동하지 않습니다. 다음 릴리스에서 검증하고 수정하겠습니다.

기능 개요

데이터베이스 쿼리 도구

v0.3.0 서버는 읽기 전용 작업과 데이터 수정 작업을 모두 지원합니다.

읽기 작업 : 데이터 검색을 위한 SELECT 쿼리
데이터 조작 언어(DML) : 데이터 변경에 대한 INSERT, UPDATE, DELETE 작업
데이터 정의 언어(DDL) : 스키마 변경을 위한 CREATE, ALTER, DROP 작업*

*참고: DDL 작업에는 다음이 필요합니다.

live_dangerously 통해 읽기-쓰기 모드가 활성화되었습니다.
연결된 데이터베이스 역할에 대한 충분한 권한

거래 처리

서버는 쓰기 작업을 실행하기 위한 두 가지 접근 방식을 지원합니다.

명시적 거래 제어 (권장):
BEGIN; CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT); COMMIT;
단일 문장 :
CREATE TABLE public.test_table (id SERIAL PRIMARY KEY, name TEXT);

DDL 작업(CREATE/ALTER/DROP)의 경우 도구 설명에서는 Cursor/Windsurft가 BEGIN/COMMIT 블록을 사용하여 명시적 트랜잭션 제어를 사용하도록 적절하게 안내합니다.

연결 유형

이 MCP 서버는 다음을 사용합니다.

직접 데이터베이스 연결 : 로컬 Supabase 인스턴스에 연결할 때
트랜잭션 풀러 연결 : 원격 Supabase 인스턴스에 연결할 때

Supabase의 트랜잭션 풀러를 통해 연결할 때 일부 복잡한 트랜잭션 패턴이 예상대로 작동하지 않을 수 있습니다. 이러한 환경에서 스키마를 변경하는 경우 명시적인 트랜잭션 블록을 사용하거나 Supabase 마이그레이션 또는 대시보드의 SQL 편집기를 사용하는 것이 좋습니다.

사용 가능한 데이터베이스 도구:

get_db_schemas - 모든 데이터베이스 스키마를 크기와 테이블 수와 함께 나열합니다.
get_tables - 스키마의 모든 테이블을 크기, 행 수, 메타데이터와 함께 나열합니다.
get_table_schema - 열, 키, 관계를 포함한 자세한 테이블 구조를 가져옵니다.
execute_sql_query - 모든 PostgreSQL 작업에 대한 포괄적인 지원을 통해 원시 SQL 쿼리를 실행합니다.
- 모든 쿼리 유형(SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP 등)을 지원합니다.
- 트랜잭션 제어 명령문(BEGIN, COMMIT, ROLLBACK)을 처리합니다.
지원되는 모드:
- read-only - 읽기 전용 쿼리만 허용됩니다(기본 모드)
- read-write - 명시적으로 활성화된 경우 모든 SQL 작업이 허용됩니다.
안전 기능:
- 기본적으로 읽기 전용 모드로 시작합니다.
- 쓰기 작업을 위해 명시적인 모드 전환이 필요합니다.
- 쓰기 작업 후 자동으로 읽기 전용 모드로 재설정됩니다.
- 오류를 방지하기 위한 지능형 거래 상태 감지
- SQL 쿼리 검증 [TODO]

관리 API 도구

v0.3.0 서버는 프로젝트 참조 및 안전 모드 제어의 자동 주입을 통해 Supabase 관리 API에 임의의 요청을 보내는 것을 지원합니다.

다음 도구가 포함되어 있습니다.
- 프로젝트 참조 및 안전 모드 제어의 자동 주입을 통해 Supabase 관리 API에 임의의 요청을 보내기 위한 send_management_api_request
- get_management_api_spec 사용하여 안전 정보가 포함된 강화된 API 사양을 가져옵니다.
- 차단된 작업과 안전하지 않은 작업을 포함한 모든 안전 규칙을 사람이 읽을 수 있는 설명과 함께 가져오려면 get_management_api_safety_rules .
- live_dangerously 사용하여 안전 모드와 안전하지 않은 모드 사이를 전환합니다.
안전 기능:
- 작업의 위험도에 따라 API 메서드를 safe , unsafe , blocked 범주로 구분합니다.
- 안전 모드와 안전하지 않은 모드 사이를 동적으로 전환할 수 있습니다.
- 차단된 작업(프로젝트 삭제, 데이터베이스 삭제)은 모드에 관계없이 허용되지 않습니다.

인증 관리 도구

MCP 서버에 Python SDK 메서드 지원을 추가할 계획이었습니다. 테스트 사용자를 수동으로 생성하는 데 오류가 발생하고 시간이 많이 소요되는 경우가 많았기 때문에, 검토 후 Auth 관리자 메서드 지원만 추가하기로 결정했습니다. 이제 Cursor에 테스트 사용자를 생성해 달라고 요청하기만 하면 됩니다. Auth 관리자 SDK 메서드의 전체 기능을 확인하려면 해당 메서드의 전체 문서를 확인하세요.

v0.3.6 서버는 Python SDK를 통해 Supabase Auth Admin 메서드에 직접 액세스할 수 있도록 지원합니다.

다음 도구가 포함되어 있습니다.
- get_auth_admin_methods_spec 사용하여 사용 가능한 모든 인증 관리 방법에 대한 문서를 검색합니다.
- call_auth_admin_method 하여 적절한 매개변수 처리를 통해 Auth Admin 메서드를 직접 호출합니다.
지원되는 방법:
- get_user_by_id : ID로 사용자를 검색합니다.
- list_users : 페이지 번호가 있는 모든 사용자 나열
- create_user : 새로운 사용자를 생성합니다
- delete_user : ID로 사용자를 삭제합니다.
- invite_user_by_email : 사용자의 이메일로 초대 링크를 보냅니다.
- generate_link : 다양한 인증 목적으로 이메일 링크를 생성합니다.
- update_user_by_id : ID로 사용자 속성 업데이트
- delete_factor : 사용자의 요소를 삭제합니다(현재 SDK에 구현되어 있지 않음)

원시 SQL 쿼리 대신 Auth Admin SDK를 사용하는 이유는 무엇입니까?

Auth Admin SDK는 직접적인 SQL 조작에 비해 여러 가지 주요 이점을 제공합니다.

기능 : SQL만으로는 불가능한 작업(초대, 매직 링크, MFA)을 가능하게 합니다.
정확도 : 인증 스키마에 대한 원시 SQL 쿼리를 생성하고 실행하는 것보다 더 안정적입니다.
단순성 : 적절한 검증 및 오류 처리를 통해 명확한 방법을 제공합니다.
- 응답 형식:
  - 모든 메서드는 원시 사전 대신 구조화된 Python 객체를 반환합니다.
  - 객체 속성은 점 표기법을 사용하여 액세스할 수 있습니다(예: user["id"] 대신 user.id ).
- 예외 사례 및 제한 사항:
  - UUID 유효성 검사: 많은 메서드에서 사용자 ID에 대한 유효한 UUID 형식이 필요하며 특정 유효성 검사 오류가 반환됩니다.
  - 이메일 구성: invite_user_by_email 및 generate_link 와 같은 방법을 사용하려면 Supabase 프로젝트에서 이메일 전송을 구성해야 합니다.
  - 링크 유형: 링크를 생성할 때, 다양한 링크 유형에는 각기 다른 요구 사항이 있습니다.
    - signup 링크는 사용자가 존재하지 않아도 됩니다.
    - magiclink 및 recovery 링크를 사용하려면 사용자가 시스템에 이미 존재해야 합니다.
  - 오류 처리: 서버는 Supabase API에서 자세한 오류 메시지를 제공하며 이는 대시보드 인터페이스와 다를 수 있습니다.
  - 메서드 가용성: delete_factor 와 같은 일부 메서드는 API에 노출되어 있지만 SDK에서는 완전히 구현되지 않았습니다.

로드맵

📦 패키지 관리자를 통한 간소화된 설치 - ✅ (v0.2.0)
🌎 다양한 Supabase 지역 지원 - ✅ (v0.2.2)
🎮 안전 제어 기능을 갖춘 Supabase 관리 API에 대한 프로그래밍 방식 액세스 - ✅ (v0.3.0)
👷‍♂️ 안전 제어 기능을 갖춘 읽기 및 읽기-쓰기 데이터베이스 SQL 쿼리 - ✅ (v0.3.0)
🔄 직접 연결과 풀 연결 모두에 대한 강력한 트랜잭션 처리 - ✅ (v0.3.2)
🐍 네이티브 Python SDK에서 사용 가능한 메서드 및 객체 지원 - ✅ (v0.3.6)
🔍 더 강력한 SQL 쿼리 검증(읽기 대 쓰기 작업)
📝 DDL 쿼리의 자동 버전 관리(?)
🪵 데이터베이스, 엣지 함수 로그에 보다 쉽게 액세스할 수 있는 도구/리소스 (?)
👨‍💻 Supabase CLI 통합 (?)

Supabase 로그에 연결

디버깅에 유용할 수 있는 Supabase db 로그에 연결할 수 있는지 조사할 계획입니다(아직 지원되지 않는 경우).

즐겨보세요! ☺️

Supabase MCP Server

Integrations

Supabase MCP 서버

목차

✨ 주요 특징

시작하기

필수 조건

PostgreSQL 설치

1단계. MCP 서버 설치

소스에서 설치

Smithery.ai를 통해 설치

2단계. 구성

로컬 Supabase 인스턴스(기본값)

원격 Supabase 인스턴스

커서

윈드서핑

구성 우선 순위

3단계. Cursor/Windsurf에서 MCP 서버 실행

커서

윈드서핑

문제 해결

MCP 검사관

기능 개요

데이터베이스 쿼리 도구

거래 처리

연결 유형

관리 API 도구

인증 관리 도구

원시 SQL 쿼리 대신 Auth Admin SDK를 사용하는 이유는 무엇입니까?

로드맵

Supabase 로그에 연결

Appeared in Searches