StarRocks

Servidor MCP Oficial do StarRocks

O Servidor MCP do StarRocks atua como uma ponte entre assistentes de IA e bancos de dados StarRocks. Ele permite execução direta de SQL, exploração de banco de dados, visualização de dados via gráficos e obtenção de visões gerais detalhadas de esquemas/dados sem exigir configuração complexa no lado do cliente.

Funcionalidades

• Execução Direta de SQL: Executa consultas SELECT (read_query) e comandos DDL/DML (write_query).
• Exploração de Banco de Dados: Lista bancos de dados e tabelas, recupera esquemas de tabelas (recursos starrocks://).
• Informações do Sistema: Acessa métricas e estados internos do StarRocks através do caminho de recurso proc://.
• Visões Gerais Detalhadas: Obtém resumos abrangentes de tabelas (table_overview) ou bancos de dados inteiros (db_overview), incluindo definições de colunas, contagem de linhas e dados de amostra.
• Visualização de Dados: Executa uma consulta e gera um gráfico Plotly diretamente dos resultados (query_and_plotly_chart).
• Cache Inteligente: Visões gerais de tabelas e bancos de dados são armazenadas em cache na memória para acelerar requisições repetidas. O cache pode ser ignorado quando necessário.
• Configuração Flexível: Define detalhes de conexão e comportamento via variáveis de ambiente.

Pré-requisitos

• Python 3.11 ou mais recente.
• Um cluster StarRocks acessível (serviço FE). Por padrão, o servidor conecta-se a localhost:9030 através do protocolo MySQL.
• uv — um gerenciador de pacotes e projetos Python rápido (um substituto moderno para pip + virtualenv) da Astral. Este projeto usa uv para resolver dependências, criar o ambiente virtual e iniciar o servidor. Os comandos uv run ao longo deste README criam automaticamente um ambiente isolado e instalam as dependências necessárias no primeiro uso, portanto, nenhuma etapa manual de pip install é necessária.

Instalando o 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

Consulte o guia oficial de instalação do uv para outras opções. Após a instalação, verifique se ele está no seu PATH:

uv --version

Instalação

Geralmente, você não precisa instalar o pacote manualmente — o host MCP o inicia para você via uv (veja Configuração abaixo). O uv busca o pacote e suas dependências sob demanda.

Para executá-lo diretamente para testes ou desenvolvimento:

# 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

Configuração

O servidor MCP é tipicamente executado através de um host MCP. A configuração é passada para o host, especificando como iniciar o processo do servidor MCP do StarRocks.

Usando HTTP Transmissível (recomendado):

Para iniciar o servidor no modo HTTP Transmissível:

Primeiro, teste se a conexão com o StarRocks está OK (9030 é a porta do protocolo MySQL do StarRocks, não a porta do servidor HTTP):

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

Inicie o servidor:

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

Em seguida, configure o MCP assim:

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

Usando uv com pacote instalado (variáveis de ambiente individuais):

{
  "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 com pacote instalado (URL de conexão):

{
  "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 com diretório local (para desenvolvimento):

{
  "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 com diretório local e URL de conexão:

{
  "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 Linha de Comando:

O servidor suporta os seguintes argumentos de linha de comando:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Modo de transporte (padrão: stdio ou variável de ambiente MCP_TRANSPORT_MODE)
• --host HOST: Host do servidor para modos HTTP (padrão: localhost)
• --port PORT: Porta do servidor para modos HTTP
• --test: Executa em modo de teste para verificar a funcionalidade

Exemplos:

# 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

• O campo url deve apontar para o endpoint HTTP Transmissível do seu servidor MCP (ajuste host/porta conforme necessário).
• Com esta configuração, os clientes podem interagir com o servidor usando JSON padrão através de requisições HTTP POST. Nenhum SDK especial é necessário.
• Todas as APIs de ferramentas aceitam e retornam JSON padrão conforme descrito acima.

Nota: O modo sse (Eventos Enviados pelo Servidor) está obsoleto e não é mais mantido. Use o modo HTTP Transmissível para todas as novas integrações.

Variáveis de Ambiente:

Configuração de Conexão

Você pode configurar a conexão com o StarRocks usando variáveis de ambiente individuais ou uma única URL de conexão:

Opção 1: Variáveis de Ambiente Individuais

• STARROCKS_HOST: (Opcional) Nome do host ou endereço IP do serviço FE do StarRocks. O padrão é localhost.
• STARROCKS_PORT: (Opcional) Porta do protocolo MySQL do serviço FE do StarRocks. O padrão é 9030.
• STARROCKS_USER: (Opcional) Nome de usuário do StarRocks. O padrão é root.
• STARROCKS_PASSWORD: (Opcional) Senha do StarRocks. O padrão é string vazia.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Opcional, somente macOS) Nome do serviço de senha genérica a ser usado ao ler a senha do Keychain. Isso só é usado quando nenhuma senha explícita é fornecida via STARROCKS_PASSWORD ou STARROCKS_URL.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Opcional, somente macOS) Nome da conta de senha genérica a ser usado ao ler a senha do Keychain. O padrão é o usuário StarRocks resolvido.
• STARROCKS_DB: (Opcional) Banco de dados padrão a ser usado se não for especificado nos argumentos da ferramenta ou URIs de recurso. Se definido, a conexão tentará executar USE neste banco de dados. Ferramentas como table_overview e db_overview usarão isso se a parte do banco de dados for omitida em seus argumentos. O padrão é vazio (sem banco de dados padrão).

Opção 2: URL de Conexão (tem precedência sobre variáveis individuais)

• STARROCKS_URL: (Opcional) Uma string de URL de conexão que contém todos os parâmetros de conexão em uma única variável. Formato: [<schema>://]user:password@host:port/database. A parte do esquema é opcional. Quando esta variável é definida, ela tem precedência sobre as variáveis individuais STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD e STARROCKS_DB.

  Exemplos:

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

Precedência de senha:

• Uma senha incorporada em STARROCKS_URL vence, incluindo uma senha vazia explícita como user:@host:9030/db.
• Se STARROCKS_URL omitir a senha, STARROCKS_PASSWORD será usado quando definido.
• Se nenhuma fonte de senha explícita for definida e STARROCKS_PASSWORD_KEYCHAIN_SERVICE estiver configurado, a senha será lida do Keychain do macOS.

Exemplo de Keychain do macOS

Armazene a senha:

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

Verifique a senha armazenada:

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

Use-a com este servidor:

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

Configuração Adicional

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Opcional) Porta Arrow Flight SQL do serviço FE do StarRocks. Quando definida, o servidor conecta-se usando o protocolo Arrow Flight SQL de alto desempenho (via drivers ADBC) em vez do protocolo MySQL padrão. Deixe em branco para usar a conexão MySQL padrão. O host, usuário e senha são obtidos das mesmas configurações de conexão descritas acima.

• STARROCKS_OVERVIEW_LIMIT: (Opcional) Um limite aproximado de caracteres para o texto total gerado pelas ferramentas de visão geral (table_overview, db_overview) ao buscar dados para preencher o cache. Isso ajuda a evitar uso excessivo de memória para esquemas muito grandes ou tabelas numerosas. O padrão é 20000.

• STARROCKS_MCP_OUTPUT_DIR: (Opcional) Diretório usado por read_query quando seu argumento output_file é um caminho relativo. O padrão é ~/.mcp-server-starrocks/output/. O diretório é criado sob demanda. Caminhos absolutos passados para output_file (incluindo caminhos prefixados com ~) ignoram esta configuração. Nota: os arquivos são gravados na máquina onde o servidor MCP é executado. Para Claude Code / Claude Desktop, o servidor é executado localmente, então os arquivos ficam no seu laptop. Para implantações remotas/http, o arquivo fica no servidor, não no cliente.

• STARROCKS_MYSQL_AUTH_PLUGIN: (Opcional) Especifica o plugin de autenticação a ser usado ao conectar-se ao serviço FE do StarRocks. Por exemplo, defina como mysql_clear_password se sua implantação do StarRocks exigir autenticação de senha em texto claro (como ao usar certas configurações LDAP ou de autenticação externa). Defina isso apenas se seu ambiente exigir especificamente; caso contrário, o auth_plugin padrão será usado.

• MCP_TRANSPORT_MODE: (Opcional) Modo de comunicação que especifica como o Servidor MCP expõe seus serviços. Opções disponíveis:

  • stdio (padrão): Comunica-se através de entrada/saída padrão, adequado para hospedagem de Host MCP.
  • streamable-http (HTTP Transmissível): Inicia como um Servidor HTTP Transmissível, suportando chamadas de API RESTful.
  • sse: (Obsoleto, não recomendado) Inicia no modo de streaming de Eventos Enviados pelo Servidor (SSE), adequado para cenários que exigem respostas de streaming. Nota: O modo SSE não é mais mantido, recomenda-se usar o modo HTTP Transmissível uniformemente.

Componentes

Ferramentas

• read_query

  • Descrição: Executa uma consulta SELECT ou outros comandos que retornam um ResultSet (ex., SHOW, DESCRIBE). Opcionalmente, grava o resultado completo em um arquivo local em vez de retorná-lo inline — útil para resultados muito grandes para caber no contexto do 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"
    }
    

  • Saída: Sem output_file, conteúdo de texto contendo os resultados da consulta em formato semelhante a CSV com uma linha de cabeçalho e resumo da contagem de linhas. Com output_file, um breve resumo incluindo o caminho absoluto resolvido, contagem de bytes e contagem de linhas, além de uma pequena prévia. Retorna uma mensagem de erro em caso de falha.

• write_query

  • Descrição: Executa um comando DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) ou outro comando StarRocks que não retorna um ResultSet.
  • Entrada:

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

  • Saída: Conteúdo de texto confirmando o sucesso (ex., "Query OK, X rows affected") ou relatando um erro. As alterações são confirmadas automaticamente em caso de sucesso.

• analyze_query

  • Descrição: Analisa uma consulta e obtém o resultado da análise usando perfil de consulta ou 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)"
    }
    

  • Saída: Conteúdo de texto contendo os resultados da análise da consulta. Usa ANALYZE PROFILE FROM se uuid for fornecido, caso contrário, usa EXPLAIN ANALYZE se sql for fornecido.

