StarRocks

StarRocks Offizieller MCP-Server

Der StarRocks MCP-Server fungiert als Brücke zwischen KI-Assistenten und StarRocks-Datenbanken. Er ermöglicht die direkte SQL-Ausführung, Datenbankexploration, Datenvisualisierung mittels Diagrammen und das Abrufen detaillierter Schema-/Datenübersichten, ohne dass eine komplexe clientseitige Einrichtung erforderlich ist.

Funktionen

• Direkte SQL-Ausführung: Führen Sie SELECT-Abfragen (read_query) und DDL/DML-Befehle (write_query) aus.
• Datenbankexploration: Datenbanken und Tabellen auflisten, Tabellenschemata abrufen (starrocks://-Ressourcen).
• Systeminformationen: Zugriff auf interne StarRocks-Metriken und -Zustände über den proc://-Ressourcenpfad.
• Detaillierte Übersichten: Umfassende Zusammenfassungen von Tabellen (table_overview) oder ganzen Datenbanken (db_overview) abrufen, einschließlich Spaltendefinitionen, Zeilenanzahl und Beispieldaten.
• Datenvisualisierung: Eine Abfrage ausführen und direkt aus den Ergebnissen ein Plotly-Diagramm generieren (query_and_plotly_chart).
• Intelligentes Caching: Tabellen- und Datenbankübersichten werden im Speicher zwischengespeichert, um wiederholte Anfragen zu beschleunigen. Der Cache kann bei Bedarf umgangen werden.
• Flexible Konfiguration: Verbindungsdetails und Verhalten über Umgebungsvariablen festlegen.

Voraussetzungen

• Python 3.11 oder neuer.
• Ein erreichbarer StarRocks-Cluster (FE-Dienst). Standardmäßig verbindet sich der Server mit localhost:9030 über das MySQL-Protokoll.
• uv — ein schnelles Python-Paket- und Projektverwaltungstool (ein moderner Ersatz für pip + virtualenv) von Astral. Dieses Projekt verwendet uv, um Abhängigkeiten aufzulösen, die virtuelle Umgebung zu erstellen und den Server zu starten. Die uv run-Befehle in dieser README erstellen bei der ersten Verwendung automatisch eine isolierte Umgebung und installieren die erforderlichen Abhängigkeiten, sodass kein manueller pip install-Schritt erforderlich ist.

Installation von 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

Weitere Optionen finden Sie im offiziellen uv-Installationshandbuch. Überprüfen Sie nach der Installation, ob es in Ihrem PATH verfügbar ist:

uv --version

Installation

Sie müssen das Paket in der Regel nicht manuell installieren – der MCP-Host startet es für Sie über uv (siehe Konfiguration unten). uv ruft das Paket und seine Abhängigkeiten bei Bedarf ab.

Um es direkt zu Test- oder Entwicklungszwecken auszuführen:

# 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

Konfiguration

Der MCP-Server wird normalerweise über einen MCP-Host ausgeführt. Die Konfiguration wird an den Host übergeben und gibt an, wie der StarRocks MCP-Serverprozess gestartet werden soll.

Verwendung von Streamable HTTP (empfohlen):

So starten Sie den Server im Streamable-HTTP-Modus:

Testen Sie zunächst, ob die Verbindung zu StarRocks in Ordnung ist (9030 ist der MySQL-Protokollport von StarRocks, nicht der HTTP-Serverport):

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

Starten Sie den Server:

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

Konfigurieren Sie dann MCP wie folgt:

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

Verwendung von uv mit installiertem Paket (einzelne Umgebungsvariablen):

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

Verwendung von uv mit installiertem Paket (Verbindungs-URL):

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

Verwendung von uv mit lokalem Verzeichnis (für die Entwicklung):

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

Verwendung von uv mit lokalem Verzeichnis und Verbindungs-URL:

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

Befehlszeilenargumente:

Der Server unterstützt die folgenden Befehlszeilenargumente:

uv run mcp-server-starrocks --help

• --mode {stdio,sse,http,streamable-http}: Transportmodus (Standard: stdio oder MCP_TRANSPORT_MODE-Umgebungsvariable)
• --host HOST: Server-Host für HTTP-Modi (Standard: localhost)
• --port PORT: Server-Port für HTTP-Modi
• --test: Im Testmodus ausführen, um die Funktionalität zu überprüfen

Beispiele:

# 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

• Das Feld url sollte auf den Streamable-HTTP-Endpunkt Ihres MCP-Servers verweisen (Host/Port nach Bedarf anpassen).
• Mit dieser Konfiguration können Clients über Standard-JSON über HTTP-POST-Anfragen mit dem Server interagieren. Es ist kein spezielles SDK erforderlich.
• Alle Tool-APIs akzeptieren und geben Standard-JSON wie oben beschrieben zurück.

Hinweis: Der sse-Modus (Server-Sent Events) ist veraltet und wird nicht mehr gepflegt. Bitte verwenden Sie für alle neuen Integrationen den Streamable-HTTP-Modus.

Umgebungsvariablen:

Verbindungskonfiguration

Sie können die StarRocks-Verbindung entweder über einzelne Umgebungsvariablen oder eine einzelne Verbindungs-URL konfigurieren:

Option 1: Einzelne Umgebungsvariablen

• STARROCKS_HOST: (Optional) Hostname oder IP-Adresse des StarRocks FE-Dienstes. Standardmäßig localhost.
• STARROCKS_PORT: (Optional) MySQL-Protokollport des StarRocks FE-Dienstes. Standardmäßig 9030.
• STARROCKS_USER: (Optional) StarRocks-Benutzername. Standardmäßig root.
• STARROCKS_PASSWORD: (Optional) StarRocks-Passwort. Standardmäßig leerer String.
• STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Optional, nur macOS) Generischer Passwortdienstname, der beim Lesen des Passworts aus dem Schlüsselbund verwendet werden soll. Dies wird nur verwendet, wenn kein explizites Passwort über STARROCKS_PASSWORD oder STARROCKS_URL angegeben wird.
• STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Optional, nur macOS) Generischer Passwortkontoname, der beim Lesen des Passworts aus dem Schlüsselbund verwendet werden soll. Standardmäßig der aufgelöste StarRocks-Benutzer.
• STARROCKS_DB: (Optional) Standarddatenbank, die verwendet werden soll, wenn sie nicht in Tool-Argumenten oder Ressourcen-URIs angegeben ist. Falls gesetzt, versucht die Verbindung, ein USE für diese Datenbank durchzuführen. Tools wie table_overview und db_overview verwenden diese, wenn der Datenbankteil in ihren Argumenten weggelassen wird. Standardmäßig leer (keine Standarddatenbank).

