StarRocks MCP Server

Servidor MCP Oficial de StarRocks

El Servidor MCP de StarRocks actúa como un puente entre los asistentes de IA y las bases de datos StarRocks. Permite la ejecución directa de SQL, la exploración de bases de datos, la visualización de datos mediante gráficos y la obtención de resúmenes detallados de esquemas/datos sin necesidad de una configuración compleja del lado del cliente.

Características

• Ejecución Directa de SQL: Ejecuta consultas SELECT (read_query) y comandos DDL/DML (write_query).
• Exploración de Bases de Datos: Lista bases de datos y tablas, recupera esquemas de tablas (recursos starrocks://).
• Información del Sistema: Accede a métricas y estados internos de StarRocks a través de la ruta de recurso proc://.
• Resúmenes Detallados: Obtén resúmenes completos de tablas (table_overview) o bases de datos enteras (db_overview), incluyendo definiciones de columnas, conteo de filas y datos de muestra.
• Visualización de Datos: Ejecuta una consulta y genera un gráfico Plotly directamente a partir de los resultados (query_and_plotly_chart).
• Caché Inteligente: Los resúmenes de tablas y bases de datos se almacenan en caché en memoria para acelerar las solicitudes repetidas. La caché se puede omitir cuando sea necesario.
• Configuración Flexible: Establece los detalles de conexión y el comportamiento mediante variables de entorno.

Prerrequisitos

• Python 3.11 o más reciente.
• Un clúster StarRocks accesible (servicio FE). Por defecto, el servidor se conecta a localhost:9030 a través del protocolo MySQL.
• uv — un gestor rápido de paquetes y proyectos Python (un reemplazo moderno para pip + virtualenv) de Astral. Este proyecto usa uv para resolver dependencias, crear el entorno virtual y lanzar el servidor. Los comandos uv run a lo largo de este README crean automáticamente un entorno aislado e instalan las dependencias necesarias en el primer uso, por lo que no se necesita un paso manual de pip install.

Instalando uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

Consulta la guía oficial de instalación de uv para otras opciones. Después de instalar, verifica que esté en tu PATH:

uv --version

Instalación

Generalmente no necesitas instalar el paquete manualmente — el host MCP lo lanza por ti a través de uv (consulta Configuración más abajo). uv obtiene el paquete y sus dependencias bajo demanda.

Para ejecutarlo directamente para pruebas o desarrollo:

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

Configuración

El servidor MCP se ejecuta típicamente a través de un host MCP. La configuración se pasa al host, especificando cómo lanzar el proceso del servidor MCP de StarRocks.

Usando HTTP Transmisible (recomendado):

Para iniciar el servidor en modo HTTP Transmisible:

Primero prueba que la conexión a StarRocks esté bien (9030 es el puerto del protocolo MySQL de StarRocks, no el puerto del servidor HTTP):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

Inicia el servidor:

uv run mcp-server-starrocks --mode streamable-http --port 8000

Luego configura el MCP así:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Usando uv con paquete instalado (variables de entorno individuales):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Usando uv con paquete instalado (URL de conexión):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Usando uv con directorio local (para desarrollo):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Usando uv con directorio local y URL de conexión:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Argumentos de Línea de Comandos:

El servidor soporta los siguientes argumentos de línea de comandos:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Modo de transporte (por defecto: stdio o variable de entorno MCP_TRANSPORT_MODE)
• --host HOST: Host del servidor para modos HTTP (por defecto: localhost)
• --port PORT: Puerto del servidor para modos HTTP
• --test: Ejecutar en modo de prueba para verificar la funcionalidad

Ejemplos:

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test

• El campo url debe apuntar al endpoint HTTP Transmisible de tu servidor MCP (ajusta host/puerto según sea necesario).
• Con esta configuración, los clientes pueden interactuar con el servidor usando JSON estándar sobre solicitudes HTTP POST. No se requiere un SDK especial.
• Todas las APIs de herramientas aceptan y devuelven JSON estándar como se describe arriba.

Nota: El modo sse (Eventos Enviados por el Servidor) está obsoleto y ya no recibe mantenimiento. Por favor, usa el modo HTTP Transmisible para todas las nuevas integraciones.

Variables de Entorno:

Configuración de Conexión

Puedes configurar la conexión a StarRocks usando variables de entorno individuales o una única URL de conexión:

Opción 1: Variables de Entorno Individuales

• STARROCKS_HOST: (Opcional) Nombre de host o dirección IP del servicio FE de StarRocks. Por defecto localhost.
• STARROCKS_PORT: (Opcional) Puerto del protocolo MySQL del servicio FE de StarRocks. Por defecto 9030.
• STARROCKS_USER: (Opcional) Nombre de usuario de StarRocks. Por defecto root.
• STARROCKS_PASSWORD: (Opcional) Contraseña de StarRocks. Por defecto cadena vacía.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Opcional, solo macOS) Nombre del servicio de contraseña genérica a usar al leer la contraseña del Llavero. Esto solo se usa cuando no se proporciona una contraseña explícita a través de STARROCKS_PASSWORD o STARROCKS_URL.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Opcional, solo macOS) Nombre de cuenta de contraseña genérica a usar al leer la contraseña del Llavero. Por defecto el usuario de StarRocks resuelto.
• STARROCKS_DB: (Opcional) Base de datos por defecto a usar si no se especifica en los argumentos de la herramienta o URIs de recurso. Si se establece, la conexión intentará USE esta base de datos. Herramientas como table_overview y db_overview la usarán si se omite la parte de la base de datos en sus argumentos. Por defecto vacío (sin base de datos por defecto).

