SingleStore MCP 서버

SingleStore 데이터베이스와 상호 작용하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 이 서버는 테이블 쿼리, 스키마 설명, ER 다이어그램 생성 도구를 제공합니다.

특징

데이터베이스의 모든 테이블 나열
사용자 정의 SQL 쿼리 실행
스키마와 샘플 데이터를 포함한 자세한 테이블 정보를 얻으세요
데이터베이스 스키마의 Mermaid ER 다이어그램 생성
자동 CA 번들 페칭을 통한 SSL 지원
적절한 오류 처리 및 TypeScript 유형 안전성

필수 조건

Node.js 16 이상
npm 또는 yarn
SingleStore 데이터베이스에 액세스
SingleStore CA 번들(포털에서 자동으로 가져옴)

설치

Smithery를 통해 설치

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

지엑스피1

저장소를 복제합니다.

git clone <repository-url>
cd mcp-server-singlestore

종속성 설치:

npm install

서버를 빌드하세요:

npm run build

환경 변수

필수 환경 변수

서버에는 데이터베이스 연결을 위해 다음과 같은 환경 변수가 필요합니다.

SINGLESTORE_HOST=your-host.singlestore.com
SINGLESTORE_PORT=3306
SINGLESTORE_USER=your-username
SINGLESTORE_PASSWORD=your-password
SINGLESTORE_DATABASE=your-database

서버가 SingleStore 데이터베이스에 연결하는 데 이러한 모든 환경 변수가 필요합니다. 이 연결은 SingleStore 포털에서 자동으로 가져오는 SingleStore CA 번들과 함께 SSL을 사용합니다.

선택적 환경 변수

SSE(Server-Sent Events) 프로토콜 지원:

SSE_ENABLED=true       # Enable the SSE HTTP server (default: false if not set)
SSE_PORT=3333          # HTTP port for the SSE server (default: 3333 if not set)

환경 변수 설정

셸에서 : 서버를 실행하기 전에 터미널에서 변수를 설정하세요.
export SINGLESTORE_HOST=your-host.singlestore.com export SINGLESTORE_PORT=3306 export SINGLESTORE_USER=your-username export SINGLESTORE_PASSWORD=your-password export SINGLESTORE_DATABASE=your-database
클라이언트 구성 파일 : 아래 통합 섹션에 표시된 대로 MCP 클라이언트 구성 파일에 변수를 추가합니다.

용법

프로토콜 지원

이 서버는 클라이언트 통합을 위해 두 가지 프로토콜을 지원합니다.

MCP 프로토콜 : Claude Desktop, Windsurf, Cursor에서 사용하는 stdio 통신을 사용하는 표준 모델 컨텍스트 프로토콜입니다.
SSE 프로토콜 : 실시간 데이터 스트리밍이 필요한 웹 기반 클라이언트와 애플리케이션을 위해 HTTP를 통해 서버에서 전송하는 이벤트입니다.

두 프로토콜 모두 동일한 도구와 기능을 제공하므로 사용 사례에 가장 적합한 통합 방법을 선택할 수 있습니다.

사용 가능한 도구

리스트_테이블
- 데이터베이스의 모든 테이블을 나열합니다
- 매개변수가 필요 없습니다 GXP8
쿼리_테이블
- 사용자 정의 SQL 쿼리를 실행합니다
- 매개변수:
  - 쿼리: SQL 쿼리 문자열 GXP9
설명_테이블
- 테이블에 대한 자세한 정보를 가져옵니다
- 매개변수:
  - 테이블: 테이블 이름 GXP10
생성_도표_생성
- 데이터베이스 스키마의 Mermaid ER 다이어그램을 생성합니다.
- 매개변수가 필요 없습니다 GXP11
실행_읽기_쿼리
- 데이터베이스에 대한 읽기 전용(SELECT) 쿼리를 실행합니다.
- 매개변수:
  - 쿼리: GXP12를 실행하기 위한 SQL SELECT 쿼리
테이블 생성
- 지정된 열과 제약 조건을 사용하여 데이터베이스에 새 테이블을 만듭니다.
- 매개변수:
  - table_name: 생성할 테이블의 이름
  - 열: 열 정의 배열
  - table_options: 선택적 테이블 구성 GXP13
