Servidor MCP oficial de StarRocks

El servidor MCP de StarRocks actúa como puente entre los asistentes de IA y las bases de datos de 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 recuperación de esquemas/datos detallados sin necesidad de una configuración compleja del lado del cliente.

Características

• Ejecución directa de SQL: ejecutar consultas SELECT ( read_query ) y comandos DDL/DML ( write_query ).

• Exploración de bases de datos: enumerar bases de datos y tablas, recuperar esquemas de tablas (recursos starrocks:// ).

• Información del sistema: acceda a las métricas y estados internos de StarRocks a través de la ruta de recursos proc:// .

• Resúmenes detallados: obtenga resúmenes completos de tablas ( table_overview ) o bases de datos completas ( db_overview ), incluidas definiciones de columnas, recuentos de filas y datos de muestra.

• Visualización de datos: ejecute una consulta y genere un gráfico Plotly directamente a partir de los resultados ( query_and_plotly_chart ).

• Almacenamiento en caché inteligente: Las vistas generales de tablas y bases de datos se almacenan en caché para agilizar las solicitudes repetidas. Es posible omitir el caché cuando sea necesario.

• Configuración flexible: establezca los detalles de la conexión y el comportamiento a través de variables de entorno.

Related MCP server: mcp-server-starrocks

Configuración

El servidor MCP se ejecuta normalmente a través de un host MCP. La configuración se envía al host, especificando cómo iniciar el proceso del servidor MCP de StarRocks.

Usando uv con el paquete instalado:

{
  "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",
        "STARROCKS_OVERVIEW_LIMIT": "default 20000"
      }
    }
  }
}

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",
        "STARROCKS_OVERVIEW_LIMIT": "default 20000"
      }
    }
  }
}

Variables de entorno:

• STARROCKS_HOST : (Opcional) Nombre de host o dirección IP del servicio StarRocks FE. El valor predeterminado es localhost .

• STARROCKS_PORT : (Opcional) Puerto del protocolo MySQL del servicio StarRocks FE. El valor predeterminado es 9030 .

• STARROCKS_USER : (Opcional) Nombre de usuario de StarRocks. El valor predeterminado es root .

• STARROCKS_PASSWORD : (Opcional) Contraseña de StarRocks. El valor predeterminado es una cadena vacía.

• STARROCKS_DB : (Opcional) Base de datos predeterminada que se usará si no se especifica en los argumentos de la herramienta ni en las URI de recursos. Si se configura, 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. El valor predeterminado es vacío (sin base de datos predeterminada).

• STARROCKS_OVERVIEW_LIMIT : (Opcional) Un límite aproximado de caracteres para el texto total generado por las herramientas de vista general ( table_overview , db_overview ) al obtener datos para llenar la caché. Esto ayuda a evitar el uso excesivo de memoria para esquemas muy grandes o numerosas tablas. El valor predeterminado es 20000 .

Componentes

Herramientas

• read_query

  • Descripción: Ejecuta una consulta SELECT u otros comandos que devuelven un ResultSet (por ejemplo, SHOW , DESCRIBE ).

  • Entrada: { "query": "SQL query string" }

  • Salida: Contenido de texto con los resultados de la consulta en formato CSV, incluyendo una fila de encabezado y un resumen del recuento de filas. Devuelve un mensaje de error en caso de error.

• write_query

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

  • Entrada: { "query": "SQL command string" }

  • Salida: Texto que confirma el éxito (p. ej., "Consulta correcta, X filas afectadas") o informa de un error. Los cambios se aplican automáticamente si la consulta se realiza correctamente.

• query_and_plotly_chart

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

  • Aporte:

    {
      "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\")'"
    }

  • Salida: Una lista que contiene:

    1. TextContent : una representación de texto del DataFrame y una nota que indica que el gráfico es para visualización en la interfaz de usuario.

    2. ImageContent : El gráfico de Plotly generado, codificado como imagen PNG base64 ( image/png ). Devuelve un mensaje de error de texto si falla o si la consulta no genera datos.

• table_overview

  • Descripción: Obtiene una descripción general de una tabla específica: columnas (de DESCRIBE ), recuento total de filas y filas de muestra ( LIMIT 3 ). Utiliza una caché en memoria a menos que refresh sea verdadera.

  • Aporte:

    {
      "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 con la descripción general formateada (columnas, recuento de filas, datos de muestra) o un mensaje de error. Los resultados en caché incluyen errores previos, si corresponde.

• db_overview

  • Descripción: Obtiene una visión general (columnas, recuento de filas, filas de muestra) de todas las tablas de una base de datos específica. Utiliza la caché de tabla para cada tabla, a menos que refresh sea verdadera.

  • Aporte:

    {
      "db": "database_name", // Optional if STARROCKS_DB env var 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 con resúmenes concatenados de todas las tablas de la base de datos, separados por encabezados. Devuelve un mensaje de error si no se puede acceder a la base de datos o si no contiene tablas.

Recursos

Recursos directos

• starrocks:///databases

  • Descripción: Enumera 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: Enumera 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 la instrucción /proc de Linux. El parámetro path especifica el nodo de información deseado.

  • Consulta equivalente: SHOW PROC '/{path}'

  • Tipo MIME: text/plain

  • Caminos comunes:

    • /frontends - Información sobre los nodos FE.

    • /backends : información sobre los nodos BE (para implementaciones no nativas de la nube).

    • /compute_nodes : información sobre los nodos CN (para implementaciones nativas 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 partición de una tabla.

    • /transactions - Información de transacciones agrupada por base de datos.

    • /transactions/<DB_ID> - Información de transacción para un ID de base de datos específico.

    • /transactions/<DB_ID>/running : ejecución de transacciones 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 asincrónicos (cambio de esquema, acumulación, etc.).

    • /statistic - Estadísticas para cada base de datos.

    • /tasks - Información sobre las tareas del agente.

    • /cluster_balance - Información sobre el estado del equilibrio de carga.

    • /routine_loads - Información sobre trabajos de carga de rutina.

    • /colocation_group - Información sobre la unión de grupos de colocation.

    • /catalog - Información sobre catálogos configurados (por ejemplo, Hive, Iceberg).

Indicaciones

Ninguno definido por este servidor.

Comportamiento del almacenamiento en caché

• Las herramientas table_overview y db_overview utilizan un caché en memoria para almacenar el texto de descripción general generado.

• La clave de caché es una tupla de (database_name, table_name) .

• Al llamar table_overview , primero se revisa la caché. Si existe un resultado y el parámetro refresh es false (predeterminado), el resultado almacenado en caché se devuelve inmediatamente. De lo contrario, se obtienen los datos de StarRocks, se almacenan en la caché y luego se devuelven.

• Al llamar db_overview , se listan todas las tablas de la base de datos y se intenta obtener la vista general de cada tabla utilizando la misma lógica de caché que table_overview (primero se revisa la caché, se recupera si es necesario y refresh si es false o se produce un error de caché). Si refresh es true para db_overview , se fuerza una actualización de todas las tablas de esa base de datos.

• La variable de entorno STARROCKS_OVERVIEW_LIMIT proporciona un objetivo flexible para la longitud máxima de la cadena de descripción general generada por tabla al completar la memoria caché, lo que ayuda a administrar el uso de la memoria.

• Los resultados almacenados en caché, incluidos los mensajes de error encontrados durante la búsqueda original, se almacenan y se devuelven en los accesos de caché posteriores.

Manifestación