Option 2: Verbindungs-URL (hat Vorrang vor einzelnen Variablen)

• STARROCKS_URL: (Optional) Eine Verbindungs-URL-Zeichenfolge, die alle Verbindungsparameter in einer einzigen Variablen enthält. Format: [<schema>://]user:password@host:port/database. Der Schema-Teil ist optional. Wenn diese Variable gesetzt ist, hat sie Vorrang vor den einzelnen Variablen STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD und STARROCKS_DB.

  Beispiele:

  • root:mypass@localhost:9030/test_db
  • mysql://admin:secret@db.example.com:9030/production
  • starrocks://user:pass@192.168.1.100:9030/analytics

Passwort-Vorrang:

• Ein in STARROCKS_URL eingebettetes Passwort gewinnt, einschließlich eines explizit leeren Passworts wie user:@host:9030/db.
• Wenn STARROCKS_URL das Passwort weglässt, wird STARROCKS_PASSWORD verwendet, falls gesetzt.
• Wenn keine explizite Passwortquelle gesetzt ist und STARROCKS_PASSWORD_KEYCHAIN_SERVICE konfiguriert ist, wird das Passwort aus dem macOS-Schlüsselbund gelesen.

macOS-Schlüsselbund-Beispiel

Passwort speichern:

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

Gespeichertes Passwort überprüfen:

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

Mit diesem Server verwenden:

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

Zusätzliche Konfiguration

• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Optional) Arrow Flight SQL-Port des StarRocks FE-Dienstes. Wenn gesetzt, verbindet sich der Server über das leistungsstarke Arrow Flight SQL-Protokoll (über ADBC-Treiber) anstelle des standardmäßigen MySQL-Protokolls. Lassen Sie die Variable ungesetzt, um die standardmäßige MySQL-Verbindung zu verwenden. Host, Benutzer und Passwort werden aus denselben oben beschriebenen Verbindungseinstellungen übernommen.