Opción 2: URL de Conexión (tiene prioridad sobre las variables individuales)

• STARROCKS_URL: (Opcional) Una cadena de URL de conexión que contiene todos los parámetros de conexión en una sola variable. Formato: [<schema>://]user:password@host:port/database. La parte del esquema es opcional. Cuando esta variable está configurada, tiene prioridad sobre las variables individuales STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD y STARROCKS_DB.

  Ejemplos:

  • root:mypass@localhost:9030/test_db
  • mysql://admin:[email protected]:9030/production
  • starrocks://user:[email protected]:9030/analytics

Prioridad de la contraseña:

• Una contraseña incrustada en STARROCKS_URL gana, incluyendo una contraseña vacía explícita como user:@host:9030/db.
• Si STARROCKS_URL omite la contraseña, se usa STARROCKS_PASSWORD cuando está configurada.
• Si no se establece ninguna fuente de contraseña explícita y STARROCKS_PASSWORD_KEYCHAIN_SERVICE está configurado, la contraseña se lee del Llavero de macOS.

Ejemplo de Llavero de macOS

Almacena la contraseña:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

Verifica la contraseña almacenada:

security find-generic-password -a root -s mcp-server-starrocks -w

Úsala con este servidor:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

Configuración Adicional

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Opcional) Puerto Arrow Flight SQL del servicio FE de StarRocks. Cuando se establece, el servidor se conecta usando el protocolo Arrow Flight SQL de alto rendimiento (a través de controladores ADBC) en lugar del protocolo MySQL estándar. Déjalo sin configurar para usar la conexión MySQL por defecto. El host, usuario y contraseña se toman de la misma configuración de conexión descrita anteriormente.

• STARROCKS_OVERVIEW_LIMIT: (Opcional) Un límite de caracteres aproximado para el texto total generado por las herramientas de resumen (table_overview, db_overview) al obtener datos para poblar la caché. Esto ayuda a prevenir el uso excesivo de memoria para esquemas muy grandes o numerosas tablas. Por defecto 20000.

• STARROCKS_MCP_OUTPUT_DIR: (Opcional) Directorio usado por read_query cuando su argumento output_file es una ruta relativa. Por defecto ~/.mcp-server-starrocks/output/. El directorio se crea bajo demanda. Las rutas absolutas pasadas a output_file (incluyendo rutas con prefijo ~) omiten esta configuración. Nota: los archivos se escriben en la máquina donde se ejecuta el servidor MCP. Para Claude Code / Claude Desktop el servidor se ejecuta localmente, por lo que los archivos se guardan en tu equipo. Para despliegues remotos/http el archivo se guarda en el servidor, no en el cliente.

