Overview

The SingleStore MCP Server lets natural-language MCP clients (Claude, Cursor, VS Code Copilot Chat, Gemini, etc.) interact with a SingleStore database using the Model Context Protocol (MCP). It runs as a local MCP server process and exposes a set of callable “tools” that translate user intents into authenticated, auditable database operations — queries, schema introspection, and administrative queries — without requiring clients to manage database credentials directly.

By connecting a conversational agent to this MCP server you can ask for complex SQL operations, get schema-aware suggestions, explore tables, and run diagnostics using plain English. The server handles authentication (browser OAuth by default), sessions, and a small toolkit that maps natural-language requests to concrete SingleStore actions.

Features

Seamless MCP integration: Works with any MCP-compatible client (Claude Desktop/Code, Cursor, VS Code, Windsurf, Gemini CLI, LM Studio, Goose, etc.)
OAuth-based authentication in interactive modes; optional API key for headless runs (Docker)
Tools for user/org info, schema discovery, query execution, and query explanation
Local CLI installer and Docker image for isolated deployments
No client-side environment variables required for interactive setups

Installation / Configuration

Prerequisites:

Python >= 3.10
uvx installed in the Python environment (used to run the MCP server wrapper)

Standard MCP server configuration (works for most clients). Add this to your client’s MCP config:

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

Start or initialize client-specific integration (examples):

# Automatic init for Claude Desktop
uvx singlestore-mcp-server init --client=claude-desktop

# Automatic init for Cursor
uvx singlestore-mcp-server init --client=cursor

# Automatic init for VS Code
uvx singlestore-mcp-server init --client=vscode

Docker (headless/containerized) usage:

OAuth browser flow is not available in Docker. You must provide an API key.

Example MCP config that runs the container:

{
  "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"
      ]
    }
  }
}

You can build the image locally:

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

Pro tip: If you want to see what the MCP server can do from your chat client, call the /help prompt.

Available Tools / Resources

The server exposes a set of callable tools that MCP clients can invoke. Typical tools include:

get_user_info
- Returns metadata about the currently authenticated user (name, email, id).
organization_info
- Returns details about the selected organization.
choose_organization
- Interactive listing to select an organization (used when multiple orgs exist and no env API key is provided).
set_organization
- Programmatically set the current organization for the session.
list_databases
- Returns available databases/schemas visible to the user.
list_tables
- Lists tables in a selected database.
describe_table
- Returns column definitions, types, and basic stats for a table.
execute_query
- Runs a SQL query and returns results (with safeguards for long-running or destructive statements).
explain_query
- Returns an execution plan / explanation for a SQL statement.
query_stats / query_history
- Inspect recent or historical queries and performance metrics.
help
- Returns a human-readable list of available prompts and best practices.

Each tool is invoked through MCP’s standard tool/call pattern. Tools are schema-aware — they use introspection to avoid ambiguous or dangerous actions where possible.

Use Cases

Ad-hoc data exploration: “Show me the top 10 customers by revenue in the last 30 days and plot the distribution of order sizes.”
- Agent will list relevant tables, suggest joins, execute a SELECT with ORDER BY and LIMIT, and return results.
Schema discovery & migration help: “Which tables reference customers.customer_id? Suggest an index for queries joining orders to customers.”
- Agent will run describe_table/list_tables and produce index recommendations based on schema and sample queries.
Performance troubleshooting: “Explain why this query is slow: SELECT …”
- Agent runs explain_query and returns an annotated plan with suggestions (indexes, rewrite).
Lightweight admin actions: “Create a read-only user for analytics with access to schema X.”
- Agent can generate and, with confirmation, execute CREATE USER / GRANT statements.
Embedded copiloting in editors: VS Code users can ask for query rewrites or to generate test data and apply migrations without leaving the editor.

Tips & Security

Interactive runs use browser OAuth — no API keys required for local development. For CI / containerized setups, supply MCP_API_KEY and secure it via your secrets manager.
The server may block or require confirmation for destructive SQL (DROP, DELETE without WHERE). Always verify generated SQL before execution.
Log and audit your MCP sessions if you need traceability of automated SQL runs.

Troubleshooting

If the client cannot launch the MCP server, confirm uvx is installed and available on PATH.
For Docker containers, ensure MCP_API_KEY is set when starting the container.
If schema introspection returns incomplete data, verify the authenticated user has appropriate metadata permissions.

For full source, issue tracking, and contribution guidelines, visit the project repository on GitHub: https://github.com/singlestore-labs/mcp-server-singlestore

SingleStore MCP Server: Conversational Database Operations