• query_and_plotly_chart

  • Descrição: Executa uma consulta SQL, carrega os resultados em um Pandas DataFrame e gera um gráfico Plotly usando uma expressão Python fornecida. Projetado para visualização em UIs compatíveis.
  • 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)"
    }
    

  • Saída: Uma lista contendo:
    1. TextContent: Uma representação textual do DataFrame e uma nota de que o gráfico é para exibição na UI.
    2. ImageContent: O gráfico Plotly gerado, codificado como uma imagem PNG base64 (image/png). Retorna mensagem de erro em texto em caso de falha ou se a consulta não produzir dados.

• table_overview

  • Descrição: Obtém uma visão geral de uma tabela específica: colunas (de DESCRIBE), contagem total de linhas e linhas de amostra (LIMIT 3). Usa um cache em memória, a menos que refresh seja true.
  • 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.
    }
    

  • Saída: Conteúdo de texto contendo a visão geral formatada (colunas, contagem de linhas, dados de amostra) ou uma mensagem de erro. Resultados em cache incluem erros anteriores, se aplicável.

• db_overview

  • Descrição: Obtém uma visão geral (colunas, contagem de linhas, linhas de amostra) para todas as tabelas dentro de um banco de dados especificado. Usa o cache em nível de tabela para cada tabela, a menos que refresh seja true.
  • 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.
    }
    

  • Saída: Conteúdo de texto contendo visões gerais concatenadas para todas as tabelas encontradas no banco de dados, separadas por cabeçalhos. Retorna uma mensagem de erro se o banco de dados não puder ser acessado ou não contiver tabelas.