• STARROCKS_OVERVIEW_LIMIT: (Optional) Ein ungefähres Zeichenlimit für den gesamten Text, der von Übersichts-Tools (table_overview, db_overview) generiert wird, wenn Daten zum Füllen des Caches abgerufen werden. Dies hilft, übermäßige Speichernutzung bei sehr großen Schemata oder zahlreichen Tabellen zu vermeiden. Standardmäßig 20000.

• STARROCKS_MCP_OUTPUT_DIR: (Optional) Verzeichnis, das von read_query verwendet wird, wenn sein output_file-Argument ein relativer Pfad ist. Standardmäßig ~/.mcp-server-starrocks/output/. Das Verzeichnis wird bei Bedarf erstellt. Absolute Pfade, die an output_file übergeben werden (einschließlich Pfaden mit dem Präfix ~), umgehen diese Einstellung. Hinweis: Dateien werden auf dem Rechner geschrieben, auf dem der MCP-Server läuft. Bei Claude Code / Claude Desktop läuft der Server lokal, sodass die Dateien auf Ihrem Laptop landen. Bei Remote-/HTTP-Bereitstellungen landet die Datei auf dem Server, nicht auf dem Client.

• STARROCKS_MYSQL_AUTH_PLUGIN: (Optional) Gibt das Authentifizierungs-Plugin an, das bei der Verbindung mit dem StarRocks FE-Dienst verwendet werden soll. Setzen Sie es beispielsweise auf mysql_clear_password, wenn Ihre StarRocks-Bereitstellung eine Klartext-Passwortauthentifizierung erfordert (z. B. bei Verwendung bestimmter LDAP- oder externer Authentifizierungskonfigurationen). Setzen Sie dies nur, wenn Ihre Umgebung dies ausdrücklich erfordert; andernfalls wird das Standard-Auth-Plugin verwendet.

• MCP_TRANSPORT_MODE: (Optional) Kommunikationsmodus, der angibt, wie der MCP-Server seine Dienste bereitstellt. Verfügbare Optionen:

  • stdio (Standard): Kommuniziert über Standardeingabe/-ausgabe, geeignet für MCP-Host-Hosting.
  • streamable-http (Streamable HTTP): Startet als Streamable HTTP-Server und unterstützt RESTful-API-Aufrufe.
  • sse: (Veraltet, nicht empfohlen) Startet im Server-Sent Events (SSE)-Streaming-Modus, geeignet für Szenarien, die Streaming-Antworten erfordern. Hinweis: Der SSE-Modus wird nicht mehr gepflegt, es wird empfohlen, einheitlich den Streamable-HTTP-Modus zu verwenden.

Komponenten

Tools

• read_query

  • Beschreibung: Führt eine SELECT-Abfrage oder andere Befehle aus, die ein ResultSet zurückgeben (z. B. SHOW, DESCRIBE). Schreibt optional das vollständige Ergebnis in eine lokale Datei, anstatt es inline zurückzugeben – nützlich für Ergebnisse, die zu groß für den Modellkontext sind.
  • Eingabe:

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

  • Ausgabe: Ohne output_file Textinhalt mit den Abfrageergebnissen im CSV-ähnlichen Format mit einer Kopfzeile und einer Zusammenfassung der Zeilenanzahl. Mit output_file eine kurze Zusammenfassung mit dem aufgelösten absoluten Pfad, der Byte-Anzahl und der Zeilenanzahl sowie einer kleinen Vorschau. Gibt bei einem Fehler eine Fehlermeldung zurück.

