SingleStore MCP 서버

Model Context Protocol(MCP)은 대규모 언어 모델(LLM)과 외부 시스템 간의 컨텍스트를 관리하기 위해 설계된 표준화된 프로토콜입니다. 이 저장소는 SingleStore용 설치 프로그램과 MCP 서버를 제공하여 원활한 통합을 지원합니다.

MCP를 사용하면 Claude Desktop, Claude Code, Cursor 또는 기타 호환 가능한 MCP 클라이언트를 사용하여 자연어로 SingleStore와 상호 작용할 수 있으므로 복잡한 작업을 손쉽게 수행할 수 있습니다.

💡 팁: MCP 서버로 무엇을 할 수 있는지 궁금하신가요? 채팅에서 /help 프롬프트를 호출해 보세요!

요구 사항

• Python >= v3.10.0

• 파이썬 환경에 설치된 uvx

• VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose 또는 기타 MCP 클라이언트

Related MCP server: ExecuteAutomation Database Server

시작하기

시작하기

먼저 클라이언트에 SingleStore MCP 서버를 설치합니다.

표준 구성은 대부분의 도구에서 작동합니다:

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "uvx",
      "args": [
        "singlestore-mcp-server",
        "start"
      ]
    }
  }
}

API 키, 토큰 또는 환경 변수가 필요하지 않습니다! 서버가 시작되면 브라우저 OAuth를 통해 인증을 자동으로 처리합니다.

자동 설정:

uvx singlestore-mcp-server init --client=claude-desktop

수동 설정: MCP 설치 가이드를 따르고 위의 표준 구성을 사용하세요.

자동 설정:

uvx singlestore-mcp-server init --client=claude-code

이 명령은 Claude CLI 명령을 자동으로 실행합니다.

수동 설정:

claude mcp add singlestore-mcp-server uvx singlestore-mcp-server start

자동 설정:

uvx singlestore-mcp-server init --client=cursor

수동 설정: Cursor Settings -> MCP -> Add new MCP Server로 이동합니다. 원하는 이름을 지정하고 command 유형을 선택한 후 uvx singlestore-mcp-server start 명령을 사용합니다. Edit을 클릭하여 구성을 확인하거나 명령줄 인수를 추가할 수도 있습니다.

자동 설정:

uvx singlestore-mcp-server init --client=vscode

수동 설정: MCP 설치 가이드를 따르고 위의 표준 구성을 사용하세요. VS Code CLI를 사용하여 설치할 수도 있습니다:

code --add-mcp '{"name":"singlestore-mcp-server","command":"uvx","args":["singlestore-mcp-server","start"]}'

설치 후, SingleStore MCP 서버를 VS Code의 GitHub Copilot 에이전트와 함께 사용할 수 있습니다.

자동 설정:

uvx singlestore-mcp-server init --client=windsurf

수동 설정: Windsurf MCP 문서를 따르세요. 위의 표준 구성을 사용하세요.

자동 설정:

uvx singlestore-mcp-server init --client=gemini

수동 설정: MCP 설치 가이드를 따르고 위의 표준 구성을 사용하세요.

자동 설정:

uvx singlestore-mcp-server init --client=lm-studio

수동 설정: 오른쪽 사이드바의 Program -> Install -> Edit mcp.json으로 이동합니다. 위의 표준 구성을 사용하세요.

수동 설정 전용: Advanced settings -> Extensions -> Add custom extension으로 이동합니다. 원하는 이름을 지정하고 STDIO 유형을 선택한 후 command를 uvx singlestore-mcp-server start로 설정합니다. "Add Extension"을 클릭합니다.

수동 설정 전용: VSCode 또는 IntelliJ에서 Qodo Gen 채팅 패널을 열고 → Connect more tools → + Add new MCP → 위의 표준 구성을 붙여넣습니다.

Save를 클릭합니다.

Docker 사용

참고: Docker 컨테이너에서 실행되는 서버는 OAuth 흐름을 지원하지 않으므로 Docker 사용 시 API 키가 필요합니다.

{
  "mcpServers": {
    "singlestore-mcp-server": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--init", "--pull=always",
        "-e", "MCP_API_KEY=your_api_key_here",
        "singlestore/mcp-server-singlestore"
      ]
    }
  }
}

Docker 이미지를 직접 빌드할 수 있습니다:

docker build -t singlestore/mcp-server-singlestore .

보안을 강화하려면 Docker Desktop을 사용하여 SingleStore MCP 서버를 구성하는 것이 좋습니다. Docker의 새로운 MCP 카탈로그에 대한 자세한 내용은 이 블로그 게시물을 참조하세요.

구성 요소

도구

서버는 다음 도구를 구현합니다:

• get_user_info: 현재 사용자에 대한 세부 정보 검색

  • 인수 필요 없음

  • 사용자 정보 및 세부 정보 반환

• organization_info: 사용자의 현재 조직에 대한 세부 정보 검색

  • 인수 필요 없음

  • 조직 세부 정보 반환

• choose_organization: 사용 가능한 조직 중에서 선택 (API 키 환경 변수가 설정되지 않은 경우에만 사용 가능)

  • 인수 필요 없음

  • 선택 가능한 사용 가능한 조직 목록 반환

• set_organization: 활성 조직 설정 (API 키 환경 변수가 설정되지 않은 경우에만 사용 가능)

  • 인수: organization_id (문자열)

  • 지정된 조직을 활성 상태로 설정

