mcp-server-singlestore

SingleStore MCP Server is a server based on the Model Context Protocol (MCP), used to connect large language models (LLMs) with the SingleStore database platform. MCP is a standardized protocol for managing context between LLMs and external systems. This repository provides an installer and an MCP server, enabling Claude Desktop, Claude Code, Cursor, or any MCP-compatible client to interact with SingleStore using natural language, making it easier to perform complex operations.

Purpose: Interact with the SingleStore Management API and services through natural language, simplifying tasks such as database management, workspace operations, SQL execution, Notebook and job management, and Stage file management.

Main capabilities: The server implements a series of tools, including:

• get_user_info: Get current user information, no parameters required.
• organization_info: Get current organization information, no parameters required.
• choose_organization: Select from available organizations (only available when the API key environment variable is not set), no parameters required.
• set_organization: Set the active organization (only available when the API key environment variable is not set), parameter organization_id (string).
• workspace_groups_info: Get information about workspace groups accessible to the user, no parameters required.
• workspaces_info: Get information about workspaces in a specific workspace group, parameter workspace_group_id (string).
• resume_workspace: Resume a paused workspace, parameter workspace_id (string).
• list_starter_workspaces: List all Starter workspaces accessible to the user, no parameters required.
• create_starter_workspace: Create a new Starter workspace, parameters are workspace configuration parameters.
• terminate_starter_workspace: Terminate an existing Starter workspace, parameter workspace_id (string).
• list_regions: Get a list of all regions that support workspaces, no parameters required.
• list_sharedtier_regions: Get a list of shared tier regions, no parameters required.
• run_sql: Execute SQL operations on the connected workspace, parameters workspace_id, database, sql_query, and connection parameters, returning structured query results.
• create_notebook_file: Create a new Notebook file in SingleStore Spaces, parameters notebook_name, content (optional).
• upload_notebook_file: Upload a Notebook file to SingleStore Spaces, parameters file_path, notebook_name.
• create_job_from_notebook: Create a scheduled job from a Notebook, parameters include notebook_path, schedule_mode, and other job configuration.
• get_job: Get details of an existing job, parameter job_id (string).
• delete_job: Delete an existing job, parameter job_id (string).
• stage_list_files: List files and folders in the Stage deployment file system, parameters deployment_id (string), path (string, optional).
• stage_get_file: Get a file from Stage by path, parameters deployment_id (string), path (string), return_type (string: 'metadata', 'url', or 'content'), returning file metadata, download URL, or text content.
• stage_create_folder: Create a folder in Stage, parameters deployment_id (string), path (string).
• stage_upload_file: Upload a file with text content to Stage, parameters deployment_id (string), path (string), content (string), local_path (string).
• stage_move: Move or rename a file or folder in Stage, parameters deployment_id (string), source_path (string), destination_path (string).
• stage_delete: Delete a file or folder from Stage, parameters deployment_id (string), path (string). Note: The organization management tools (choose_organization and set_organization) are only available when the API key environment variable is not set, allowing interactive organization selection during OAuth authentication.

Usage: Prerequisites: Python >= v3.10.0; install uvx in the Python environment; use VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose, or another MCP client. Installation: Available in most tools using the standard configuration. No API key, token, or environment variable required! Authentication is handled automatically via browser OAuth when the server starts.

• Automatic setup: Can automatically run the Claude CLI command.
• Manual setup: Follow the MCP installation guide and use the standard configuration.
• Cursor: Go to Cursor Settings -> MCP -> Add new MCP server, name it, use the command type, with the command uvx singlestore-mcp-server start. You can also verify the configuration by clicking edit or add command-line arguments.
• VS Code: Follow the MCP installation guide and use the standard configuration. You can also install using the VS Code CLI. After installation, the SingleStore MCP server will be available to the GitHub Copilot agent in VS Code.
• Windsurf: Follow the Windsurf MCP documentation and use the standard configuration.
• Other clients: Such as Program sidebar -> Install -> Edit mcp.json, use the standard configuration; or Advanced Settings -> Extensions -> Add custom extension, type STDIO, command uvx singlestore-mcp-server start; or Qodo Gen chat panel -> Connect more tools -> Add new MCP -> paste the standard configuration. Note: When using Docker, an API key is required, because the server running in a Docker container does not support the OAuth flow. You can build the Docker image yourself. For better security, it is recommended to configure the SingleStore MCP server using Docker Desktop.

Development: Use uv for dependency management. Clone the repository, install dependencies, set up the pre-commit hook (optional but recommended). The development workflow uses Ruff for linting and formatting. The release process is managed through git tags and automated PyPI publishing: create a release using ./scripts/release.sh (interactive tool), push the version tag to trigger automatic publishing, with no manual PyPI upload required. See scripts/dev-workflow.md for details.

Use cases: Suitable for developers or data teams who need to manage SingleStore databases, workspaces, organizations, Notebooks, tasks, and Stage files through natural language, especially for users of MCP clients such as Claude Desktop, Cursor, and VS Code.

Limitations: Requires Python >= 3.10.0 and uvx; the Docker method requires an API key and does not support OAuth; the organization management tools are only available when the API key environment variable is not set. Other specific limitations are not provided at this time.