SingleStore MCP Server

Official MCP server for SingleStore, enabling natural-language access to workspaces, SQL execution, notebooks, jobs, and Stage file management.

Database by SingleStore Labs OAuth2 (browser) or API Key (MCP_API_KEY for Docker) active

GitHub Docs

Overview

The SingleStore MCP Server is the official integration from SingleStore Labs that connects MCP-compatible clients (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, LM Studio, Goose, Qodo Gen) to a SingleStore account. It exposes the SingleStore Management API and SQL execution surface as Model Context Protocol tools, so an LLM agent can discover organizations, manage workspaces, run queries, schedule notebook jobs, and operate on Stage files using natural language.

The server ships roughly 22 tools spanning user and organization management, workspace lifecycle (including starter workspaces and resume), region discovery, SQL execution via run_sql, notebook creation and upload, job scheduling, and a full set of Stage filesystem operations (list, get, create folder, upload, move, delete). Authentication is browser-based OAuth by default, with no API key required for standard local setups; an MCP_API_KEY environment variable is supported for Docker or non-interactive deployments.

It is distributed as a Python package runnable via uvx, with built-in init commands that auto-configure popular MCP clients. The repo is MIT-licensed and maintained by SingleStore Labs.

Tools

Tool	Description
`get_user_info`	Retrieve information about the currently authenticated SingleStore user.
`organization_info`	Return details about the active SingleStore organization.
`choose_organization`	Interactively select an organization (available when MCP_API_KEY is not set).
`set_organization`	Set the active organization for subsequent calls.
`workspace_groups_info`	List workspace groups in the organization.
`workspaces_info`	List workspaces within a workspace group.
`resume_workspace`	Resume a suspended workspace.
`list_starter_workspaces`	List free-tier starter workspaces.
`create_starter_workspace`	Provision a new starter (free-tier) workspace.
`terminate_starter_workspace`	Delete a starter workspace.
`list_regions`	List regions available for standard workspaces.
`list_sharedtier_regions`	List regions available for shared/starter tier.
`run_sql`	Execute SQL operations on a connected workspace and return structured results.
`create_notebook_file`	Create a new notebook file in the workspace.
`upload_notebook_file`	Upload an existing notebook file.
`create_job_from_notebook`	Schedule a job from a notebook file.
`get_job`	Retrieve metadata and status for a scheduled job.
`delete_job`	Delete a scheduled job.
`stage_list_files`	List files in a Stage path.
`stage_get_file`	Download/get a file from Stage.
`stage_create_folder`	Create a folder in Stage.
`stage_upload_file`	Upload a file to Stage.
`stage_move`	Move or rename a file in Stage.
`stage_delete`	Delete a file or folder from Stage.

Setup Guide

Prerequisites

Python >= 3.10
uvx installed (part of the uv Python tooling)
A SingleStore account
A compatible MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI, LM Studio, etc.)

Automatic client setup

The package can configure popular clients for you:

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

Replace claude-desktop with claude-code, cursor, vscode, windsurf, gemini-cli, or lm-studio as needed.

Manual configuration

Add the server to your MCP client config (e.g. claude_desktop_config.json):

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

Authentication

Local (default): The server opens a browser flow for OAuth on first use. No API key needed.
Docker / headless: Set MCP_API_KEY to a SingleStore API key. Note that organization-selection tools are only active when MCP_API_KEY is unset.

Discovering capabilities

Once connected, ask the agent to run the /help prompt to enumerate available tools.

Use Cases

Query SingleStore tables in natural language and have the agent translate prompts into SQL via run_sql.
Provision and manage starter workspaces on the fly for prototyping, then terminate them when done.
Resume suspended workspaces before running scheduled analytics jobs.
Create or upload notebooks and schedule them as recurring jobs without leaving the IDE.
Manage Stage files (uploads, moves, deletes) as part of an ETL or notebook workflow.

Example Prompts

"Show me the top 20 rows from the orders table in my analytics workspace, sorted by total descending."
"Create a new starter workspace named dev-sandbox in the closest US region."
"Resume the prod-analytics workspace and run a count on the events table."
"Upload this notebook to my workspace and schedule it to run daily at 2am UTC."
"List all files under /stage/raw-events/ and delete anything older than last week."

Pros

Official server maintained by SingleStore Labs under the singlestore-labs GitHub org.
Broad tool coverage: SQL, workspace lifecycle, notebooks, jobs, and Stage file management in one server.
Browser OAuth flow means no manual API key handling for typical local setups.
One-line init commands auto-configure most major MCP clients.

Limitations

Requires Python 3.10+ and uvx, which adds setup overhead for non-Python users.
Docker/headless deployments lose interactive organization selection and require an MCP_API_KEY.
Scoped to SingleStore; not a generic SQL MCP server, so it isn't useful for other databases.

Alternatives

PostgreSQL MCP server (reference server) for plain Postgres-style SQL access.
MotherDuck/DuckDB MCP server for analytics on DuckDB/MotherDuck.
ClickHouse MCP server for a comparable real-time analytics database experience.