StarRocks MCP Server

公式

StarRocksと連携する

ドキュメント

StarRocks 公式 MCP サーバー

StarRocks MCP サーバーは、AI アシスタントと StarRocks データベース間のブリッジとして機能します。複雑なクライアント側のセットアップを必要とせずに、直接的な SQL 実行、データベース探索、チャートによるデータ可視化、詳細なスキーマ/データ概要の取得を可能にします。

機能

直接 SQL 実行: SELECT クエリ (read_query) および DDL/DML コマンド (write_query) を実行します。
データベース探索: データベースとテーブルの一覧表示、テーブルスキーマの取得 (starrocks:// リソース)。
システム情報: proc:// リソースパスを介して内部の StarRocks メトリクスと状態にアクセスします。
詳細な概要: 列定義、行数、サンプルデータを含む、テーブル (table_overview) またはデータベース全体 (db_overview) の包括的なサマリーを取得します。
データ可視化: クエリを実行し、結果から直接 Plotly チャートを生成します (query_and_plotly_chart)。
インテリジェントキャッシング: テーブルとデータベースの概要はメモリにキャッシュされ、繰り返しのリクエストを高速化します。必要に応じてキャッシュをバイパスできます。
柔軟な設定: 環境変数を介して接続詳細と動作を設定します。

前提条件

Python 3.11 以降。
到達可能な StarRocks クラスター (FE サービス)。デフォルトでは、サーバーは MySQL プロトコルを介して localhost:9030 に接続します。
uv — Astral 社による高速な Python パッケージおよびプロジェクトマネージャー (pip + virtualenv の現代的な代替)。このプロジェクトは uv を使用して依存関係を解決し、仮想環境を作成し、サーバーを起動します。この README 全体の uv run コマンドは、初回使用時に自動的に分離環境を作成し、必要な依存関係をインストールするため、手動での pip install 手順は不要です。

`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

その他のオプションについては、公式 uv インストールガイドを参照してください。インストール後、PATH にパスが通っていることを確認してください。

uv --version

インストール

通常、パッケージを手動でインストールする必要はありません。MCP ホストが uv を介して起動します (下記の設定を参照)。uv はパッケージとその依存関係をオンデマンドで取得します。

テストまたは開発のために直接実行するには:

# 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

設定

MCP サーバーは通常、MCP ホストを介して実行されます。設定はホストに渡され、StarRocks MCP サーバープロセスを起動する方法を指定します。

Streamable HTTP の使用 (推奨):

サーバーを Streamable HTTP モードで起動するには:

まず、StarRocks への接続が正常であることをテストします (9030 は StarRocks MySQL プロトコルポートであり、HTTP サーバーポートではありません):

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

サーバーを起動します:

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

次に、MCP を次のように設定します:

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

インストール済みパッケージでの uv の使用 (個別の環境変数):

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

インストール済みパッケージでの uv の使用 (接続 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"
      }
    }
  }
}

ローカルディレクトリでの uv の使用 (開発用):

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

ローカルディレクトリと接続 URL での uv の使用:

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

コマンドライン引数:

サーバーは以下のコマンドライン引数をサポートしています:

uv run mcp-server-starrocks --help

--mode {stdio,sse,http,streamable-http}: トランスポートモード (デフォルト: stdio または MCP_TRANSPORT_MODE 環境変数)
--host HOST: HTTP モードのサーバーホスト (デフォルト: localhost)
--port PORT: HTTP モードのサーバーポート
--test: 機能を検証するためにテストモードで実行

例:

# 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

url フィールドは、MCP サーバーの Streamable HTTP エンドポイントを指す必要があります (必要に応じてホスト/ポートを調整してください)。
この設定により、クライアントは標準の JSON over HTTP POST リクエストを使用してサーバーと対話できます。特別な SDK は必要ありません。
すべてのツール API は、上記のように標準の JSON を受け入れ、返します。

注: sse (Server-Sent Events) モードは非推奨であり、メンテナンスされていません。すべての新しい統合には Streamable HTTP モードを使用してください。

環境変数:

接続設定

個別の環境変数または単一の接続 URL を使用して StarRocks 接続を設定できます:

オプション 1: 個別の環境変数

STARROCKS_HOST: (オプション) StarRocks FE サービスのホスト名または IP アドレス。デフォルトは localhost です。
STARROCKS_PORT: (オプション) StarRocks FE サービスの MySQL プロトコルポート。デフォルトは 9030 です。
STARROCKS_USER: (オプション) StarRocks ユーザー名。デフォルトは root です。
STARROCKS_PASSWORD: (オプション) StarRocks パスワード。デフォルトは空文字列です。
STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (オプション、macOS のみ) STARROCKS_PASSWORD または STARROCKS_URL で明示的なパスワードが提供されていない場合に、キーチェーンからパスワードを読み取る際に使用する汎用パスワードサービス名。
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (オプション、macOS のみ) キーチェーンからパスワードを読み取る際に使用する汎用パスワードアカウント名。デフォルトは解決された StarRocks ユーザーです。
STARROCKS_DB: (オプション) ツール引数またはリソース URI で指定されていない場合に使用するデフォルトデータベース。設定されている場合、接続はこのデータベースに USE しようとします。table_overview や db_overview などのツールは、引数でデータベース部分が省略されている場合にこれを使用します。デフォルトは空 (デフォルトデータベースなし) です。

オプション 2: 接続 URL (個別の変数よりも優先されます)

STARROCKS_URL: (オプション) すべての接続パラメータを単一の変数に含む接続 URL 文字列。形式: [<schema>://]user:password@host:port/database。スキーマ部分はオプションです。この変数が設定されている場合、個別の STARROCKS_HOST、STARROCKS_PORT、STARROCKS_USER、STARROCKS_PASSWORD、STARROCKS_DB 変数よりも優先されます。

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

パスワードの優先順位:

STARROCKS_URL に埋め込まれたパスワード (user:@host:9030/db のような明示的な空のパスワードを含む) が優先されます。
STARROCKS_URL がパスワードを省略している場合、STARROCKS_PASSWORD が設定されていれば使用されます。
明示的なパスワードソースがどちらも設定されておらず、STARROCKS_PASSWORD_KEYCHAIN_SERVICE が設定されている場合、パスワードは macOS キーチェーンから読み取られます。

macOS キーチェーンの例

パスワードを保存:

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

保存されたパスワードを確認:

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

このサーバーで使用:

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

追加設定

STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (オプション) StarRocks FE サービスの Arrow Flight SQL ポート。設定すると、サーバーは標準の MySQL プロトコルの代わりに、高性能な Arrow Flight SQL プロトコル (ADBC ドライバー経由) を使用して接続します。デフォルトの MySQL 接続を使用するには、設定しないでください。ホスト、ユーザー、パスワードは、上記と同じ接続設定から取得されます。
STARROCKS_OVERVIEW_LIMIT: (オプション) キャッシュにデータを投入するためにデータを取得する際に、概要ツール (table_overview、db_overview) によって生成されるテキストの_合計_に対する_おおよその_文字数制限。これにより、非常に大きなスキーマや多数のテーブルに対する過剰なメモリ使用を防ぎます。デフォルトは 20000 です。
STARROCKS_MCP_OUTPUT_DIR: (オプション) read_query の output_file 引数が相対パスの場合に使用されるディレクトリ。デフォルトは ~/.mcp-server-starrocks/output/ です。ディレクトリはオンデマンドで作成されます。output_file に渡される絶対パス (~ で始まるパスを含む) は、この設定をバイパスします。注: ファイルは MCP サーバーが実行されているマシンに書き込まれます。Claude Code / Claude Desktop の場合、サーバーはローカルで実行されるため、ファイルはあなたのラップトップに保存されます。リモート/http デプロイメントの場合、ファイルはクライアントではなくサーバーに保存されます。
STARROCKS_MYSQL_AUTH_PLUGIN: (オプション) StarRocks FE サービスに接続する際に使用する認証プラグインを指定します。たとえば、StarRocks デプロイメントでクリアテキストパスワード認証が必要な場合 (特定の LDAP または外部認証設定を使用している場合など) は、mysql_clear_password に設定します。環境で特に必要な場合にのみ設定してください。それ以外の場合は、デフォルトの auth_plugin が使用されます。
MCP_TRANSPORT_MODE: (オプション) MCP サーバーがサービスを公開する方法を指定する通信モード。利用可能なオプション:
- stdio (デフォルト): 標準入出力を介して通信し、MCP ホストのホスティングに適しています。
- streamable-http (Streamable HTTP): Streamable HTTP サーバーとして起動し、RESTful API 呼び出しをサポートします。
- sse: (非推奨、推奨されません) Server-Sent Events (SSE) ストリーミングモードで起動し、ストリーミング応答が必要なシナリオに適しています。注: SSE モードはメンテナンスされていません。一律して Streamable HTTP モードを使用することを推奨します。

コンポーネント

ツール

read_query
- 説明: SELECT クエリ、または ResultSet を返すその他のコマンド (例: SHOW、DESCRIBE) を実行します。オプションで、完全な結果をインラインで返す代わりにローカルファイルに書き込むことができます。これは、モデルコンテキストに収まらないほど大きな結果に役立ちます。
- 入力:
```
{
  "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"
}
```
- 出力: output_file がない場合、ヘッダー行と行数サマリーを含む CSV のような形式のクエリ結果を含むテキストコンテンツ。output_file がある場合、解決された絶対パス、バイト数、行数、および小さなプレビューを含む短いサマリー。失敗した場合はエラーメッセージを返します。
write_query
- 説明: DDL (CREATE、ALTER、DROP)、DML (INSERT、UPDATE、DELETE)、または ResultSet を返さないその他の StarRocks コマンドを実行します。
- 入力:
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- 出力: 成功を確認するテキストコンテンツ (例: "Query OK, X rows affected") またはエラーの報告。成功した場合、変更は自動的にコミットされます。
analyze_query
- 説明: クエリを分析し、クエリプロファイルまたは explain analyze を使用して分析結果を取得します。
- 入力:
```
{
  "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)"
}
```
- 出力: クエリ分析結果を含むテキストコンテンツ。uuid が提供されている場合は ANALYZE PROFILE FROM を使用し、sql が提供されている場合は EXPLAIN ANALYZE を使用します。
query_and_plotly_chart
- 説明: SQL クエリを実行し、結果を Pandas DataFrame にロードし、提供された Python 式を使用して Plotly チャートを生成します。サポートする UI での可視化用に設計されています。
- 入力:
```
{
  "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)"
}
```
- 出力: 以下を含むリスト:
  1. TextContent: DataFrame のテキスト表現と、チャートが UI 表示用であることを示すメモ。
  2. ImageContent: base64 PNG 画像としてエンコードされた生成された Plotly チャート (image/png)。失敗した場合、またはクエリがデータを生成しない場合は、テキストエラーメッセージを返します。
table_overview
- 説明: 特定のテーブルの概要を取得します: 列 (DESCRIBE から)、合計行数、サンプル行 (LIMIT 3)。refresh が true でない限り、メモリ内キャッシュを使用します。
- 入力:
```
{
  "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.
}
```
- 出力: フォーマットされた概要 (列、行数、サンプルデータ) またはエラーメッセージを含むテキストコンテンツ。キャッシュされた結果には、該当する場合、以前のエラーが含まれます。
db_overview
- 説明: 指定されたデータベース内の_すべての_テーブルの概要 (列、行数、サンプル行) を取得します。refresh が true でない限り、各テーブルのテーブルレベルキャッシュを使用します。
- 入力:
```
{
  "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.
}
```
- 出力: データベースで見つかったすべてのテーブルの連結された概要を含むテキストコンテンツ。ヘッダーで区切られます。データベースにアクセスできない場合、またはテーブルが含まれていない場合は、エラーメッセージを返します。

リソース

直接リソース

starrocks:///databases
- 説明: 設定されたユーザーがアクセス可能なすべてのデータベースを一覧表示します。
- 同等のクエリ: SHOW DATABASES
- MIME タイプ: text/plain

リソーステンプレート

starrocks:///{db}/{table}/schema
- 説明: 特定のテーブルのスキーマ定義を取得します。
- 同等のクエリ: SHOW CREATE TABLE {db}.{table}
- MIMEタイプ: text/plain
starrocks:///{db}/tables
- 説明: 特定のデータベース内のすべてのテーブルを一覧表示します。
- 同等のクエリ: SHOW TABLES FROM {db}
- MIMEタイプ: text/plain
proc:///{+path}
- 説明: Linuxの /proc に似た、StarRocksの内部システム情報にアクセスします。path パラメータで目的の情報ノードを指定します。
- 同等のクエリ: SHOW PROC '/{path}'
- MIMEタイプ: text/plain
- 一般的なパス:
  - /frontends - FEノードに関する情報。
  - /backends - BEノードに関する情報（非クラウドネイティブデプロイメント用）。
  - /compute_nodes - CNノードに関する情報（クラウドネイティブデプロイメント用）。
  - /dbs - データベースに関する情報。
  - /dbs/<DB_ID> - IDによる特定のデータベースに関する情報。
  - /dbs/<DB_ID>/<TABLE_ID> - IDによる特定のテーブルに関する情報。
  - /dbs/<DB_ID>/<TABLE_ID>/partitions - テーブルのパーティション情報。
  - /transactions - データベースごとにグループ化されたトランザクション情報。
  - /transactions/<DB_ID> - 特定のデータベースIDのトランザクション情報。
  - /transactions/<DB_ID>/running - データベースIDの実行中のトランザクション。
  - /transactions/<DB_ID>/finished - データベースIDの完了したトランザクション。
  - /jobs - 非同期ジョブ（スキーマ変更、ロールアップなど）に関する情報。
  - /statistic - 各データベースの統計情報。
  - /tasks - エージェントタスクに関する情報。
  - /cluster_balance - ロードバランスステータス情報。
  - /routine_loads - Routine Loadジョブに関する情報。
  - /colocation_group - Colocation Joinグループに関する情報。
  - /catalog - 設定されたカタログ（例：Hive、Iceberg）に関する情報。

プロンプト

このサーバーによって定義されたものはありません。

キャッシュ動作

table_overview および db_overview ツールは、生成された概要テキストを保存するためにインメモリキャッシュを利用します。
キャッシュキーは (database_name, table_name) のタプルです。
table_overview が呼び出されると、最初にキャッシュをチェックします。結果が存在し、refresh パラメータが false（デフォルト）の場合、キャッシュされた結果がすぐに返されます。それ以外の場合は、StarRocksからデータを取得し、キャッシュに保存してから返します。
db_overview が呼び出されると、データベース内のすべてのテーブルを一覧表示し、table_overview と同じキャッシュロジック（最初にキャッシュをチェックし、必要で refresh が false またはキャッシュミスの場合に取得）を使用して、各テーブル の概要を取得しようとします。refresh が true の場合、db_overview に対して、そのデータベース内の_すべての_テーブルの強制更新を行います。
STARROCKS_OVERVIEW_LIMIT 環境変数は、キャッシュを生成する際に_テーブルごとに_生成される概要文字列の最大長の_ソフトターゲット_を提供し、メモリ使用量の管理に役立ちます。
キャッシュされた結果には、元の取得中に発生したエラーメッセージも含めて保存され、後続のキャッシュヒット時に返されます。

デバッグ

mcpサーバーを起動した後、インスペクターを使用してデバッグできます：

npx @modelcontextprotocol/inspector

デモ

MCP Demo Image