합성 데이터 생성
- 기존 테이블에 합성 데이터를 생성하고 삽입합니다.
- 매개변수:
  - table: 데이터를 삽입할 테이블의 이름
  - count: 생성할 행 수(기본값: 100)
  - column_generators: 특정 열에 대한 사용자 정의 생성기
  - batch_size: 각 배치에 삽입할 행 수(기본값: 1000) GXP14
optimize_sql
- PROFILE을 사용하여 SQL 쿼리를 분석하고 최적화 권장 사항을 제공합니다.
- 매개변수:
  - 쿼리: GXP15를 분석하고 최적화하기 위한 SQL 쿼리
- 응답에는 다음이 포함됩니다.
  - 원래 쿼리
  - 성능 프로필 요약(전체 런타임, 컴파일 시간, 실행 시간)
  - 감지된 병목 현상 목록
  - 영향 수준(높음/보통/낮음)에 따른 최적화 권장 사항
  - 인덱스, 조인, 메모리 사용 및 기타 최적화에 대한 제안

독립 실행형 실행

서버를 빌드하세요:

npm run build

MCP 프로토콜로만 서버를 실행합니다.

node build/index.js

MCP와 SSE 프로토콜을 모두 사용하여 서버를 실행합니다.

SSE_ENABLED=true SSE_PORT=3333 node build/index.js

SSE 프로토콜 사용

SSE가 활성화되면 서버는 다음 HTTP 엔드포인트를 노출합니다.

루트 엔드포인트
GET /
서버 정보와 사용 가능한 엔드포인트를 반환합니다.
건강 검진
GET /health
서버에 대한 상태 정보를 반환합니다.
SSE 연결
GET /sse
실시간 업데이트를 위해 서버 전송 이벤트 연결을 설정합니다.
목록 도구
GET /tools
MCP list_tools 기능과 동일하게 사용 가능한 모든 도구 목록을 반환합니다.MCP Inspector 호환성을 위한 POST 요청도 지원합니다.
POST /tools Content-Type: application/json { "jsonrpc": "2.0", "id": "request-id", "method": "mcp.list_tools", "params": {} }
통화 도구
POST /call-tool Content-Type: application/json { "name": "tool_name", "arguments": { "param1": "value1", "param2": "value2" }, "client_id": "optional_sse_client_id_for_streaming_response" }
제공된 인수로 도구를 실행합니다.
- client_id 제공되면 응답은 해당 SSE 클라이언트로 스트리밍됩니다.
- client_id 생략되면 응답은 HTTP 응답으로 직접 반환됩니다.
MCP Inspector 호환성을 위해 표준 MCP 형식도 지원합니다.
POST /call-tool Content-Type: application/json { "jsonrpc": "2.0", "id": "request-id", "method": "mcp.call_tool", "params": { "name": "tool_name", "arguments": { "param1": "value1", "param2": "value2" }, "_meta": { "client_id": "optional_sse_client_id_for_streaming_response" } } }

SSE 이벤트 유형

SSE 연결을 사용하는 경우 서버는 다음 이벤트 유형을 전송합니다.

메시지 (이름이 지정되지 않은 이벤트): SSE 연결이 성공적으로 설정되면 전송됩니다.
open : 추가 연결이 설정된 이벤트입니다.
메시지 : 도구 시작, 결과, 오류 이벤트를 포함한 모든 MCP 프로토콜 메시지에 사용됩니다.

모든 이벤트는 MCP 프로토콜에서 사용하는 JSON-RPC 2.0 형식을 따릅니다. 시스템은 MCP Inspector 및 대부분의 SSE 클라이언트 라이브러리와의 호환성을 위해 표준 message 이벤트 유형을 사용합니다.

JavaScript 클라이언트 예시

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:3333/sse');
let clientId = null;

// Handle connection establishment via unnamed event
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'connection_established') {
    clientId = data.clientId;
    console.log(`Connected with client ID: ${clientId}`);
  }
};

// Handle open event
eventSource.addEventListener('open', (event) => {
  console.log('SSE connection opened via open event');
});

