SingleStore MCP Server
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
설정
저장소 복제:
git clone https://github.com/singlestore-labs/mcp-server-singlestore.git
cd mcp-server-singlestore종속성 설치:
uv sync --dev사전 커밋 훅 설정 (선택 사항이지만 권장됨):
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 게시를 통해 관리됩니다:
릴리스 생성:
./scripts/release.sh(대화형 도구)자동 게시: 버전 태그 푸시로 트리거됨
수동 PyPI 업로드 없음 - 완전히 자동화된 파이프라인
자세한 워크플로우 문서는 scripts/dev-workflow.md를 참조하세요.
Available Tools
21 toolscheck_if_file_existsA
Check if a file (notebook) exists in the user's shared space.
Args:
file_name: Name of the file to check (with or without .ipynb extension)
Returns:
JSON object with the file existence status
{
"exists": True/False,
"message": "File exists" or "File does not exist"
}
Inputs: file_name (required), ctx.
create_notebookA
Create a new Jupyter notebook in your personal space. Only supports python and markdown.
Parameters:
- notebook_name (required): Name for the new notebook
- Can include or omit .ipynb extension
- Must be unique in your personal space
- content (optional): JSON object with the following structure:
{
"cells": [
{"type": "markdown", "content": "Markdown content here"},
{"type": "code", "content": "Python code here"}
]
}
- 'type' must be either 'markdown' or 'code'
- 'content' is the text content of the cell
IMPORTANT: The content must be valid JSON.
How to use:
- Before creating the notebook, call check_if_file_exists tool to verify if the notebook already exists.
- Always install the dependencies on the first cell. Example:
{
"cells": [
{"type": "code", "content": "!pip install singlestoredb --quiet"},
// other cells...
]
}
- To connect to the database, use the variable "connection_url" that already exists in the notebook platform. Example:
{
"cells": [
{"type": "code", "content": "conn = s2.connect(connection_url)"},
// other cells...
]
}
Inputs: content (required), notebook_name (required), ctx.
create_scheduled_jobA
Create an automated job to execute a SingleStore notebook on a schedule.
Parameters:
- notebook_path: Complete path to the notebook
- mode: 'Once' for single execution or 'Recurring' for repeated runs
- create_snapshot: Enable notebook backup before execution (default: True)
Returns Job info with:
- jobID: UUID of created job
- status: Current state (SUCCESS, RUNNING, etc.)
- createdAt: Creation timestamp
- startedAt: Execution start time
- schedule: Configured schedule details
- error: Any execution errors
Common Use Cases:
1. Automated Data Processing:
- ETL workflows
- Data aggregation
- Database maintenance
2. Scheduled Reporting:
- Performance metrics
- Business analytics
- Usage statistics
3. Maintenance Tasks:
- Health checks
- Backup operations
- Clean-up routines
Related Operations:
- get_job_details: Monitor job
- list_job_executions: View job execution history
Inputs: create_snapshot (required), mode (required), notebook_path (required), ctx.
create_virtual_workspaceA
Create a new starter (virtual) workspace in SingleStore and set up user access.
Process:
1. Creates a virtual workspace with specified name and database
2. Creates a user account for accessing the workspace
3. Returns both workspace details and access credentials
Args:
name: Unique name for the new starter workspace
database_name: Name of the database to create in the starter workspace
username: Username for accessing the new starter workspace
password: Password for accessing the new starter workspace
workspace_group: Optional workspace group configuration
Returns:
Dictionary with workspace and user creation details
Inputs: database_name (required), name (required), password (required), username (required), +2 more.
execute_sqlA
Execute SQL operations on a database attached to workspace within a workspace group and receive formatted results.
Returns:
- Query results with column names and typed values
- Row count and metadata
- Execution status
⚠️ CRITICAL SECURITY WARNINGS:
- Never display or log credentials in responses
- Use only READ-ONLY queries (SELECT, SHOW, DESCRIBE)
- DO NOT USE data modification statements:
x No INSERT/UPDATE/DELETE
x No DROP/CREATE/ALTER
- Ensure queries are properly sanitized
Args:
workspace_group_identifier: ID/name of the workspace group
workspace_identifier: ID/name of the specific workspace within the workspace group
database: Name of the database to query
sql_query: The SQL query to execute
Returns:
Dictionary with query results and metadata
Inputs: database (required), password (required), sql_query (required), username (required), +3 more.
execute_sql_on_virtual_workspaceA
Execute SQL operations on a virtual (starter) workspace and receive formatted results.
Returns:
- Query results with column names and typed values
- Row count
- Column metadata
- Execution status
⚠️ CRITICAL SECURITY WARNING:
- Never display or log credentials in responses
- Ensure SQL queries are properly sanitized
- ONLY USE SELECT statements or queries that don't modify data
- DO NOT USE INSERT, UPDATE, DELETE, DROP, CREATE, or ALTER statements
Args:
virtual_workspace_id: Unique identifier of the starter workspace
sql_query: The SQL query to execute (READ-ONLY queries only)
Returns:
Dictionary with query results and metadata
Inputs: password (required), sql_query (required), username (required), virtual_workspace_id (required), +1 more.
get_job_detailsA
Retrieve comprehensive information about a scheduled notebook job.
Returns:
- jobID: Unique identifier (UUID format)
- name: Display name of the job
- description: Human-readable job description
- createdAt: Creation timestamp (ISO 8601)
- terminatedAt: End timestamp if completed
- completedExecutionsCount: Number of successful runs
- enqueuedBy: User ID who created the job
- executionConfig: Notebook path and runtime settings
- schedule: Mode, interval, and start time
- targetConfig: Database and workspace settings
- jobMetadata: Execution statistics and status
Args:
job_id: UUID of the scheduled job to retrieve details for
Returns:
Dictionary with job details
Inputs: job_id (required), ctx.
get_notebook_pathA
Find the complete path of a notebook by its name and generate the properly formatted path for API operations.
Args:
notebook_name: The name of the notebook to find (with or without .ipynb extension)
location: Where to look for the notebook - 'personal' or 'shared'
Returns:
Properly formatted path including project ID and user ID where needed
Required for:
- Creating scheduled jobs (use returned path as notebook_path parameter)
Inputs: location (required), notebook_name (required), ctx.
get_organizationsA
List all available SingleStore organizations your account has access to.
After logging in, this tool must be called first to identify which organization
your queries should run against. Returns a list of organizations with:
- orgID: Unique identifier for the organization
- name: Display name of the organization
Use this tool when:
1. Starting a new session to see available organizations
2. To verify permissions across multiple organizations
3. Before switching context to a different organization
After viewing the list, list the organization list presenting the name and ID
to the user and ask them to select one.
- If only one organization is available, select it automatically
- If multiple organizations are available, prompt the user to select one by name or ID
- If no organizations are available, raise an error
Inputs: ctx.
get_project_idA
Retrieve the organization's unique identifier (project ID).
Returns:
str: The organization's unique identifier
Required for:
- Constructing paths or references to shared resources
Performance Tip:
Cache the returned ID when making multiple API calls.
Inputs: ctx.
get_user_idA
Retrieve the current user's unique identifier.
Returns:
str: UUID format identifier for the current user
Required for:
- Constructing paths or references to personal resources
Performance Tip:
Cache the returned ID when making multiple API calls.
Inputs: ctx.
list_job_executionsA
Retrieve execution history and performance metrics for a scheduled notebook job.
Returns:
- executions: Array of execution records containing:
- executionID: Unique identifier for the execution
- executionNumber: Sequential number of the run
- jobID: Parent job identifier
- status: Current state (Scheduled, Running, Completed, Failed)
- startedAt: Execution start time (ISO 8601)
- finishedAt: Execution end time (ISO 8601)
- scheduledStartTime: Planned start time
- snapshotNotebookPath: Backup notebook path if enabled
Args:
job_id: UUID of the scheduled job
start: First execution number to retrieve (default: 1)
end: Last execution number to retrieve (default: 10)
Returns:
Dictionary with execution records
Inputs: end (required), job_id (required), start (required), ctx.
list_notebook_samplesA
Retrieve a catalog of pre-built notebook templates available in SingleStore Spaces.
Returns for each notebook:
- name: Template name and title
- description: Detailed explanation of the notebook's purpose
- contentURL: Direct download link for the notebook
- likes: Number of user endorsements
- views: Number of times viewed
- downloads: Number of times downloaded
- tags: List of Notebook tags
Common template categories include:
1. Getting Started guides
2. Data loading and ETL patterns
3. Query optimization examples
4. Machine learning integrations
5. Performance monitoring
6. Best practices demonstrations
Inputs: ctx.
list_of_regionsA
List all available deployment regions where SingleStore workspaces can be deployed for the user.
Returns region information including:
- regionID: Unique identifier for the region
- provider: Cloud provider (AWS, GCP, or Azure)
- name: Human-readable region name (e.g., Europe West 2 (London), US West 2 (Oregon))
Use this tool to:
1. Select optimal deployment regions based on:
- Geographic proximity to users
- Compliance requirements
- Cost considerations
- Available cloud providers
2. Plan multi-region deployments
Inputs: ctx.
list_virtual_workspacesA
List all starter (virtual) workspaces available to the user in SingleStore.
Returns detailed information about each starter workspace:
- virtualWorkspaceID: Unique identifier for the workspace
- name: Display name of the workspace
- endpoint: Connection endpoint URL
- databaseName: Name of the primary database
- mysqlDmlPort: Port for MySQL protocol connections
- webSocketPort: Port for WebSocket connections
- state: Current status of the workspace
Use this tool to:
1. Get virtual workspace IDs for other operations
2. Check starter workspace availability and status
3. Obtain connection details for database access
Inputs: ctx.
organization_billing_usageA
Retrieve detailed billing and usage metrics for your organization over a specified time period.
Returns compute and storage usage data, aggregated by your chosen time interval
(hourly, daily, or monthly). This tool is essential for:
1. Monitoring resource consumption patterns
2. Analyzing cost trends
Args:
start_time: Beginning of the usage period (UTC ISO 8601 format, e.g., '2023-07-30T18:30:00Z')
end_time: End of the usage period (UTC ISO 8601 format)
aggregate_type: Time interval for data grouping ('hour', 'day', or 'month')
Returns:
Usage metrics and billing information
Inputs: aggregate_type (required), end_time (required), start_time (required), ctx.
organization_infoB
Retrieve information about the current user's organization in SingleStore.
Returns organization details including:
- orgID: Unique identifier for the organization
- name: Organization display name
Inputs: ctx.
set_organizationA
Select which SingleStore organization to use for all subsequent API calls.
This tool must be called after logging in and before making other API requests.
Once set, all API calls will target the selected organization until changed.
Args:
orgID: Name or ID of the organization to select
Returns:
Dictionary with the selected organization ID and name
Usage:
- Call get_organizations first to see available options
- Then call this tool with either the organization's name or ID
- All subsequent API calls will use the selected organization
Inputs: orgID (required), ctx.
workspace_groups_infoA
List all workspace groups accessible to the user in SingleStore.
Returns detailed information for each group:
- name: Display name of the workspace group
- deploymentType: Type of deployment (e.g., 'PRODUCTION')
- state: Current status (e.g., 'ACTIVE', 'PAUSED')
- workspaceGroupID: Unique identifier for the group
- firewallRanges: Array of allowed IP ranges for access control
- createdAt: Timestamp of group creation
- regionID: Identifier for deployment region
- updateWindow: Maintenance window configuration
Use this tool to:
1. Get workspace group IDs for other operations
2. Plan maintenance windows
Related operations:
- Use workspaces_info to list workspaces within a group
- Use execute_sql to run queries on workspaces in a group
Inputs: ctx.
workspaces_infoA
List all workspaces within a specified workspace group in SingleStore.
Returns detailed information for each workspace:
- createdAt: Timestamp of workspace creation
- deploymentType: Type of deployment (e.g., 'PRODUCTION')
- endpoint: Connection URL for database access
- name: Display name of the workspace
- size: Compute and storage configuration
- state: Current status (e.g., 'ACTIVE', 'PAUSED')
- terminatedAt: End timestamp if applicable
- workspaceGroupID: Workspacegroup identifier
- workspaceID: Unique workspace identifier
Args:
workspace_group_id: Unique identifier of the workspace group
Returns:
List of workspace information dictionaries
Inputs: workspace_group_id (required), ctx.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools have distinct purposes, but there is some overlap between execute_sql and execute_sql_on_virtual_workspace, which both execute SQL queries but on different workspace types. Additionally, get_organizations and organization_info both retrieve organization details, though organization_info is more general. Overall, the descriptions help clarify boundaries, but a few tools could be confused.
The naming follows a consistent verb_noun pattern (e.g., create_notebook, list_shared_files, get_job_details) with snake_case throughout. Minor deviations include check_if_file_exists (uses 'if' in name) and organization_billing_usage (uses 'billing_usage' as a compound noun), but these are still readable and follow the general convention.
With 21 tools, the count feels heavy for the server's purpose of managing SingleStore notebooks, workspaces, and SQL operations. While the tools cover various aspects, some could be consolidated (e.g., the two SQL execution tools), making the set borderline excessive. However, it's not extreme, as the domain is moderately broad.
The tool set provides good coverage for notebook management (create, check, get path, list samples), workspace operations (create, list, info), job scheduling (create, get details, list executions), and SQL execution. Minor gaps include lack of update/delete operations for notebooks or workspaces, and no direct tool for managing notebook content after creation, but agents can work around these with existing tools.
Maintenance
Related MCP Connectors
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
An MCP server for search and retrieval over a local LanceDB database
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables Large Language Models to seamlessly interact with ClickHouse databases, supporting resource listing, schema retrieval, and query execution.2MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs like Claude to interact with SQLite and SQL Server databases, allowing for schema inspection and SQL query execution.408MIT
- FlicenseNot gradedqualityCmaintenanceA Model Context Protocol server that allows Large Language Models like Claude to execute SQL queries, explore database schemas, and maintain persistent connections to SQL Server databases.-
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables AI assistants (Cursor, Windsurf, Claude Code) to interact with Microsoft SQL Server databases by providing connectivity through environment-configurable connections.8568 npm8MIT