StarRocks MCP Server

Server MCP Resmi StarRocks

Server MCP StarRocks bertindak sebagai jembatan antara asisten AI dan basis data StarRocks. Server ini memungkinkan eksekusi SQL langsung, eksplorasi basis data, visualisasi data melalui bagan, serta pengambilan ringkasan skema/data yang mendetail tanpa memerlukan pengaturan sisi klien yang rumit.

Fitur

Eksekusi SQL Langsung: Menjalankan kueri SELECT (read_query) dan perintah DDL/DML (write_query).
Eksplorasi Basis Data: Mendaftar basis data dan tabel, mengambil skema tabel (sumber daya starrocks://).
Informasi Sistem: Mengakses metrik dan status internal StarRocks melalui jalur sumber daya proc://.
Ringkasan Mendetail: Mendapatkan ringkasan komprehensif dari tabel (table_overview) atau seluruh basis data (db_overview), termasuk definisi kolom, jumlah baris, dan data sampel.
Visualisasi Data: Mengeksekusi kueri dan menghasilkan bagan Plotly langsung dari hasilnya (query_and_plotly_chart).
Caching Cerdas: Ringkasan tabel dan basis data di-cache di memori untuk mempercepat permintaan berulang. Cache dapat dilewati bila diperlukan.
Konfigurasi Fleksibel: Mengatur detail koneksi dan perilaku melalui variabel lingkungan.

Prasyarat

Python 3.11 atau lebih baru.
Kluster StarRocks yang dapat dijangkau (layanan FE). Secara default, server terhubung ke localhost:9030 melalui protokol MySQL.
uv — pengelola paket dan proyek Python yang cepat (pengganti modern untuk pip + virtualenv) dari Astral. Proyek ini menggunakan uv untuk menyelesaikan dependensi, membuat lingkungan virtual, dan meluncurkan server. Perintah uv run di seluruh README ini secara otomatis membuat lingkungan terisolasi dan menginstal dependensi yang diperlukan pada penggunaan pertama, sehingga tidak diperlukan langkah pip install manual.

Menginstal `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

Lihat panduan instalasi resmi uv untuk opsi lainnya. Setelah menginstal, verifikasi bahwa ia ada di PATH Anda:

uv --version

Instalasi

Anda umumnya tidak perlu menginstal paket secara manual — host MCP meluncurkannya untuk Anda melalui uv (lihat Konfigurasi di bawah). uv mengambil paket dan dependensinya sesuai permintaan.

Untuk menjalankannya secara langsung untuk pengujian atau pengembangan:

# 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

Konfigurasi

Server MCP biasanya dijalankan melalui host MCP. Konfigurasi diteruskan ke host, yang menentukan cara meluncurkan proses server MCP StarRocks.

Menggunakan HTTP Streamable (disarankan):

Untuk memulai server dalam mode HTTP Streamable:

Pertama, uji apakah koneksi ke StarRocks baik-baik saja (9030 adalah port protokol MySQL StarRocks, bukan port server HTTP):

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

Mulai server:

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

Kemudian konfigurasikan MCP seperti ini:

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

Menggunakan uv dengan paket terinstal (variabel lingkungan individual):

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

Menggunakan uv dengan paket terinstal (URL koneksi):

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

Menggunakan uv dengan direktori lokal (untuk pengembangan):

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

Menggunakan uv dengan direktori lokal dan URL koneksi:

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

Argumen Baris Perintah:

Server mendukung argumen baris perintah berikut:

uv run mcp-server-starrocks --help

--mode {stdio,sse,http,streamable-http}: Mode transport (default: stdio atau variabel env MCP_TRANSPORT_MODE)
--host HOST: Host server untuk mode HTTP (default: localhost)
--port PORT: Port server untuk mode HTTP
--test: Jalankan dalam mode uji untuk memverifikasi fungsionalitas

Contoh:

# 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

Bidang url harus menunjuk ke endpoint HTTP Streamable dari server MCP Anda (sesuaikan host/port sesuai kebutuhan).
Dengan konfigurasi ini, klien dapat berinteraksi dengan server menggunakan JSON standar melalui permintaan HTTP POST. Tidak diperlukan SDK khusus.
Semua API alat menerima dan mengembalikan JSON standar seperti yang dijelaskan di atas.

Catatan: Mode sse (Server-Sent Events) sudah usang dan tidak lagi dipelihara. Harap gunakan mode HTTP Streamable untuk semua integrasi baru.

Variabel Lingkungan:

Konfigurasi Koneksi

Anda dapat mengonfigurasi koneksi StarRocks menggunakan variabel lingkungan individual atau URL koneksi tunggal:

Opsi 1: Variabel Lingkungan Individual

STARROCKS_HOST: (Opsional) Nama host atau alamat IP layanan FE StarRocks. Default ke localhost.
STARROCKS_PORT: (Opsional) Port protokol MySQL layanan FE StarRocks. Default ke 9030.
STARROCKS_USER: (Opsional) Nama pengguna StarRocks. Default ke root.
STARROCKS_PASSWORD: (Opsional) Kata sandi StarRocks. Default ke string kosong.
STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Opsional, hanya macOS) Nama layanan kata sandi generik yang digunakan saat membaca kata sandi dari Keychain. Ini hanya digunakan jika tidak ada kata sandi eksplisit yang diberikan melalui STARROCKS_PASSWORD atau STARROCKS_URL.
STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Opsional, hanya macOS) Nama akun kata sandi generik yang digunakan saat membaca kata sandi dari Keychain. Default ke pengguna StarRocks yang diselesaikan.
STARROCKS_DB: (Opsional) Basis data default yang digunakan jika tidak ditentukan dalam argumen alat atau URI sumber daya. Jika diatur, koneksi akan mencoba USE basis data ini. Alat seperti table_overview dan db_overview akan menggunakan ini jika bagian basis data dihilangkan dalam argumennya. Default ke kosong (tidak ada basis data default).

Opsi 2: URL Koneksi (lebih diutamakan daripada variabel individual)

STARROCKS_URL: (Opsional) String URL koneksi yang berisi semua parameter koneksi dalam satu variabel. Format: [<schema>://]user:password@host:port/database. Bagian skema bersifat opsional. Ketika variabel ini diatur, ia lebih diutamakan daripada variabel individual STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD, dan STARROCKS_DB.

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

Prioritas kata sandi:

Kata sandi yang disematkan dalam STARROCKS_URL menang, termasuk kata sandi kosong eksplisit seperti user:@host:9030/db.
Jika STARROCKS_URL menghilangkan kata sandi, STARROCKS_PASSWORD digunakan jika diatur.
Jika tidak ada sumber kata sandi eksplisit yang diatur dan STARROCKS_PASSWORD_KEYCHAIN_SERVICE dikonfigurasi, kata sandi dibaca dari Keychain macOS.

Contoh Keychain macOS

Simpan kata sandi:

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

Verifikasi kata sandi yang disimpan:

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

Gunakan dengan server ini:

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

Konfigurasi Tambahan

STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Opsional) Port Arrow Flight SQL dari layanan FE StarRocks. Ketika diatur, server terhubung menggunakan protokol Arrow Flight SQL berkinerja tinggi (melalui driver ADBC) alih-alih protokol MySQL standar. Biarkan tidak diatur untuk menggunakan koneksi MySQL default. Host, pengguna, dan kata sandi diambil dari pengaturan koneksi yang sama seperti yang dijelaskan di atas.
STARROCKS_OVERVIEW_LIMIT: (Opsional) Batas karakter perkiraan untuk total teks yang dihasilkan oleh alat ringkasan (table_overview, db_overview) saat mengambil data untuk mengisi cache. Ini membantu mencegah penggunaan memori yang berlebihan untuk skema yang sangat besar atau banyak tabel. Default ke 20000.
STARROCKS_MCP_OUTPUT_DIR: (Opsional) Direktori yang digunakan oleh read_query ketika argumen output_file-nya adalah jalur relatif. Default ke ~/.mcp-server-starrocks/output/. Direktori dibuat sesuai permintaan. Jalur absolut yang diteruskan ke output_file (termasuk jalur berawalan ~) melewati pengaturan ini. Catatan: file ditulis di mesin tempat server MCP berjalan. Untuk Claude Code / Claude Desktop, server berjalan secara lokal, sehingga file mendarat di laptop Anda. Untuk penerapan jarak jauh/http, file mendarat di server, bukan klien.
STARROCKS_MYSQL_AUTH_PLUGIN: (Opsional) Menentukan plugin autentikasi yang digunakan saat menghubungkan ke layanan FE StarRocks. Misalnya, atur ke mysql_clear_password jika penerapan StarRocks Anda memerlukan autentikasi kata sandi teks jelas (seperti saat menggunakan pengaturan LDAP atau autentikasi eksternal tertentu). Hanya atur ini jika lingkungan Anda secara spesifik memerlukannya; jika tidak, auth_plugin default digunakan.
MCP_TRANSPORT_MODE: (Opsional) Mode komunikasi yang menentukan bagaimana Server MCP mengekspos layanannya. Opsi yang tersedia:
- stdio (default): Berkomunikasi melalui input/output standar, cocok untuk hosting Host MCP.
- streamable-http (HTTP Streamable): Dimulai sebagai Server HTTP Streamable, mendukung panggilan API RESTful.
- sse: (Usang, tidak disarankan) Dimulai dalam mode streaming Server-Sent Events (SSE), cocok untuk skenario yang memerlukan respons streaming. Catatan: Mode SSE tidak lagi dipelihara, disarankan untuk menggunakan mode HTTP Streamable secara seragam.

Komponen

Alat

read_query
- Deskripsi: Mengeksekusi kueri SELECT atau perintah lain yang mengembalikan ResultSet (mis., SHOW, DESCRIBE). Secara opsional menulis hasil lengkap ke file lokal alih-alih mengembalikannya secara inline — berguna untuk hasil yang terlalu besar untuk muat dalam konteks model.
- Input:
```
{
  "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: Tanpa output_file, konten teks berisi hasil kueri dalam format mirip CSV dengan baris header dan ringkasan jumlah baris. Dengan output_file, ringkasan singkat termasuk jalur absolut yang diselesaikan, jumlah byte, dan jumlah baris, ditambah pratinjau kecil. Mengembalikan pesan kesalahan saat gagal.
write_query
- Deskripsi: Mengeksekusi perintah DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE), atau perintah StarRocks lainnya yang tidak mengembalikan ResultSet.
- Input:
```
{
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
```
- Output: Konten teks yang mengonfirmasi keberhasilan (mis., "Query OK, X rows affected") atau melaporkan kesalahan. Perubahan dikomit secara otomatis saat berhasil.
analyze_query
- Deskripsi: Menganalisis kueri dan mendapatkan hasil analisis menggunakan profil kueri atau explain analyze.
- Input:
```
{
  "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)"
}
```
- Output: Konten teks yang berisi hasil analisis kueri. Menggunakan ANALYZE PROFILE FROM jika uuid disediakan, jika tidak menggunakan EXPLAIN ANALYZE jika sql disediakan.
query_and_plotly_chart
- Deskripsi: Mengeksekusi kueri SQL, memuat hasilnya ke dalam Pandas DataFrame, dan menghasilkan bagan Plotly menggunakan ekspresi Python yang disediakan. Dirancang untuk visualisasi di UI yang mendukung.
- Input:
```
{
  "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)"
}
```
- Output: Daftar yang berisi:
  1. TextContent: Representasi teks dari DataFrame dan catatan bahwa bagan untuk tampilan UI.
  2. ImageContent: Bagan Plotly yang dihasilkan dikodekan sebagai gambar PNG base64 (image/png). Mengembalikan pesan kesalahan teks saat gagal atau jika kueri tidak menghasilkan data.
table_overview
- Deskripsi: Mendapatkan ringkasan tabel tertentu: kolom (dari DESCRIBE), jumlah total baris, dan baris sampel (LIMIT 3). Menggunakan cache dalam memori kecuali refresh bernilai true.
- Input:
```
{
  "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.
}
```
- Output: Konten teks yang berisi ringkasan terformat (kolom, jumlah baris, data sampel) atau pesan kesalahan. Hasil yang di-cache menyertakan kesalahan sebelumnya jika berlaku.
db_overview
- Deskripsi: Mendapatkan ringkasan (kolom, jumlah baris, baris sampel) untuk semua tabel dalam basis data tertentu. Menggunakan cache tingkat tabel untuk setiap tabel kecuali refresh bernilai true.
- Input:
```
{
  "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.
}
```
- Output: Konten teks yang berisi ringkasan gabungan untuk semua tabel yang ditemukan di basis data, dipisahkan oleh header. Mengembalikan pesan kesalahan jika basis data tidak dapat diakses atau tidak berisi tabel.

Sumber Daya

Sumber Daya Langsung

starrocks:///databases
- Deskripsi: Mendaftar semua basis data yang dapat diakses oleh pengguna yang dikonfigurasi.
- Kueri Setara: SHOW DATABASES
- Tipe MIME: text/plain

Templat Sumber Daya

starrocks:///{db}/{table}/schema
- Deskripsi: Mendapatkan definisi skema dari tabel tertentu.
- Kueri Setara: SHOW CREATE TABLE {db}.{table}
- Tipe MIME: text/plain
starrocks:///{db}/tables
- Deskripsi: Mencantumkan semua tabel dalam basis data tertentu.
- Kueri Setara: SHOW TABLES FROM {db}
- Tipe MIME: text/plain
proc:///{+path}
- Deskripsi: Mengakses informasi sistem internal StarRocks, mirip dengan /proc di Linux. Parameter path menentukan simpul informasi yang diinginkan.
- Kueri Setara: SHOW PROC '/{path}'
- Tipe MIME: text/plain
- Jalur Umum:
  - /frontends - Informasi tentang simpul FE.
  - /backends - Informasi tentang simpul BE (untuk deployment non-cloud native).
  - /compute_nodes - Informasi tentang simpul CN (untuk deployment cloud native).
  - /dbs - Informasi tentang basis data.
  - /dbs/<DB_ID> - Informasi tentang basis data tertentu berdasarkan ID.
  - /dbs/<DB_ID>/<TABLE_ID> - Informasi tentang tabel tertentu berdasarkan ID.
  - /dbs/<DB_ID>/<TABLE_ID>/partitions - Informasi partisi untuk sebuah tabel.
  - /transactions - Informasi transaksi yang dikelompokkan berdasarkan basis data.
  - /transactions/<DB_ID> - Informasi transaksi untuk ID basis data tertentu.
  - /transactions/<DB_ID>/running - Transaksi yang sedang berjalan untuk ID basis data.
  - /transactions/<DB_ID>/finished - Transaksi yang telah selesai untuk ID basis data.
  - /jobs - Informasi tentang pekerjaan asinkron (Schema Change, Rollup, dll.).
  - /statistic - Statistik untuk setiap basis data.
  - /tasks - Informasi tentang tugas agen.
  - /cluster_balance - Informasi status keseimbangan beban.
  - /routine_loads - Informasi tentang pekerjaan Routine Load.
  - /colocation_group - Informasi tentang grup Colocation Join.
  - /catalog - Informasi tentang katalog yang dikonfigurasi (misalnya, Hive, Iceberg).

Prompt

Tidak ada yang didefinisikan oleh server ini.

Perilaku Caching

Alat table_overview dan db_overview menggunakan cache dalam memori untuk menyimpan teks ringkasan yang dihasilkan.
Kunci cache adalah tuple dari (database_name, table_name).
Saat table_overview dipanggil, ia memeriksa cache terlebih dahulu. Jika hasil ada dan parameter refresh adalah false (default), hasil yang di-cache segera dikembalikan. Jika tidak, ia mengambil data dari StarRocks, menyimpannya di cache, lalu mengembalikannya.
Saat db_overview dipanggil, ia mencantumkan semua tabel dalam basis data dan kemudian mencoba mengambil ringkasan untuk setiap tabel menggunakan logika caching yang sama seperti table_overview (memeriksa cache terlebih dahulu, mengambil jika diperlukan dan refresh adalah false atau cache tidak ditemukan). Jika refresh adalah true untuk db_overview, ia memaksa penyegaran untuk semua tabel dalam basis data tersebut.
Variabel lingkungan STARROCKS_OVERVIEW_LIMIT menyediakan target lunak untuk panjang maksimum string ringkasan yang dihasilkan per tabel saat mengisi cache, membantu mengelola penggunaan memori.
Hasil yang di-cache, termasuk pesan kesalahan apa pun yang ditemui selama pengambilan asli, disimpan dan dikembalikan pada cache hit berikutnya.

Debug

Setelah memulai server mcp, Anda dapat menggunakan inspector untuk debug:

npx @modelcontextprotocol/inspector

Demo

MCP Demo Image

Dokumentasi