// Handle all MCP messages
eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  
  if (data.jsonrpc === '2.0') {
    if (data.result) {
      console.log('Tool result:', data.result);
    } else if (data.error) {
      console.error('Tool error:', data.error);
    } else if (data.method === 'mcp.call_tool.update') {
      console.log('Tool update:', data.params);
    }
  }
});

// Call a tool with streaming response (custom format)
async function callTool(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: name,
      arguments: args,
      client_id: clientId
    })
  });
  return response.json();
}

// Call a tool with streaming response (MCP format)
async function callToolMcp(name, args) {
  const response = await fetch('http://localhost:3333/call-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 'request-' + Date.now(),
      method: 'mcp.call_tool',
      params: {
        name: name,
        arguments: args,
        _meta: {
          client_id: clientId
        }
      }
    })
  });
  return response.json();
}

// Example usage
callTool('list_tables', {})
  .then(response => console.log('Request accepted:', response));

MCP Inspector와 함께 사용

MCP Inspector는 MCP 서버를 테스트하고 디버깅하는 브라우저 기반 도구입니다. 이 서버에서 사용하려면 다음 단계를 따르세요.

하나의 명령으로 서버와 MCP 검사기를 모두 시작합니다.
npm run inspector
또는 다음을 사용하여 서버만 시작하세요.
npm run start:inspector
MCP Inspector를 별도로 설치하고 실행하려면:
npx @modelcontextprotocol/inspector
검사기는 기본 브라우저에서 열립니다.
MCP 검사관이 열리면:a. 연결 필드에 URL을 입력하세요.
http://localhost:8081
참고: 실제 포트는 구성에 따라 다를 수 있습니다. 서버 시작 로그에서 사용 중인 실제 포트를 확인하세요. 서버는 다음과 같이 출력합니다.
MCP SingleStore SSE server listening on port XXXX
b. 전송 유형으로 "SSE"가 선택되었는지 확인하세요.c. "연결"을 클릭하세요.
연결 문제가 발생하면 다음 대안을 시도해 보세요.a. 특정 엔드포인트에 연결을 시도해 보세요.
http://localhost:8081/stream
b. 컴퓨터의 실제 IP 주소를 사용해 보세요.
http://192.168.1.x:8081
c. Docker에서 실행하는 경우:
http://host.docker.internal:8081
연결 문제 디버깅 :a. 브라우저에서 http://localhost:8081을 방문하여 서버가 실행 중인지 확인하세요.b. 연결 시도에 대한 서버 로그를 확인하세요.c. 서버와 검사기를 모두 다시 시작해 보세요.d. 다른 서비스가 포트 8081을 사용하고 있지 않은지 확인하세요.e. 제공된 스크립트를 사용하여 SSE 연결을 테스트합니다.
npm run test:sse
또는 curl을 사용하여 수동으로:
curl -N http://localhost:8081/sse
f. 방화벽 설정이 포트 8081에 대한 연결을 허용하는지 확인하세요.
연결되면 검사기가 사용 가능한 모든 도구를 표시하고 대화형으로 테스트할 수 있습니다.

⚠️ 참고 : MCP 검사기를 사용할 때는 http:// 접두사를 포함한 전체 URL을 사용해야 합니다.

MCP 클라이언트 통합

Claude Desktop에 설치

Claude Desktop 구성 파일에 서버 구성을 추가하세요. 구성 파일은 다음 위치에 있습니다.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED 및 SSE_PORT 변수는 선택 사항입니다. 표준 MCP 프로토콜과 함께 HTTP 서버에서 SSE를 지원하도록 설정하려면 이 변수를 포함하세요.

Claude 데스크톱 앱을 다시 시작하세요
Claude와의 대화에서 이제 SingleStore MCP 서버를 다음과 함께 사용할 수 있습니다.

use_mcp_tool({
  server_name: "singlestore",
  tool_name: "list_tables",
  arguments: {}
})

윈드서프에 설치

다음 위치에 있는 Windsurf 구성 파일에 서버 구성을 추가하세요.
- macOS: ~/Library/Application Support/Windsurf/config.json
- 윈도우: %APPDATA%\Windsurf\config.json

