Supabase MCP 서버

Claude와 다른 LLM이 Supabase와 상호 작용하여 Postgres 테이블에서 CRUD 작업을 수행할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

특징

데이터베이스 작업:
- 필터를 사용하여 데이터 쿼리
- 데이터 삽입
- 데이터 업데이트
- 데이터 삭제
- 테이블 목록

필수 조건

Node.js(v16 이상)
npm 또는 yarn
API 키가 있는 Supabase 프로젝트

설치

옵션 1: npm에서 설치(권장)

패키지는 npm에 게시되었습니다! 다음을 사용하여 전역으로 설치할 수 있습니다.

지엑스피1

또는 프로젝트 내에서 로컬로:

npm install supabase-mcp

옵션 2: 저장소 복제

git clone https://github.com/Cappahccino/SB-MCP.git
cd SB-MCP
npm install
npm run build

구성

Supabase 자격 증명으로 .env 파일을 만듭니다.

# Supabase credentials
SUPABASE_URL=your_supabase_project_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_supabase_service_role_key

# MCP server configuration
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=localhost
MCP_API_KEY=your_secret_api_key

Claude와 함께 사용

Claude는 호환성을 위해 특정 전송 모드를 필요로 합니다. 이 패키지는 Claude 통합을 위한 전용 바이너리를 제공합니다.

Claude Desktop MCP 구성

"supabase": {
  "command": "npx",
  "args": [
    "-y",
    "supabase-mcp@latest",
    "supabase-mcp-claude"
  ],
  "env": {
    "SUPABASE_URL": "your_supabase_project_url",
    "SUPABASE_ANON_KEY": "your_supabase_anon_key", 
    "SUPABASE_SERVICE_ROLE_KEY": "your_service_role_key",
    "MCP_API_KEY": "your_secret_api_key"
  }
}

구성에서 필요한 환경 변수를 설정했는지 확인하세요. Claude는 통신을 위해 stdio 전송을 사용합니다.

Claude Binary를 사용한 수동 테스트

Claude 외부에서 테스트하려면 다음을 실행할 수 있습니다.

npm run start:claude

또는 글로벌하게 설치된 경우:

supabase-mcp-claude

독립형 서버로 사용

전역적으로 설치한 후:

supabase-mcp

이렇게 하면 http://localhost:3000 (또는 .env 파일에 지정된 포트)에서 MCP 서버가 시작됩니다.

코드에서의 사용

또한, Node.js 프로젝트에서 라이브러리로 supabase-mcp를 사용할 수도 있습니다.

import { createServer, mcpConfig, validateConfig } from 'supabase-mcp';

// Validate configuration
validateConfig();

// Create the server
const app = createServer();

// Start the server
app.listen(mcpConfig.port, mcpConfig.host, () => {
  console.log(`Supabase MCP server running at http://${mcpConfig.host}:${mcpConfig.port}`);
});

문제 해결

일반적인 문제 및 솔루션

1. "포트 XXXX가 이미 사용 중입니다."

HTTP 서버는 사용 가능한 포트를 자동으로 찾습니다. .env 파일에서 MCP_SERVER_PORT 값을 변경하여 다른 포트를 수동으로 지정할 수 있습니다.

2. "필수 환경 변수가 없습니다"

모든 필수 값이 포함된 적절한 .env 파일이 있는지, 아니면 시스템에 환경 변수를 설정했는지 확인하세요.

3. "TypeError: 클래스 생성자 Server는 'new' 없이 호출할 수 없습니다."

이 오류가 표시되면 이전 버전의 패키지를 실행 중일 수 있습니다. 최신 버전으로 업데이트하세요.

npm install -g supabase-mcp@latest

4. Claude를 사용한 JSON 구문 분석 오류

일반 HTTP 서버(supabase- supabase-mcp supabase-mcp-claude )를 사용하고 있는지 확인하세요.

5. Claude와의 요청 시간이 초과되었습니다.

이는 일반적으로 Claude가 연결을 시작했지만 서버가 제때 응답하지 못했음을 의미합니다. 다음을 확인하세요.

귀하의 Supabase 자격증명이 정확합니까?
서버가 올바르게 설정되어 실행되고 있나요?
연결을 차단하는 것이 있나요?

도구 참조

데이터베이스 도구

쿼리데이터베이스
- 매개변수:
  - table (문자열): 쿼리할 테이블의 이름
  - select (문자열, 선택 사항): 쉼표로 구분된 열 목록(기본값: "*")
  - query (객체, 선택 사항): 필터 조건
데이터 삽입
- 매개변수:
  - table (문자열): 테이블의 이름
  - data (객체 또는 객체 배열): 삽입할 데이터
업데이트데이터
- 매개변수:
  - table (문자열): 테이블의 이름
  - data (객체): 키-값 쌍으로 업데이트할 데이터
  - query (객체): 업데이트에 대한 필터 조건
데이터 삭제
- 매개변수:
  - table (문자열): 테이블의 이름
  - query (객체): 삭제를 위한 필터 조건
리스트테이블
- 매개변수: 없음

버전 기록

1.0.0: 최초 릴리스
1.0.1: 자동 포트 선택 추가
1.0.2: 프로토콜 호환성 문제 해결
1.0.3: JSON-RPC 지원 추가
1.1.0: 공식 MCP SDK를 사용하여 완전히 다시 작성
1.2.0: 별도의 Claude 전송 추가 및 포트 충돌 문제 해결
1.3.0: TypeScript 프로젝트와의 호환성을 개선하기 위해 업데이트되었습니다.
1.4.0: Supabase 커뮤니티 모범 사례를 기반으로 Claude stdio 전송 통합이 수정되었습니다.
1.5.0: 안정성을 개선하고 데이터베이스 작업에 집중하기 위해 Edge Function 지원이 제거되었습니다.

특허

MIT

Supabase MCP Server

Integrations