• workspace_groups_info: 사용자가 액세스할 수 있는 워크스페이스 그룹에 대한 세부 정보 검색

  • 인수 필요 없음

  • 워크스페이스 그룹 세부 정보 반환

• workspaces_info: 특정 워크스페이스 그룹 내의 워크스페이스에 대한 세부 정보 검색

  • 인수: workspace_group_id (문자열)

  • 워크스페이스 세부 정보 반환

• resume_workspace: 일시 중단된 워크스페이스 재개

  • 인수: workspace_id (문자열)

  • 지정된 워크스페이스 재개

• list_starter_workspaces: 사용자가 액세스할 수 있는 모든 스타터 워크스페이스 나열

  • 인수 필요 없음

  • 사용 가능한 스타터 워크스페이스 세부 정보 반환

• create_starter_workspace: 새로운 스타터 워크스페이스 생성

  • 인수: 워크스페이스 구성 매개변수

  • 생성된 스타터 워크스페이스 세부 정보 반환

• terminate_starter_workspace: 기존 스타터 워크스페이스 종료

  • 인수: workspace_id (문자열)

  • 지정된 스타터 워크스페이스 종료

• list_regions: 워크스페이스를 지원하는 모든 리전 목록 검색

  • 인수 필요 없음

  • 사용 가능한 리전 목록 반환

• list_sharedtier_regions: 공유 계층 리전 목록 검색

  • 인수 필요 없음

  • 공유 계층 리전 목록 반환

• run_sql: 연결된 워크스페이스에서 SQL 작업 실행

  • 인수: workspace_id, database, sql_query 및 연결 매개변수

  • 구조화된 형식으로 SQL 쿼리 결과 반환

• create_notebook_file: SingleStore Spaces에 새 노트북 파일 생성

  • 인수: notebook_name, content (선택 사항)

  • 생성된 노트북 세부 정보 반환

• upload_notebook_file: SingleStore Spaces에 노트북 파일 업로드

  • 인수: file_path, notebook_name

  • 업로드된 노트북 세부 정보 반환

• create_job_from_notebook: 노트북에서 예약된 작업 생성

  • 인수: notebook_path, schedule_mode 등을 포함한 작업 구성

  • 생성된 작업 세부 정보 반환

• get_job: 기존 작업의 세부 정보 검색

  • 인수: job_id (문자열)

  • 지정된 작업의 세부 정보 반환

• delete_job: 기존 작업 삭제

  • 인수: job_id (문자열)

  • 지정된 작업 삭제

• stage_list_files: Stage 배포의 파일 시스템에 있는 파일 및 폴더 나열

  • 인수: deployment_id (문자열), path (문자열, 선택 사항)

  • 파일 및 하위 폴더를 포함한 폴더 내용 반환

• stage_get_file: 경로를 통해 Stage에서 파일 가져오기

  • 인수: deployment_id (문자열), path (문자열), return_type (문자열: 'metadata', 'url' 또는 'content')

  • 파일 메타데이터, 다운로드 URL 또는 텍스트 콘텐츠 반환

• stage_create_folder: Stage에 폴더 생성

  • 인수: deployment_id (문자열), path (문자열)

  • 생성 상태 반환

• stage_upload_file: 텍스트 콘텐츠와 함께 Stage에 파일 업로드

  • 인수: deployment_id (문자열), path (문자열), content (문자열), local_path (문자열)

  • 업로드 상태 반환

• stage_move: Stage에서 파일 또는 폴더 이동 또는 이름 변경

  • 인수: deployment_id (문자열), source_path (문자열), destination_path (문자열)

  • 이동 상태 반환

• stage_delete: Stage에서 파일 또는 폴더 삭제

  • 인수: deployment_id (문자열), path (문자열)

  • 삭제 상태 반환

참고: 조직 관리 도구(choose_organization 및 set_organization)는 API 키 환경 변수가 설정되지 않은 경우에만 사용할 수 있으며, OAuth 인증 중에 대화형 조직 선택이 가능합니다.

개발

필수 조건

• Python >= 3.11

• 종속성 관리를 위한 uv

설정

1. 저장소 복제:

git clone https://github.com/singlestore-labs/mcp-server-singlestore.git
cd mcp-server-singlestore

1. 종속성 설치:

uv sync --dev

1. 사전 커밋 훅 설정 (선택 사항이지만 권장됨):

uv run pre-commit install

개발 워크플로우

# Quick quality checks (fast feedback)
./scripts/check.sh

# Run tests independently
./scripts/test.sh

# Comprehensive validation (before PRs)
./scripts/check-all.sh

# Create and publish releases
./scripts/release.sh

테스트 실행

# Run test suite with coverage
./scripts/test.sh

# Or use pytest directly
uv run pytest
uv run pytest --cov=src --cov-report=html

코드 품질

린팅 및 포맷팅을 위해 Ruff를 사용합니다:

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Lint and fix issues automatically
uv run ruff check --fix src/ tests/

릴리스 프로세스

릴리스는 git 태그와 자동화된 PyPI 게시를 통해 관리됩니다:

1. 릴리스 생성: ./scripts/release.sh (대화형 도구)

2. 자동 게시: 버전 태그 푸시로 트리거됨

3. 수동 PyPI 업로드 없음 - 완전히 자동화된 파이프라인

자세한 워크플로우 문서는 scripts/dev-workflow.md를 참조하세요.