{
  "mcpServers": {
    "singlestore": {
      "command": "node",
      "args": ["path/to/mcp-server-singlestore/build/index.js"],
      "env": {
        "SINGLESTORE_HOST": "your-host.singlestore.com",
        "SINGLESTORE_PORT": "3306",
        "SINGLESTORE_USER": "your-username",
        "SINGLESTORE_PASSWORD": "your-password",
        "SINGLESTORE_DATABASE": "your-database",
        "SSE_ENABLED": "true",
        "SSE_PORT": "3333"
      }
    }
  }
}

SSE_ENABLED 및 SSE_PORT 변수는 선택 사항이지만 SSE HTTP 서버를 통해 추가 기능을 활성화합니다.

윈드서프 재시작
Windsurf의 Claude와 대화할 때 Claude가 데이터베이스 정보에 액세스해야 할 때 SingleStore MCP 도구를 자동으로 사용할 수 있습니다.

커서에 설치

커서 설정에 서버 구성을 추가합니다.
- 오픈 커서
- 설정(기어 아이콘) > 확장 프로그램 > Claude AI > MCP 서버로 이동하세요.
- 다음 구성으로 새로운 MCP 서버를 추가합니다.

{
  "singlestore": {
    "command": "node",
    "args": ["path/to/mcp-server-singlestore/build/index.js"],
    "env": {
      "SINGLESTORE_HOST": "your-host.singlestore.com",
      "SINGLESTORE_PORT": "3306",
      "SINGLESTORE_USER": "your-username",
      "SINGLESTORE_PASSWORD": "your-password",
      "SINGLESTORE_DATABASE": "your-database",
      "SSE_ENABLED": "true",
      "SSE_PORT": "3333"
    }
  }
}

SSE_ENABLED 및 SSE_PORT 변수를 사용하면 웹 애플리케이션이 HTTP를 통해 서버에 연결하고 Server-Sent Events를 통해 실시간 업데이트를 수신할 수 있습니다.

커서 재시작
Cursor 내에서 Claude AI를 사용하면 SingleStore MCP 도구를 사용하여 데이터베이스 작업을 수행할 수 있습니다.

보안 고려 사항

버전 제어에 자격 증명을 커밋하지 마십시오.
환경 변수 또는 보안 구성 관리를 사용하세요
프로덕션 사용을 위해 연결 풀링 메커니즘 사용을 고려하세요
SingleStore에서 적절한 액세스 제어 및 사용자 권한을 구현합니다.
SingleStore CA 번들을 최신 상태로 유지하세요

개발

프로젝트 구조

mcp-server-singlestore/
├── src/
│   └── index.ts      # Main server implementation
├── package.json
├── tsconfig.json
├── README.md
└── CHANGELOG.md

건물

npm run build

테스트

npm test

문제 해결

연결 문제
- 환경 변수에서 자격 증명 및 호스트 정보를 확인하세요.
- SSL 구성 확인
- 네트워크에서 데이터베이스에 액세스할 수 있는지 확인하세요.
- SingleStore 데이터베이스에 대한 아웃바운드 연결을 허용하려면 방화벽 설정을 확인하세요.
빌드 문제
- node_modules를 지우고 종속성을 다시 설치하세요
- TypeScript 구성 확인
- Node.js 버전 호환성을 확인하세요(16 이상이어야 함)
MCP 통합 문제
- 클라이언트 구성에서 서버의 build/index.js 파일 경로가 올바른지 확인하세요.
- 클라이언트 구성에서 모든 환경 변수가 올바르게 설정되었는지 확인하세요.
- 구성 변경 후 클라이언트 애플리케이션을 다시 시작하세요.
- MCP 서버와 관련된 오류 메시지가 있는지 클라이언트 로그를 확인하세요.
- 클라이언트 외부에서 작동하는지 확인하려면 먼저 서버를 독립 실행형으로 실행해 보세요.

기여하다

저장소를 포크하세요
기능 브랜치 생성
변경 사항을 커밋하세요
지점으로 밀어 넣기
풀 리퀘스트 만들기

특허

MIT 라이센스 - 자세한 내용은 라이센스 파일을 참조하세요.

SingleStore MCP Server

Integrations