SingleStore MCP Server

SingleStore MCP 서버

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

MCP를 사용하면 Claude Desktop, Claude Code, Cursor 또는 호환되는 모든 MCP 클라이언트에서 자연어로 SingleStore와 상호 작용할 수 있어 복잡한 작업을 손쉽게 수행할 수 있습니다.

💡 프로 팁: MCP 서버가 무엇을 할 수 있는지 잘 모르시겠다면? 채팅에서 /help 프롬프트를 호출해 보세요!

요구 사항

• Python >= v3.10.0
• Python 환경에 uvx 설치
• VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose 또는 기타 MCP 클라이언트

시작하기

시작하기

먼저, 클라이언트에 SingleStore MCP 서버를 설치하세요.

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

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

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

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

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

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

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

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

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

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

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

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

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를 참조하세요.