Recursos

Recursos Diretos

• starrocks:///databases
  • Descrição: Lista todos os bancos de dados acessíveis ao usuário configurado.
  • Consulta Equivalente: SHOW DATABASES
  • Tipo MIME: text/plain

Modelos de Recursos

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

  • Descrição: Obtém a definição do esquema de uma tabela específica.
  • Consulta equivalente: SHOW CREATE TABLE {db}.{table}
  • Tipo MIME: text/plain

• starrocks:///{db}/tables

  • Descrição: Lista todas as tabelas dentro de um banco de dados específico.
  • Consulta equivalente: SHOW TABLES FROM {db}
  • Tipo MIME: text/plain

• proc:///{+path}

  • Descrição: Acessa informações internas do sistema StarRocks, semelhante ao /proc do Linux. O parâmetro path especifica o nó de informação desejado.
  • Consulta equivalente: SHOW PROC '/{path}'
  • Tipo MIME: text/plain
  • Caminhos comuns:
    • /frontends - Informações sobre os nós FE.
    • /backends - Informações sobre os nós BE (para implantações não nativas em nuvem).
    • /compute_nodes - Informações sobre os nós CN (para implantações nativas em nuvem).
    • /dbs - Informações sobre bancos de dados.
    • /dbs/<DB_ID> - Informações sobre um banco de dados específico por ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Informações sobre uma tabela específica por ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Informações de partição para uma tabela.
    • /transactions - Informações de transações agrupadas por banco de dados.
    • /transactions/<DB_ID> - Informações de transações para um ID de banco de dados específico.
    • /transactions/<DB_ID>/running - Transações em execução para um ID de banco de dados.
    • /transactions/<DB_ID>/finished - Transações concluídas para um ID de banco de dados.
    • /jobs - Informações sobre jobs assíncronos (Schema Change, Rollup, etc.).
    • /statistic - Estatísticas para cada banco de dados.
    • /tasks - Informações sobre tarefas de agentes.
    • /cluster_balance - Informações de status de balanceamento de carga.
    • /routine_loads - Informações sobre jobs de Routine Load.
    • /colocation_group - Informações sobre grupos de Colocation Join.
    • /catalog - Informações sobre catálogos configurados (ex.: Hive, Iceberg).

