Self-Hosted Supabase MCP Server

자체 호스팅 Supabase MCP 서버

개요

이 프로젝트는 자체 호스팅 Supabase 인스턴스 와의 상호 작용을 위해 특별히 설계된 모델 컨텍스트 프로토콜(MCP) 서버를 제공합니다. 이 서버는 MCP 클라이언트(IDE 확장 프로그램 등)와 로컬 또는 비공개 호스팅 Supabase 프로젝트 간의 격차를 해소하여 개발 환경에서 직접 데이터베이스 검사, 관리 및 상호 작용을 지원합니다.

이 서버는 Supabase 공식 클라우드 MCP 서버를 적용한 경험을 바탕으로 자체 호스팅 사용 사례에 맞춰 최소한의 집중적인 구현을 제공하기 위해 처음부터 구축되었습니다.

목적

이 서버의 주요 목표는 자체 호스팅 Supabase 설치를 사용하는 개발자가 다음과 같은 작업에 MCP 기반 도구를 활용할 수 있도록 하는 것입니다.

• 데이터베이스 스키마와 데이터 쿼리.
• 데이터베이스 마이그레이션 관리.
• 데이터베이스 통계 및 연결을 검사합니다.
• 인증 사용자 관리.
• Supabase 저장소와 상호작용합니다.
• 유형 정의 생성.

다중 프로젝트 관리 및 클라우드 전용 API와 관련된 공식 클라우드 서버의 복잡성을 피하고, 단일 프로젝트의 셀프 호스팅 환경에 대한 간소화된 경험을 제공합니다.

기능(구현된 도구)

서버는 다음 도구를 MCP 클라이언트에 제공합니다.

• 스키마 및 마이그레이션
  • list_tables : 데이터베이스 스키마의 테이블을 나열합니다.
  • list_extensions : 설치된 PostgreSQL 확장 기능을 나열합니다.
  • list_migrations : 적용된 Supabase 마이그레이션을 나열합니다.
  • apply_migration : SQL 마이그레이션 스크립트를 적용합니다.
• 데이터베이스 작업 및 통계
  • execute_sql : 임의의 SQL 쿼리를 실행합니다(RPC 또는 직접 연결을 통해).
  • get_database_connections : 활성 데이터베이스 연결을 보여줍니다( pg_stat_activity ).
  • get_database_stats : 데이터베이스 통계를 검색합니다( pg_stat_* ).
• 프로젝트 구성 및 키
  • get_project_url : 구성된 Supabase URL을 반환합니다.
  • get_anon_key : 구성된 Supabase 익명 키를 반환합니다.
  • get_service_key : 구성된 Supabase 서비스 역할 키를 반환합니다(제공된 경우).
  • verify_jwt_secret : JWT 비밀번호가 구성되었는지 확인하고 미리 보기를 반환합니다.
• 개발 및 확장 도구
  • generate_typescript_types : 데이터베이스 스키마에서 TypeScript 유형을 생성합니다.
  • rebuild_hooks : pg_net 워커를 다시 시작하려고 시도합니다(사용하는 경우).
• 인증 사용자 관리
  • list_auth_users : auth.users 에서 사용자를 나열합니다.
  • get_auth_user : 특정 사용자에 대한 세부 정보를 검색합니다.
  • create_auth_user : 새로운 사용자를 생성합니다(직접 DB 접근이 필요하고, 안전하지 않은 비밀번호 처리가 필요합니다).
  • delete_auth_user : 사용자를 삭제합니다(DB에 직접 접근해야 함).
  • update_auth_user : 사용자 세부 정보를 업데이트합니다(직접 DB 액세스, 안전하지 않은 암호 처리가 필요함).
• 스토리지 인사이트
  • list_storage_buckets : 모든 스토리지 버킷을 나열합니다.
  • list_storage_objects : 특정 버킷 내의 객체를 나열합니다.
• 실시간 검사
  • list_realtime_publications : PostgreSQL 게시물(종종 supabase_realtime )을 나열합니다.

(참고: get_logs 원래 계획되었지만 셀프 호스팅 환경에서 구현이 복잡하여 생략되었습니다.)

설정 및 설치

Smithery를 통해 설치

Smithery를 통해 Claude Desktop용 Self-Hosted Supabase MCP 서버를 자동으로 설치하려면:

지엑스피1

필수 조건