• write_query

  • Beschreibung: Führt einen DDL- (CREATE, ALTER, DROP), DML- (INSERT, UPDATE, DELETE) oder anderen StarRocks-Befehl aus, der kein ResultSet zurückgibt.
  • Eingabe:

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

  • Ausgabe: Textinhalt, der den Erfolg bestätigt (z. B. "Query OK, X rows affected") oder einen Fehler meldet. Änderungen werden bei Erfolg automatisch festgeschrieben.

• analyze_query

  • Beschreibung: Analysiert eine Abfrage und ruft das Analyseergebnis mithilfe des Abfrageprofils oder Explain Analyze ab.
  • Eingabe:

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

  • Ausgabe: Textinhalt mit den Ergebnissen der Abfrageanalyse. Verwendet ANALYZE PROFILE FROM, wenn eine UUID angegeben ist, andernfalls EXPLAIN ANALYZE, wenn SQL angegeben ist.

• query_and_plotly_chart

  • Beschreibung: Führt eine SQL-Abfrage aus, lädt die Ergebnisse in einen Pandas DataFrame und generiert ein Plotly-Diagramm unter Verwendung eines bereitgestellten Python-Ausdrucks. Konzipiert für die Visualisierung in unterstützenden UIs.
  • Eingabe:

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

  • Ausgabe: Eine Liste mit:
    1. TextContent: Eine Textdarstellung des DataFrames und ein Hinweis, dass das Diagramm für die UI-Anzeige bestimmt ist.
    2. ImageContent: Das generierte Plotly-Diagramm, kodiert als base64-PNG-Bild (image/png). Gibt eine Textfehlermeldung bei einem Fehler zurück oder wenn die Abfrage keine Daten liefert.

• table_overview

  • Beschreibung: Ruft eine Übersicht einer bestimmten Tabelle ab: Spalten (aus DESCRIBE), Gesamtzeilenanzahl und Beispielzeilen (LIMIT 3). Verwendet einen In-Memory-Cache, es sei denn, refresh ist wahr.
  • Eingabe:

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

  • Ausgabe: Textinhalt mit der formatierten Übersicht (Spalten, Zeilenanzahl, Beispieldaten) oder einer Fehlermeldung. Zwischengespeicherte Ergebnisse enthalten gegebenenfalls frühere Fehler.

• db_overview

  • Beschreibung: Ruft eine Übersicht (Spalten, Zeilenanzahl, Beispielzeilen) für alle Tabellen in einer angegebenen Datenbank ab. Verwendet den Cache auf Tabellenebene für jede Tabelle, es sei denn, refresh ist wahr.
  • Eingabe:

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

  • Ausgabe: Textinhalt mit verketteten Übersichten für alle in der Datenbank gefundenen Tabellen, getrennt durch Überschriften. Gibt eine Fehlermeldung zurück, wenn auf die Datenbank nicht zugegriffen werden kann oder sie keine Tabellen enthält.

Ressourcen

Direkte Ressourcen

• starrocks:///databases
  • Beschreibung: Listet alle Datenbanken auf, auf die der konfigurierte Benutzer zugreifen kann.
  • Äquivalente Abfrage: SHOW DATABASES
  • MIME-Typ: text/plain

Ressourcenvorlagen

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

  • Beschreibung: Ruft die Schemadefinition einer bestimmten Tabelle ab.
  • Äquivalente Abfrage: SHOW CREATE TABLE {db}.{table}
  • MIME-Typ: text/plain