• STARROCKS_MYSQL_AUTH_PLUGIN: (Opcional) Especifica el plugin de autenticación a usar al conectarse al servicio FE de StarRocks. Por ejemplo, configúralo como mysql_clear_password si tu despliegue de StarRocks requiere autenticación de contraseña en texto claro (como cuando se usan ciertas configuraciones LDAP o de autenticación externa). Solo configúralo si tu entorno lo requiere específicamente; de lo contrario, se usa el auth_plugin por defecto.

• MCP_TRANSPORT_MODE: (Opcional) Modo de comunicación que especifica cómo el Servidor MCP expone sus servicios. Opciones disponibles:

  • stdio (por defecto): Se comunica a través de entrada/salida estándar, adecuado para alojamiento de Host MCP.
  • streamable-http (HTTP Transmisible): Inicia como un Servidor HTTP Transmisible, soportando llamadas API RESTful.
  • sse: (Obsoleto, no recomendado) Inicia en modo de transmisión de Eventos Enviados por el Servidor (SSE), adecuado para escenarios que requieren respuestas de transmisión. Nota: El modo SSE ya no recibe mantenimiento, se recomienda usar el modo HTTP Transmisible de manera uniforme.

Componentes

Herramientas

• read_query

  • Descripción: Ejecuta una consulta SELECT u otros comandos que devuelven un ResultSet (ej., SHOW, DESCRIBE). Opcionalmente escribe el resultado completo en un archivo local en lugar de devolverlo en línea — útil para resultados demasiado grandes para caber en el contexto del modelo.
  • Entrada:

    {
      "query": "SQL query string",
      "db": "database name (optional, uses default database if not specified)",
      "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
      "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
    }
    

  • Salida: Sin output_file, contenido de texto que contiene los resultados de la consulta en formato similar a CSV con una fila de encabezado y un resumen del conteo de filas. Con output_file, un breve resumen que incluye la ruta absoluta resuelta, el conteo de bytes y el conteo de filas, más una pequeña vista previa. Devuelve un mensaje de error en caso de fallo.