• Node.js(버전 18.x 이상 권장)
• npm(일반적으로 Node.js에 포함됨)
• 자체 호스팅 Supabase 인스턴스에 대한 액세스(URL, 키, 잠재적으로 직접 DB 연결 문자열).

단계

1. 저장소를 복제합니다.
   git clone <repository-url> cd self-hosted-supabase-mcp
2. 종속성 설치:
   npm install
3. 프로젝트를 빌드하세요:
   npm run build
   이렇게 하면 TypeScript 코드가 dist 디렉토리의 JavaScript로 컴파일됩니다.

구성

서버에는 Supabase 인스턴스에 대한 구성 정보가 필요합니다. 이러한 정보는 명령줄 인수 또는 환경 변수를 통해 제공할 수 있습니다. CLI 인수가 우선합니다.

필수의:

• --url <url> 또는 SUPABASE_URL=<url> : Supabase 프로젝트의 기본 HTTP URL(예: http://localhost:8000 ).
• --anon-key <key> 또는 SUPABASE_ANON_KEY=<key> : Supabase 프로젝트의 익명 키입니다.

선택 사항(그러나 특정 도구의 경우 권장/필수):

• --service-key <key> 또는 SUPABASE_SERVICE_ROLE_KEY=<key> : Supabase 프로젝트의 서비스 역할 키입니다. execute_sql 도우미 함수가 없는 경우 자동으로 생성하려는 경우처럼 높은 권한이 필요한 작업에 필요합니다.
• --db-url <url> 또는 DATABASE_URL=<url> : Supabase 데이터베이스에 대한 직접 PostgreSQL 연결 문자열(예: postgresql://postgres:password@localhost:5432/postgres ). 직접 데이터베이스 액세스 또는 트랜잭션이 필요한 도구( apply_migration , 인증 도구, 저장소 도구, pg_catalog 쿼리 등)에 필요합니다.
• --jwt-secret <secret> 또는 SUPABASE_AUTH_JWT_SECRET=<secret> : Supabase 프로젝트의 JWT 비밀입니다. verify_jwt_secret 과 같은 도구에 필요합니다.
• --tools-config <path> : 활성화할 도구(허용 목록)를 지정하는 JSON 파일 경로입니다. 생략하면 서버에 정의된 모든 도구가 활성화됩니다. 파일 형식은 {"enabledTools": ["tool_name_1", "tool_name_2"]} 여야 합니다.

중요 참고 사항:

• execute_sql 도우미 함수: 많은 도구가 RPC를 통한 안전하고 효율적인 SQL 실행을 위해 Supabase 데이터베이스 내의 public.execute_sql 함수를 사용합니다. 서버는 시작 시 이 함수를 확인하려고 시도합니다. 이 함수가 없고 service-key (또는 SUPABASE_SERVICE_ROLE_KEY ) 와 db-url (또는 DATABASE_URL )이 제공된 경우, 서버는 함수를 생성하고 필요한 권한을 부여하려고 시도합니다. 생성에 실패하거나 키가 제공되지 않으면 RPC에만 의존하는 도구가 실패할 수 있습니다.
• 직접 데이터베이스 액세스: 권한이 있는 스키마( auth , storage ) 또는 시스템 카탈로그( pg_catalog )와 직접 상호 작용하는 도구는 일반적으로 직접 pg 연결을 위해 DATABASE_URL 구성해야 합니다.

용법

Node.js를 사용하여 서버를 실행하고 필요한 구성을 제공합니다.

서버는 표준 입출력(stdio)을 통해 통신하며 MCP 클라이언트 애플리케이션(예: Cursor와 같은 IDE 확장 프로그램)에서 호출되도록 설계되었습니다. 클라이언트는 서버의 stdio 스트림에 연결하여 사용 가능한 도구를 나열하고 호출합니다.

클라이언트 구성 예

다음은 이 셀프 호스팅 서버를 사용하도록 인기 있는 MCP 클라이언트를 구성하는 방법에 대한 예입니다.

중요한:

• <your-supabase-url> , <your-anon-key> , <your-db-url> , <path-to-dist/index.js> 등의 플레이스홀더를 실제 값으로 바꾸세요.
• 컴파일된 서버 파일( dist/index.js )의 경로가 시스템에 맞는지 확인하세요.
• 특히 버전 관리에 커밋된 경우 민감한 키를 구성 파일에 직접 저장하는 데 주의하세요. 클라이언트에서 지원하는 경우 환경 변수나 더 안전한 방법을 사용하는 것이 좋습니다.

커서

1. 프로젝트 루트에 .cursor/mcp.json 파일을 만들거나 엽니다.
2. 다음 구성을 추가합니다.
   { "mcpServers": { "selfhosted-supabase": { "command": "node", "args": [ "<path-to-dist/index.js>", // e.g., "F:/Projects/mcp-servers/self-hosted-supabase-mcp/dist/index.js" "--url", "<your-supabase-url>", // e.g., "http://localhost:8000" "--anon-key", "<your-anon-key>", // Optional - Add these if needed by the tools you use "--service-key", "<your-service-key>", "--db-url", "<your-db-url>", // e.g., "postgresql://postgres:password@host:port/postgres" "--jwt-secret", "<your-jwt-secret>", // Optional - Whitelist specific tools "--tools-config", "<path-to-your-mcp-tools.json>" // e.g., "./mcp-tools.json" ] } } }

Visual Studio Code(Copilot)

VS Code Copilot을 사용하면 프롬프트 입력을 통해 채워진 환경 변수를 사용할 수 있으므로 키에 대한 보안이 더 강화됩니다.

1. 프로젝트 루트에서 .vscode/mcp.json 파일을 만들거나 엽니다.
2. 다음 구성을 추가합니다.
   { "inputs": [ { "type": "promptString", "id": "sh-supabase-url", "description": "Self-Hosted Supabase URL", "default": "http://localhost:8000" }, { "type": "promptString", "id": "sh-supabase-anon-key", "description": "Self-Hosted Supabase Anon Key", "password": true }, { "type": "promptString", "id": "sh-supabase-service-key", "description": "Self-Hosted Supabase Service Key (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-db-url", "description": "Self-Hosted Supabase DB URL (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-jwt-secret", "description": "Self-Hosted Supabase JWT Secret (Optional)", "password": true, "required": false }, { "type": "promptString", "id": "sh-supabase-server-path", "description": "Path to self-hosted-supabase-mcp/dist/index.js" }, { "type": "promptString", "id": "sh-supabase-tools-config", "description": "Path to tools config JSON (Optional, e.g., ./mcp-tools.json)", "required": false } ], "servers": { "selfhosted-supabase": { "command": "node", // Arguments are passed via environment variables set below OR direct args for non-env options "args": [ "${input:sh-supabase-server-path}", // Use direct args for options not easily map-able to standard env vars like tools-config // Check if tools-config input is provided before adding the argument ["--tools-config", "${input:sh-supabase-tools-config}"] // Alternatively, pass all as args if simpler: // "--url", "${input:sh-supabase-url}", // "--anon-key", "${input:sh-supabase-anon-key}", // ... etc ... ], "env": { "SUPABASE_URL": "${input:sh-supabase-url}", "SUPABASE_ANON_KEY": "${input:sh-supabase-anon-key}", "SUPABASE_SERVICE_ROLE_KEY": "${input:sh-supabase-service-key}", "DATABASE_URL": "${input:sh-supabase-db-url}", "SUPABASE_AUTH_JWT_SECRET": "${input:sh-supabase-jwt-secret}" // The server reads these environment variables as fallbacks if CLI args are missing } } } }
3. 에이전트 모드(@workspace)에서 Copilot Chat을 사용하면 서버를 감지해야 합니다. 서버를 처음 호출할 때 세부 정보(URL, 키, 경로)를 입력하라는 메시지가 표시됩니다.

다른 고객(윈드서프, 클라인, 클로드)

Cursor 또는 공식 Supabase 문서에 표시된 구성 구조를 조정하여 command 과 args Cursor 예제와 유사하게 이 서버에 대한 node 명령과 인수로 바꿉니다.

mcp.json 또는 이와 동등한 구성 파일을 어디에 배치해야 하는지에 대한 자세한 내용은 각 클라이언트의 특정 문서를 참조하세요.

개발

• 언어: TypeScript
• 빌드: tsc (TypeScript 컴파일러)
• 종속성: npm ( package.json )을 통해 관리됨
• 핵심 라이브러리: @supabase/supabase-js , pg (node-postgres), zod (검증), commander (CLI 인수), @modelcontextprotocol/sdk (MCP 서버 프레임워크).

특허

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