SingleStore MCP Server

Servidor MCP de SingleStore

[Model Context Protocol]((https://modelcontextprotocol.io/introduction) (MCP) es un protocolo estandarizado diseñado para gestionar el contexto entre modelos de lenguaje de gran tamaño (LLMs) y sistemas externos. Este repositorio proporciona un instalador y un Servidor MCP para SingleStore, permitiendo una integración perfecta.

Con MCP, puedes usar Claude Desktop, Claude Code, Cursor o cualquier cliente MCP compatible para interactuar con SingleStore usando lenguaje natural, facilitando la realización de operaciones complejas sin esfuerzo.

💡 Consejo profesional: ¿No estás seguro de lo que puede hacer el servidor MCP? ¡Simplemente llama al prompt /help en tu chat!

Requisitos

• Python >= v3.10.0
• uvx instalado en tu entorno Python
• VS Code, Cursor, Windsurf, Claude Desktop, Claude Code, Goose o cualquier otro cliente MCP

Primeros pasos

Primeros pasos

Primero, instala el servidor MCP de SingleStore con tu cliente.

La configuración estándar funciona en la mayoría de las herramientas:

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

¡No se requieren claves API, tokens ni variables de entorno! El servidor maneja automáticamente la autenticación mediante OAuth del navegador al iniciarse.

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

Usando Docker

NOTA: Se requiere una clave API al usar Docker porque el flujo OAuth no es compatible con servidores que se ejecutan en contenedores Docker.

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

Puedes construir la imagen Docker tú mismo:

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

Para mayor seguridad, recomendamos usar Docker Desktop para configurar el servidor MCP de SingleStore; consulta esta entrada de blog para más detalles sobre el nuevo Catálogo MCP de Docker.

Componentes

Herramientas

El servidor implementa las siguientes herramientas:

• get_user_info: Recupera detalles sobre el usuario actual

  • No requiere argumentos
  • Devuelve información y detalles del usuario

• organization_info: Recupera detalles sobre la organización actual del usuario

  • No requiere argumentos
  • Devuelve detalles de la organización

• choose_organization: Elige entre las organizaciones disponibles (solo disponible cuando la variable de entorno de clave API no está configurada)

  • No requiere argumentos
  • Devuelve una lista de organizaciones disponibles para elegir

• set_organization: Establece la organización activa (solo disponible cuando la variable de entorno de clave API no está configurada)

  • Argumentos: organization_id (cadena)
  • Establece la organización especificada como activa

• workspace_groups_info: Recupera detalles sobre los grupos de espacios de trabajo accesibles para el usuario

  • No requiere argumentos
  • Devuelve detalles de los grupos de espacios de trabajo

• workspaces_info: Recupera detalles sobre los espacios de trabajo en un grupo de espacios de trabajo específico

  • Argumentos: workspace_group_id (cadena)
  • Devuelve detalles de los espacios de trabajo

• resume_workspace: Reanuda un espacio de trabajo suspendido

  • Argumentos: workspace_id (cadena)
  • Reanuda el espacio de trabajo especificado

• list_starter_workspaces: Lista todos los espacios de trabajo de inicio accesibles para el usuario

  • No requiere argumentos
  • Devuelve detalles de los espacios de trabajo de inicio disponibles

• create_starter_workspace: Crea un nuevo espacio de trabajo de inicio

  • Argumentos: parámetros de configuración del espacio de trabajo
  • Devuelve detalles del espacio de trabajo de inicio creado

• terminate_starter_workspace: Termina un espacio de trabajo de inicio existente

  • Argumentos: workspace_id (cadena)
  • Termina el espacio de trabajo de inicio especificado

• list_regions: Recupera una lista de todas las regiones que admiten espacios de trabajo

  • No requiere argumentos
  • Devuelve una lista de regiones disponibles

• list_sharedtier_regions: Recupera una lista de regiones de nivel compartido

  • No requiere argumentos
  • Devuelve una lista de regiones de nivel compartido

• run_sql: Ejecuta operaciones SQL en un espacio de trabajo conectado

  • Argumentos: workspace_id, database, sql_query y parámetros de conexión
  • Devuelve los resultados de la consulta SQL en un formato estructurado

• create_notebook_file: Crea un nuevo archivo de notebook en SingleStore Spaces

  • Argumentos: notebook_name, content (opcional)
  • Devuelve detalles del notebook creado

• upload_notebook_file: Sube un archivo de notebook a SingleStore Spaces

  • Argumentos: file_path, notebook_name
  • Devuelve detalles del notebook subido

• create_job_from_notebook: Crea un trabajo programado desde un notebook

  • Argumentos: configuración del trabajo incluyendo notebook_path, schedule_mode, etc.
  • Devuelve detalles del trabajo creado

• get_job: Recupera detalles de un trabajo existente

  • Argumentos: job_id (cadena)
  • Devuelve detalles del trabajo especificado

• delete_job: Elimina un trabajo existente

  • Argumentos: job_id (cadena)
  • Elimina el trabajo especificado

• stage_list_files: Lista archivos y carpetas en el sistema de archivos de un despliegue Stage

  • Argumentos: deployment_id (cadena), path (cadena, opcional)
  • Devuelve el contenido de la carpeta incluyendo archivos y subcarpetas

• stage_get_file: Obtiene un archivo de Stage por ruta

  • Argumentos: deployment_id (cadena), path (cadena), return_type (cadena: 'metadata', 'url' o 'content')
  • Devuelve metadatos del archivo, una URL de descarga o contenido de texto

• stage_create_folder: Crea una carpeta en Stage

  • Argumentos: deployment_id (cadena), path (cadena)
  • Devuelve el estado de creación

• stage_upload_file: Sube un archivo a Stage con contenido de texto

  • Argumentos: deployment_id (cadena), path (cadena), content (cadena), local_path (cadena)
  • Devuelve el estado de subida

• stage_move: Mueve o renombra un archivo o carpeta en Stage

  • Argumentos: deployment_id (cadena), source_path (cadena), destination_path (cadena)
  • Devuelve el estado del movimiento

• stage_delete: Elimina un archivo o carpeta de Stage

  • Argumentos: deployment_id (cadena), path (cadena)
  • Devuelve el estado de eliminación

Nota: Las herramientas de gestión de organizaciones (choose_organization y set_organization) solo están disponibles cuando la variable de entorno de clave API no está configurada, permitiendo la selección interactiva de la organización durante la autenticación OAuth.

Desarrollo

Requisitos previos

• Python >= 3.11
• uv para la gestión de dependencias

Configuración

1. Clona el repositorio:

git clone https://github.com/singlestore-labs/mcp-server-singlestore.git
cd mcp-server-singlestore

1. Instala las dependencias:

uv sync --dev

1. Configura los hooks de pre-commit (opcional pero recomendado):

uv run pre-commit install

Flujo de trabajo de desarrollo

# 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

Ejecución de pruebas

# Run test suite with coverage
./scripts/test.sh

# Or use pytest directly
uv run pytest
uv run pytest --cov=src --cov-report=html

Calidad del código

Usamos Ruff tanto para linting como para formateo:

# 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/

Proceso de publicación

Las publicaciones se gestionan mediante etiquetas git y publicación automatizada en PyPI:

1. Crear publicación: ./scripts/release.sh (herramienta interactiva)
2. Publicación automática: Se activa al empujar etiquetas de versión
3. Sin subidas manuales a PyPI - pipeline completamente automatizado

Consulta scripts/dev-workflow.md para obtener documentación detallada del flujo de trabajo.