Prompts

Nenhum definido por este servidor.

Comportamento de Cache

• As ferramentas table_overview e db_overview utilizam um cache em memória para armazenar o texto de visão geral gerado.
• A chave do cache é uma tupla de (database_name, table_name).
• Quando table_overview é chamado, ele verifica o cache primeiro. Se um resultado existir e o parâmetro refresh for false (padrão), o resultado em cache é retornado imediatamente. Caso contrário, ele busca os dados do StarRocks, armazena no cache e então os retorna.
• Quando db_overview é chamado, ele lista todas as tabelas no banco de dados e então tenta recuperar a visão geral para cada tabela usando a mesma lógica de cache que table_overview (verificando o cache primeiro, buscando se necessário e refresh for false ou se houver falha no cache). Se refresh for true para db_overview, ele força uma atualização para todas as tabelas naquele banco de dados.
• A variável de ambiente STARROCKS_OVERVIEW_LIMIT fornece um limite flexível para o comprimento máximo da string de visão geral gerada por tabela ao preencher o cache, ajudando a gerenciar o uso de memória.
• Resultados em cache, incluindo quaisquer mensagens de erro encontradas durante a busca original, são armazenados e retornados em acertos de cache subsequentes.

Depuração

Após iniciar o servidor mcp, você pode usar o inspetor para depurar:

npx @modelcontextprotocol/inspector

Demonstração