• starrocks:///{db}/tables

  • Beschreibung: Listet alle Tabellen innerhalb einer bestimmten Datenbank auf.
  • Äquivalente Abfrage: SHOW TABLES FROM {db}
  • MIME-Typ: text/plain

• proc:///{+path}

  • Beschreibung: Greift auf interne Systeminformationen von StarRocks zu, ähnlich wie Linux /proc. Der Parameter path gibt den gewünschten Informationsknoten an.
  • Äquivalente Abfrage: SHOW PROC '/{path}'
  • MIME-Typ: text/plain
  • Gängige Pfade:
    • /frontends - Informationen über FE-Knoten.
    • /backends - Informationen über BE-Knoten (für nicht cloud-native Bereitstellungen).
    • /compute_nodes - Informationen über CN-Knoten (für cloud-native Bereitstellungen).
    • /dbs - Informationen über Datenbanken.
    • /dbs/<DB_ID> - Informationen über eine bestimmte Datenbank anhand der ID.
    • /dbs/<DB_ID>/<TABLE_ID> - Informationen über eine bestimmte Tabelle anhand der ID.
    • /dbs/<DB_ID>/<TABLE_ID>/partitions - Partitionsinformationen für eine Tabelle.
    • /transactions - Transaktionsinformationen gruppiert nach Datenbank.
    • /transactions/<DB_ID> - Transaktionsinformationen für eine bestimmte Datenbank-ID.
    • /transactions/<DB_ID>/running - Laufende Transaktionen für eine Datenbank-ID.
    • /transactions/<DB_ID>/finished - Abgeschlossene Transaktionen für eine Datenbank-ID.
    • /jobs - Informationen über asynchrone Jobs (Schemaänderung, Rollup usw.).
    • /statistic - Statistiken für jede Datenbank.
    • /tasks - Informationen über Agent-Aufgaben.
    • /cluster_balance - Informationen zum Lastverteilungsstatus.
    • /routine_loads - Informationen über Routine Load-Jobs.
    • /colocation_group - Informationen über Colocation Join-Gruppen.
    • /catalog - Informationen über konfigurierte Kataloge (z. B. Hive, Iceberg).

Prompts

Keine von diesem Server definiert.

Caching-Verhalten

• Die Tools table_overview und db_overview verwenden einen In-Memory-Cache, um den generierten Übersichtstext zu speichern.
• Der Cache-Schlüssel ist ein Tupel aus (database_name, table_name).
• Wenn table_overview aufgerufen wird, prüft es zuerst den Cache. Wenn ein Ergebnis existiert und der Parameter refresh auf false (Standard) gesetzt ist, wird das zwischengespeicherte Ergebnis sofort zurückgegeben. Andernfalls werden die Daten von StarRocks abgerufen, im Cache gespeichert und dann zurückgegeben.
• Wenn db_overview aufgerufen wird, listet es alle Tabellen in der Datenbank auf und versucht dann, die Übersicht für jede Tabelle mit derselben Caching-Logik wie table_overview abzurufen (zuerst Cache prüfen, bei Bedarf abrufen, wenn refresh auf false gesetzt ist oder ein Cache-Fehltreffer vorliegt). Wenn refresh für db_overview auf true gesetzt ist, erzwingt es eine Aktualisierung für alle Tabellen in dieser Datenbank.
• Die Umgebungsvariable STARROCKS_OVERVIEW_LIMIT bietet ein weiches Ziel für die maximale Länge des Übersichtsstrings, der pro Tabelle beim Befüllen des Caches generiert wird, um die Speichernutzung zu steuern.
• Zwischengespeicherte Ergebnisse, einschließlich etwaiger Fehlermeldungen, die beim ursprünglichen Abruf aufgetreten sind, werden gespeichert und bei nachfolgenden Cache-Treffern zurückgegeben.

Debug

Nach dem Start des MCP-Servers können Sie den Inspector zum Debuggen verwenden:

npx @modelcontextprotocol/inspector

Demo