• write_query

  • Descripción: Ejecuta un comando DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) u otro comando de StarRocks que no devuelve un ResultSet.
  • Entrada:

    {
      "query": "SQL command string",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Salida: Contenido de texto confirmando el éxito (ej., "Query OK, X filas afectadas") o reportando un error. Los cambios se confirman automáticamente en caso de éxito.

• analyze_query

  • Descripción: Analiza una consulta y obtiene el resultado del análisis usando el perfil de consulta o explain analyze.
  • Entrada:

    {
      "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
      "sql": "Query SQL to analyze",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Salida: Contenido de texto que contiene los resultados del análisis de la consulta. Usa ANALYZE PROFILE FROM si se proporciona uuid, de lo contrario usa EXPLAIN ANALYZE si se proporciona sql.

• query_and_plotly_chart

  • Descripción: Ejecuta una consulta SQL, carga los resultados en un DataFrame de Pandas y genera un gráfico Plotly usando una expresión Python proporcionada. Diseñado para visualización en interfaces de usuario compatibles.
  • Entrada:

    {
      "query": "SQL query to fetch data",
      "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
      "db": "database name (optional, uses default database if not specified)"
    }
    

  • Salida: Una lista que contiene:
    1. TextContent: Una representación de texto del DataFrame y una nota de que el gráfico es para visualización en la interfaz de usuario.
    2. ImageContent: El gráfico Plotly generado codificado como una imagen PNG en base64 (image/png). Devuelve un mensaje de error de texto en caso de fallo o si la consulta no produce datos.

• table_overview

  • Descripción: Obtiene un resumen de una tabla específica: columnas (de DESCRIBE), conteo total de filas y filas de muestra (LIMIT 3). Usa una caché en memoria a menos que refresh sea verdadero.
  • Entrada:

    {
      "table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
      "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
    }
    

  • Salida: Contenido de texto que contiene el resumen formateado (columnas, conteo de filas, datos de muestra) o un mensaje de error. Los resultados en caché incluyen errores previos si corresponde.

• db_overview

  • Descripción: Obtiene un resumen (columnas, conteo de filas, filas de muestra) para todas las tablas dentro de una base de datos especificada. Usa la caché a nivel de tabla para cada tabla a menos que refresh sea verdadero.
  • Entrada:

    {
      "db": "database_name", // Optional if default database is set.
      "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
    }
    

  • Salida: Contenido de texto que contiene resúmenes concatenados para todas las tablas encontradas en la base de datos, separados por encabezados. Devuelve un mensaje de error si no se puede acceder a la base de datos o no contiene tablas.

Recursos

Recursos Directos

• starrocks:///databases
  • Descripción: Lista todas las bases de datos accesibles para el usuario configurado.
  • Consulta Equivalente: SHOW DATABASES
  • Tipo MIME: text/plain

Plantillas de Recursos

• starrocks:///{db}/{table}/schema

  • Descripción: Obtiene la definición del esquema de una tabla específica.
  • Consulta equivalente: SHOW CREATE TABLE {db}.{table}
  • Tipo MIME: text/plain

• starrocks:///{db}/tables

  • Descripción: Lista todas las tablas dentro de una base de datos específica.
  • Consulta equivalente: SHOW TABLES FROM {db}
  • Tipo MIME: text/plain

• proc:///{+path}

  • Descripción: Accede a la información interna del sistema de StarRocks, similar a /proc de Linux. El parámetro path especifica el nodo de información deseado.
  • Consulta equivalente: SHOW PROC '/{path}'
  • Tipo MIME: text/plain
  • Rutas comunes:
    • /frontends - Información sobre los nodos FE.
    • /backends - Información sobre los nodos BE (para despliegues no nativos de la nube).
    • /compute_nodes - Información sobre los nodos CN (para despliegues nativos de la nube).
    • /dbs - Información sobre las bases de datos.
    • /dbs/<DB_ID> - Información sobre una base de datos específica por ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Información sobre una tabla específica por ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Información de particiones para una tabla.
    • /transactions - Información de transacciones agrupada por base de datos.
    • /transactions/<DB_ID> - Información de transacciones para un ID de base de datos específico.
    • /transactions/<DB_ID>/running - Transacciones en ejecución para un ID de base de datos.
    • /transactions/<DB_ID>/finished - Transacciones finalizadas para un ID de base de datos.
    • /jobs - Información sobre trabajos asíncronos (Cambio de esquema, Rollup, etc.).
    • /statistic - Estadísticas de cada base de datos.
    • /tasks - Información sobre tareas de agentes.
    • /cluster_balance - Información del estado de balanceo de carga.
    • /routine_loads - Información sobre trabajos de Carga Rutinaria.
    • /colocation_group - Información sobre grupos de Colocation Join.
    • /catalog - Información sobre catálogos configurados (ej., Hive, Iceberg).

Prompts

Ninguno definido por este servidor.

Comportamiento de Caché

• Las herramientas table_overview y db_overview utilizan una caché en memoria para almacenar el texto de resumen generado.
• La clave de caché es una tupla de (database_name, table_name).
• Cuando se llama a table_overview, primero verifica la caché. Si existe un resultado y el parámetro refresh es false (predeterminado), el resultado en caché se devuelve inmediatamente. De lo contrario, obtiene los datos de StarRocks, los almacena en la caché y luego los devuelve.
• Cuando se llama a db_overview, lista todas las tablas en la base de datos y luego intenta recuperar el resumen de cada tabla usando la misma lógica de caché que table_overview (verificando primero la caché, obteniendo si es necesario y refresh es false o hay fallo de caché). Si refresh es true para db_overview, fuerza una actualización para todas las tablas en esa base de datos.
• La variable de entorno STARROCKS_OVERVIEW_LIMIT proporciona un objetivo flexible para la longitud máxima de la cadena de resumen generada por tabla al poblar la caché, ayudando a gestionar el uso de memoria.
• Los resultados en caché, incluidos los mensajes de error encontrados durante la obtención original, se almacenan y se devuelven en accesos posteriores a la caché.

Depuración

Después de iniciar el servidor mcp, puede usar el inspector para depurar:

npx @modelcontextprotocol/inspector

Demostración