Skip to content
Back to search

mcp-server-starrocks

StarRocks MCP (Model Context Protocol) Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/starrocks--mcp-server-starrocks/badge.svg)](/listings/starrocks--mcp-server-starrocks)

HTML

<a href="/listings/starrocks--mcp-server-starrocks"><img src="/api/listings/starrocks--mcp-server-starrocks/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

# 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

See the [official `uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/) for other options. After installing, verify it is on your `PATH`:

uv --version

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 562 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. [![MseeP.ai Security Assessment Badge](https://mseep.net/mseep-audited.png)](https://mseep.ai/app/starrocks-mcp-server-starrocks)
  2. # StarRocks Official MCP Server
  3. The StarRocks MCP Server acts as a bridge between AI assistants and StarRocks databases. It allows for direct SQL execution, database exploration, data visualization via charts, and retrieving detailed schema/data overviews without requiring complex client-side setup.
  4. <a href="https://glama.ai/mcp/servers/@StarRocks/mcp-server-starrocks">
  5. <img width="380" height="200" src="https://glama.ai/mcp/servers/@StarRocks/mcp-server-starrocks/badge" alt="StarRocks Server MCP server" />
  6. </a>
  7. ## Features
  8. - **Direct SQL Execution:** Run `SELECT` queries (`read_query`) and DDL/DML commands (`write_query`).
  9. - **Database Exploration:** List databases and tables, retrieve table schemas (`starrocks://` resources).
  10. - **System Information:** Access internal StarRocks metrics and states via the `proc://` resource path.
  11. - **Detailed Overviews:** Get comprehensive summaries of tables (`table_overview`) or entire databases (`db_overview`), including column definitions, row counts, and sample data.
  12. - **Data Visualization:** Execute a query and generate a Plotly chart directly from the results (`query_and_plotly_chart`).
  13. - **Intelligent Caching:** Table and database overviews are cached in memory to speed up repeated requests. Cache can be bypassed when needed.
  14. - **Flexible Configuration:** Set connection details and behavior via environment variables.
  15. ## Prerequisites
  16. - **Python 3.11 or newer.**
  17. - A reachable **StarRocks** cluster (FE service). By default the server connects to `localhost:9030` over the MySQL protocol.
  18. - **[`uv`](https://docs.astral.sh/uv/)** — a fast Python package and project manager (a modern replacement for `pip` + `virtualenv`) from Astral. This project uses `uv` to resolve dependencies, create the virtual environment, and launch the server. The `uv run` commands throughout this README automatically create an isolated environment and install the required dependencies on first use, so no manual `pip install` step is needed.
  19. ### Installing `uv`
  20. ```bash
  21. # macOS / Linux
  22. curl -LsSf https://astral.sh/uv/install.sh | sh
  23. # Windows (PowerShell)
  24. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  25. # Or via Homebrew / pipx / pip
  26. brew install uv
  27. # pipx install uv
  28. # pip install uv
  29. ```
  30. See the [official `uv` installation guide](https://docs.astral.sh/uv/getting-started/installation/) for other options. After installing, verify it is on your `PATH`:
  31. ```bash
  32. uv --version
  33. ```
  34. ## Installation
  35. You generally do **not** need to install the package manually — the MCP host launches it for you via `uv` (see [Configuration](#configuration) below). `uv` fetches the package and its dependencies on demand.
  36. To run it directly for testing or development:
  37. ```bash
  38. # Run the published package in a throwaway environment
  39. uv run --with mcp-server-starrocks mcp-server-starrocks --help
  40. # Or, from a local checkout of this repository
  41. git clone https://github.com/starrocks/mcp-server-starrocks.git
  42. cd mcp-server-starrocks
  43. uv sync # create the virtual environment and install dependencies
  44. uv run mcp-server-starrocks --help
  45. ```
  46. ## Configuration
  47. The MCP server is typically run via an MCP host. Configuration is passed to the host, specifying how to launch the StarRocks MCP server process.
  48. **Using Streamable HTTP (recommended):**
  49. To start the server in Streamable HTTP mode:
  50. First test that the connection to StarRocks is OK (`9030` is the StarRocks MySQL protocol port, not the HTTP server port):
  51. ```
  52. $ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test
  53. ```
  54. Start the server:
  55. ```
  56. uv run mcp-server-starrocks --mode streamable-http --port 8000
  57. ```
  58. Then config the MCP like this:
  59. ```json
  60. {
  61. "mcpServers": {
  62. "mcp-server-starrocks": {
  63. "url": "http://localhost:8000/mcp"
  64. }
  65. }
  66. }
  67. ```
  68. **Using Docker:**
  69. Build the image:
  70. ```bash
  71. docker build -t mcp-server-starrocks:local .
  72. ```
  73. Build and push a versioned image:
  74. ```bash
  75. docker build -t <registry>/<namespace>/mcp-starrocks:0.4.0 .
  76. docker push <registry>/<namespace>/mcp-starrocks:0.4.0
  77. ```
  78. Start the server in Streamable HTTP mode:
  79. ```bash
  80. docker run --rm -p 8000:8000 \
  81. -e STARROCKS_HOST=host.docker.internal \
  82. -e STARROCKS_PORT=9030 \
  83. -e STARROCKS_USER=root \
  84. -e STARROCKS_PASSWORD='' \
  85. mcp-server-starrocks:local
  86. ```
  87. Then configure the MCP client with:
  88. ```json
  89. {
  90. "mcpServers": {
  91. "mcp-server-starrocks": {
  92. "url": "http://localhost:8000/mcp"
  93. }
  94. }
  95. }
  96. ```
  97. **Using `uv` with installed package (individual environment variables):**
  98. ```json
  99. {
  100. "mcpServers": {
  101. "mcp-server-starrocks": {
  102. "command": "uv",
  103. "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
  104. "env": {
  105. "STARROCKS_HOST": "default localhost",
  106. "STARROCKS_PORT": "default 9030",
  107. "STARROCKS_USER": "default root",
  108. "STARROCKS_PASSWORD": "default empty",
  109. "STARROCKS_DB": "default empty"
  110. }
  111. }
  112. }
  113. }
  114. ```
  115. **Using `uv` with installed package (connection URL):**
  116. ```json
  117. {
  118. "mcpServers": {
  119. "mcp-server-starrocks": {
  120. "command": "uv",
  121. "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
  122. "env": {
  123. "STARROCKS_URL": "root:password@localhost:9030/my_database"
  124. }
  125. }
  126. }
  127. }
  128. ```
  129. **Using `uv` with local directory (for development):**
  130. ```json
  131. {
  132. "mcpServers": {
  133. "mcp-server-starrocks": {
  134. "command": "uv",
  135. "args": [
  136. "--directory",
  137. "path/to/mcp-server-starrocks", // <-- Update this path
  138. "run",
  139. "mcp-server-starrocks"
  140. ],
  141. "env": {
  142. "STARROCKS_HOST": "default localhost",
  143. "STARROCKS_PORT": "default 9030",
  144. "STARROCKS_USER": "default root",
  145. "STARROCKS_PASSWORD": "default empty",
  146. "STARROCKS_DB": "default empty"
  147. }
  148. }
  149. }
  150. }
  151. ```
  152. **Using `uv` with local directory and connection URL:**
  153. ```json
  154. {
  155. "mcpServers": {
  156. "mcp-server-starrocks": {
  157. "command": "uv",
  158. "args": [
  159. "--directory",
  160. "path/to/mcp-server-starrocks", // <-- Update this path
  161. "run",
  162. "mcp-server-starrocks"
  163. ],
  164. "env": {
  165. "STARROCKS_URL": "root:password@localhost:9030/my_database"
  166. }
  167. }
  168. }
  169. }
  170. ```
  171. **Command-line Arguments:**
  172. The server supports the following command-line arguments:
  173. ```bash
  174. uv run mcp-server-starrocks --help
  175. ```
  176. - `--mode {stdio,sse,http,streamable-http}`: Transport mode (default: stdio or MCP_TRANSPORT_MODE env var)
  177. - `--host HOST`: Server host for HTTP modes (default: localhost)
  178. - `--port PORT`: Server port for HTTP modes
  179. - `--test`: Run in test mode to verify functionality
  180. Examples:
  181. ```bash
  182. # Start in streamable HTTP mode on custom host/port
  183. uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080
  184. # Start in stdio mode (default)
  185. uv run mcp-server-starrocks --mode stdio
  186. # Run test mode
  187. uv run mcp-server-starrocks --test
  188. ```
  189. - The `url` field should point to the Streamable HTTP endpoint of your MCP server (adjust host/port as needed).
  190. - With this configuration, clients can interact with the server using standard JSON over HTTP POST requests. No special SDK is required.
  191. - All tool APIs accept and return standard JSON as described above.
  192. > **Note:**
  193. > The `sse` (Server-Sent Events) mode is deprecated and no longer maintained. Please use Streamable HTTP mode for all new integrations.
  194. **Environment Variables:**
  195. ### Connection Configuration
  196. You can configure StarRocks connection using either individual environment variables or a single connection URL:
  197. **Option 1: Individual Environment Variables**
  198. - `STARROCKS_HOST`: (Optional) Hostname or IP address of the StarRocks FE service. Defaults to `localhost`.
  199. - `STARROCKS_PORT`: (Optional) MySQL protocol port of the StarRocks FE service. Defaults to `9030`.
  200. - `STARROCKS_USER`: (Optional) StarRocks username. Defaults to `root`.
  201. - `STARROCKS_PASSWORD`: (Optional) StarRocks password. Defaults to empty string.
  202. - `STARROCKS_PASSWORD_FILE`: (Optional) Path to a UTF-8 text file containing the password. This is useful with file-based secret injection such as systemd credentials. One trailing newline is ignored. This is only used when no explicit password is provided via `STARROCKS_PASSWORD` or `STARROCKS_URL`.
  203. - `STARROCKS_PASSWORD_KEYCHAIN_SERVICE`: (Optional, macOS only) Generic password service name to use when reading the password from Keychain. This is only used when no explicit password or `STARROCKS_PASSWORD_FILE` is configured.
  204. - `STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT`: (Optional, macOS only) Generic password account name to use when reading the password from Keychain. Defaults to the resolved StarRocks user.
  205. - `STARROCKS_DB`: (Optional) Default database to use if not specified in tool arguments or resource URIs. If set, the connection will attempt to `USE` this database. Tools like `table_overview` and `db_overview` will use this if the database part is omitted in their arguments. Defaults to empty (no default database).
  206. - `STARROCKS_QUERY_TIMEOUT`: (Optional) Number of seconds to wait for a query's results before giving up, as an integer. Unset by default, which waits indefinitely, matching prior behavior. Set this if a stuck or long-running query should fail instead of blocking a tool call forever.
  207. **Option 2: Connection URL (takes precedence over individual variables)**
  208. - `STARROCKS_URL`: (Optional) A connection URL string that contains all connection parameters in a single variable. Format: `[<schema>://]user:password@host:port/database`. The schema part is optional. When this variable is set, it takes precedence over the individual `STARROCKS_HOST`, `STARROCKS_PORT`, `STARROCKS_USER`, `STARROCKS_PASSWORD`, and `STARROCKS_DB` variables.
  209. Examples:
  210. - `root:mypass@localhost:9030/test_db`
  211. - `mysql://admin:secret@db.example.com:9030/production`
  212. - `starrocks://user:pass@192.168.1.100:9030/analytics`
  213. Password precedence:
  214. - A password embedded in `STARROCKS_URL` wins, including an explicit empty password like `user:@host:9030/db`.
  215. - If `STARROCKS_URL` omits the password, `STARROCKS_PASSWORD` is used when set.
  216. - If neither explicit password source is set and `STARROCKS_PASSWORD_FILE` is configured, the password is read from that file.
  217. - If no explicit password or password file is configured and `STARROCKS_PASSWORD_KEYCHAIN_SERVICE` is set, the password is read from macOS Keychain.
  218. **macOS Keychain example**
  219. Store the password:
  220. ```bash
  221. security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'
  222. ```
  223. Verify the stored password:
  224. ```bash
  225. security find-generic-password -a root -s mcp-server-starrocks -w
  226. ```
  227. Use it with this server:
  228. ```bash
  229. export STARROCKS_URL=root@localhost:9030/test_db
  230. export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
  231. export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root
  232. ```
  233. **[systemd encrypted credentials](https://systemd.io/CREDENTIALS/) example (systemd 250 or later)**
  234. The server does not invoke `systemd-creds` itself. At deployment time, an administrator encrypts the password; at service startup, systemd decrypts it into the service's credential directory and exposes only the file path to this server.
  235. Create a host-bound encrypted credential without putting the password in shell history:
  236. ```bash
  237. sudo -v
  238. sudo install -d -m 0700 /etc/credstore.encrypted
  239. sudo systemd-ask-password -n "StarRocks password:" \
  240. | sudo systemd-creds encrypt \
  241. --name=starrocks-password \
  242. - /etc/credstore.encrypted/starrocks-password.cred
  243. ```
  244. Add the credential to the service unit. The `%d` specifier expands to the service-specific credential directory:
  245. ```ini
  246. [Service]
  247. LoadCredentialEncrypted=starrocks-password:/etc/credstore.encrypted/starrocks-password.cred
  248. Environment=STARROCKS_PASSWORD_FILE=%d/starrocks-password
  249. PrivateMounts=yes
  250. ```
  251. Keep `STARROCKS_PASSWORD` unset and omit the password from `STARROCKS_URL`, then reload the unit and restart the service. The encrypted credential is normally bound to the local host (and to its TPM2 device when available); it is decrypted only while the service is being activated. The service process and administrators with root privileges can still access the plaintext password at runtime. Do not use `systemd-creds encrypt --with-key=null`, which does not provide confidentiality.
  252. ### Additional Configuration
  253. - `STARROCKS_FE_ARROW_FLIGHT_SQL_PORT`: (Optional) Arrow Flight SQL port of the StarRocks FE service. When set, the server connects using the high-performance Arrow Flight SQL protocol (via ADBC drivers) instead of the standard MySQL protocol. Leave unset to use the default MySQL connection. The host, user, and password are taken from the same connection settings described above.
  254. - `STARROCKS_OVERVIEW_LIMIT`: (Optional) An _approximate_ character limit for the _total_ text generated by overview tools (`table_overview`, `db_overview`) when fetching data to populate the cache. This helps prevent excessive memory usage for very large schemas or numerous tables. Defaults to `20000`.
  255. - `STARROCKS_MCP_OUTPUT_DIR`: (Optional) Directory used by `read_query` when its `output_file` argument is a relative path. Defaults to `~/.mcp-server-starrocks/output/`. The directory is created on demand. Absolute paths passed to `output_file` (including `~`-prefixed paths) bypass this setting. **Note:** files are written on the machine where the MCP server runs. For Claude Code / Claude Desktop the server runs locally, so files land on your laptop. For remote/http deployments the file lands on the server, not the client.
  256. - `STARROCKS_CHART_OUTPUT_DIR`: (Optional) Directory where `query_and_plotly_chart` writes interactive HTML charts (when `format="html"`). Defaults to the system temp directory. The directory is created on demand. **Note:** like other output files, charts are written on the machine where the MCP server runs.
  257. - `STARROCKS_CHART_INCLUDE_PLOTLYJS`: (Optional) Controls how `plotly.js` is bundled into HTML charts. `cdn` (default) keeps files small but needs network access when viewing; `inline`/`true` embeds the full library for offline use; `directory` and `false` are also accepted (passed through to Plotly's `write_html`).
  258. - `STARROCKS_CHART_DEFAULT_FORMAT`: (Optional) Default output format for `query_and_plotly_chart` when the `format` argument is omitted. One of `json`, `png`, `jpeg` (default), or `html`. Set to `html` to always write an interactive chart file to `STARROCKS_CHART_OUTPUT_DIR` (with an inline PNG preview) without passing `format` on every call. Invalid values fall back to `jpeg` with a warning.
  259. - `STARROCKS_MYSQL_AUTH_PLUGIN`: (Optional) Specifies the authentication plugin to use when connecting to the StarRocks FE service. For example, set to `mysql_clear_password` if your StarRocks deployment requires clear text password authentication (such as when using certain LDAP or external authentication setups). Only set this if your environment specifically requires it; otherwise, the default auth_plugin is used.
  260. ### TLS / SSL Configuration
  261. These variables control TLS for the connection. When none of them are set, the underlying `mysql.connector` keeps its default behavior (`ssl-mode=PREFERRED`): the connection is encrypted if the server supports TLS, but the server certificate is **not** verified. For real security, provide a CA certificate and enable verification.
  262. - `STARROCKS_SSL_DISABLED`: (Optional) Set to `true` to force-disable TLS. Overrides all other SSL settings. Defaults to `false`.
  263. - `STARROCKS_SSL_CA`: (Optional) Path to the CA certificate (PEM) used to verify the StarRocks server certificate.
  264. - `STARROCKS_SSL_CERT`: (Optional) Path to the client certificate (PEM) for mutual TLS (mTLS).
  265. - `STARROCKS_SSL_KEY`: (Optional) Path to the client private key (PEM) for mutual TLS (mTLS).
  266. - `STARROCKS_SSL_VERIFY_CERT`: (Optional) Set to `true` to verify the server certificate against the CA. Defaults to `false`.
  267. - `STARROCKS_SSL_VERIFY_IDENTITY`: (Optional) Set to `true` to also verify that the server hostname matches the certificate. Defaults to `false`.
  268. - `STARROCKS_TLS_VERSIONS`: (Optional) Comma-separated list of allowed TLS versions, e.g. `TLSv1.2,TLSv1.3`.
  269. Example (verify the server against a CA certificate):
  270. ```json
  271. "env": {
  272. "STARROCKS_HOST": "your-fe-host",
  273. "STARROCKS_PORT": "9030",
  274. "STARROCKS_USER": "root",
  275. "STARROCKS_PASSWORD": "your-password",
  276. "STARROCKS_SSL_CA": "/path/to/ca.pem",
  277. "STARROCKS_SSL_VERIFY_CERT": "true",
  278. "STARROCKS_SSL_VERIFY_IDENTITY": "true"
  279. }
  280. ```
  281. For the high-performance **Arrow Flight SQL** connection (enabled via `STARROCKS_FE_ARROW_FLIGHT_SQL_PORT`), TLS is controlled separately:
  282. - `STARROCKS_FE_ARROW_FLIGHT_SQL_USE_TLS`: (Optional) Set to `true` to use `grpc+tls://` instead of plaintext `grpc://`. When enabled, `STARROCKS_SSL_CA` is used as the TLS root certificate and `STARROCKS_SSL_VERIFY_CERT=false` (default) skips server certificate verification.
  283. > Security note: avoid storing plaintext passwords directly in `mcp.json`. Prefer injecting `STARROCKS_PASSWORD` (and certificate paths) from a secrets manager or environment, and never commit credentials to version control.
  284. - `MCP_TRANSPORT_MODE`: (Optional) Communication mode that specifies how the MCP Server exposes its services. Available options:
  285. - `stdio` (default): Communicates through standard input/output, suitable for MCP Host hosting.
  286. - `streamable-http` (Streamable HTTP): Starts as a Streamable HTTP Server, supporting RESTful API calls.
  287. - `sse`: **(Deprecated, not recommended)** Starts in Server-Sent Events (SSE) streaming mode, suitable for scenarios requiring streaming responses. **Note: SSE mode is no longer maintained, it is recommended to use Streamable HTTP mode uniformly.**
  288. ## Components
  289. ### Tools
  290. - `read_query`
  291. - **Description:** Execute a SELECT query or other commands that return a ResultSet (e.g., `SHOW`, `DESCRIBE`). Optionally write the full result to a local file instead of returning it inline — useful for results too large to fit in the model context.
  292. - **Input:**
  293. ```json
  294. {
  295. "query": "SQL query string",
  296. "db": "database name (optional, uses default database if not specified)",
  297. "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",
  298. "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
  299. }
  300. ```
  301. - **Output:** Without `output_file`, text content containing the query results in CSV-like format with a header row and row count summary. With `output_file`, a short summary including the resolved absolute path, byte count, and row count, plus a small preview. Returns an error message on failure.
  302. - `write_query`
  303. - **Description:** Execute a DDL (`CREATE`, `ALTER`, `DROP`), DML (`INSERT`, `UPDATE`, `DELETE`), or other StarRocks command that does not return a ResultSet.
  304. - **Input:**
  305. ```json
  306. {
  307. "query": "SQL command string",
  308. "db": "database name (optional, uses default database if not specified)"
  309. }
  310. ```
  311. - **Output:** Text content confirming success (e.g., "Query OK, X rows affected") or reporting an error. Changes are committed automatically on success.
  312. - `analyze_query`
  313. - **Description:** Analyze a query and get analyze result using query profile or explain analyze.
  314. - **Input:**
  315. ```json
  316. {
  317. "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
  318. "sql": "Query SQL to analyze",
  319. "db": "database name (optional, uses default database if not specified)"
  320. }
  321. ```
  322. - **Output:** Text content containing the query analysis results. Uses `ANALYZE PROFILE FROM` if uuid is provided, otherwise uses `EXPLAIN ANALYZE` if sql is provided.
  323. - `top_hot_tables`
  324. - **Description:** Get top hot tables by audit-log visit count. It joins `information_schema.tables` with `starrocks_audit_db__.starrocks_audit_tbl__`, excludes `root` and `SHOW` statements, matches audit SQL text against table names, and orders by `visit_count` descending.
  325. - **Input:**
  326. ```json
  327. {
  328. "db": "optional database/schema filter",
  329. "table": "optional table name substring filter",
  330. "min_start_time_ms": 1704067200000,
  331. "max_start_time_ms": 1704153600000,
  332. "top_n": 20
  333. }
  334. ```
  335. - **Output:** Text summary plus structured content containing ranked rows with `db`, `table`, and `visit_count`.
  336. - `top_bad_tables`
  337. - **Description:** Get top bad tables by table health score, following Star Management Studio's `top-bad-tables` logic. It reuses the table-health calculation based on `information_schema.be_tablets` and `information_schema.partitions_meta`, filters out system schemas, orders by `table_health_score` ascending, and returns the lowest-scoring tables.
  338. - **Input:**
  339. ```json
  340. {
  341. "db": "optional database/schema filter",
  342. "table": "optional table name substring filter",
  343. "top_n": 20
  344. }
  345. ```
  346. - **Output:** Text summary plus structured content containing ranked rows with table health fields such as `db`, `table`, `tablet_num`, `replica_score`, `tablet_score`, and `table_health_score`.
  347. - `query_and_plotly_chart`
  348. - **Description:** Executes a SQL query, loads the results into a Pandas DataFrame, and generates a Plotly chart using a provided Python expression. Designed for visualization in supporting UIs.
  349. - **Input:**
  350. ```json
  351. {
  352. "query": "SQL query to fetch data",
  353. "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
  354. "db": "database name (optional, uses default database if not specified)"
  355. }
  356. ```
  357. - **Output:** A list containing:
  358. 1. `TextContent`: A text representation of the DataFrame and a note that the chart is for UI display.
  359. 2. `ImageContent`: The generated Plotly chart encoded as a base64 PNG image (`image/png`). Returns text error message on failure or if the query yields no data.
  360. - `table_overview`
  361. - **Description:** Get an overview of a specific table: columns (from `DESCRIBE`), total row count, and sample rows (`LIMIT 3`). Uses an in-memory cache unless `refresh` is true.
  362. - **Input:**
  363. ```json
  364. {
  365. "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.",
  366. "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
  367. }
  368. ```
  369. - **Output:** Text content containing the formatted overview (columns, row count, sample data) or an error message. Cached results include previous errors if applicable.
  370. - `db_overview`
  371. - **Description:** Get an overview (columns, row count, sample rows) for _all_ tables within a specified database. Uses the table-level cache for each table unless `refresh` is true.
  372. - **Input:**
  373. ```json
  374. {
  375. "db": "database_name", // Optional if default database is set.
  376. "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
  377. }
  378. ```
  379. - **Output:** Text content containing concatenated overviews for all tables found in the database, separated by headers. Returns an error message if the database cannot be accessed or contains no tables.
  380. ### Resources
  381. #### Direct Resources
  382. - `starrocks:///databases`
  383. - **Description:** Lists all databases accessible to the configured user.
  384. - **Equivalent Query:** `SHOW DATABASES`
  385. - **MIME Type:** `text/plain`
  386. #### Resource Templates
  387. - `starrocks:///{db}/{table}/schema`
  388. - **Description:** Gets the schema definition of a specific table.
  389. - **Equivalent Query:** `SHOW CREATE TABLE {db}.{table}`
  390. - **MIME Type:** `text/plain`
  391. - `starrocks:///{db}/tables`
  392. - **Description:** Lists all tables within a specific database.
  393. - **Equivalent Query:** `SHOW TABLES FROM {db}`
  394. - **MIME Type:** `text/plain`
  395. - `proc:///{+path}`
  396. - **Description:** Accesses StarRocks internal system information, similar to Linux `/proc`. The `path` parameter specifies the desired information node.
  397. - **Equivalent Query:** `SHOW PROC '/{path}'`
  398. - **MIME Type:** `text/plain`
  399. - **Common Paths:**
  400. - `/frontends` - Information about FE nodes.
  401. - `/backends` - Information about BE nodes (for non-cloud native deployments).
  402. - `/compute_nodes` - Information about CN nodes (for cloud native deployments).
  403. - `/dbs` - Information about databases.
  404. - `/dbs/<DB_ID>` - Information about a specific database by ID.
  405. - `/dbs/<DB_ID>/<TABLE_ID>` - Information about a specific table by ID.
  406. - `/dbs/<DB_ID>/<TABLE_ID>/partitions` - Partition information for a table.
  407. - `/transactions` - Transaction information grouped by database.
  408. - `/transactions/<DB_ID>` - Transaction information for a specific database ID.
  409. - `/transactions/<DB_ID>/running` - Running transactions for a database ID.
  410. - `/transactions/<DB_ID>/finished` - Finished transactions for a database ID.
  411. - `/jobs` - Information about asynchronous jobs (Schema Change, Rollup, etc.).
  412. - `/statistic` - Statistics for each database.
  413. - `/tasks` - Information about agent tasks.
  414. - `/cluster_balance` - Load balance status information.
  415. - `/routine_loads` - Information about Routine Load jobs.
  416. - `/colocation_group` - Information about Colocation Join groups.
  417. - `/catalog` - Information about configured catalogs (e.g., Hive, Iceberg).
  418. ### Prompts
  419. None defined by this server.
  420. ## Caching Behavior
  421. - The `table_overview` and `db_overview` tools utilize an in-memory cache to store the generated overview text.
  422. - The cache key is a tuple of `(database_name, table_name)`.
  423. - When `table_overview` is called, it checks the cache first. If a result exists and the `refresh` parameter is `false` (default), the cached result is returned immediately. Otherwise, it fetches the data from StarRocks, stores it in the cache, and then returns it.
  424. - When `db_overview` is called, it lists all tables in the database and then attempts to retrieve the overview for _each table_ using the same caching logic as `table_overview` (checking cache first, fetching if needed and `refresh` is `false` or cache miss). If `refresh` is `true` for `db_overview`, it forces a refresh for _all_ tables in that database.
  425. - The `STARROCKS_OVERVIEW_LIMIT` environment variable provides a _soft target_ for the maximum length of the overview string generated _per table_ when populating the cache, helping to manage memory usage.
  426. - Cached results, including any error messages encountered during the original fetch, are stored and returned on subsequent cache hits.
  427. ## Debug
  428. After starting mcp server, you can use inspector to debug:
  429. ```
  430. npx @modelcontextprotocol/inspector
  431. ```
  432. ## Demo
  433. ![MCP Demo Image](mcpserverdemo.jpg)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.