{"id":28520022,"url":"https://github.com/starrocks/mcp-server-starrocks","last_synced_at":"2025-06-29T11:07:48.423Z","repository":{"id":281845179,"uuid":"943214141","full_name":"StarRocks/mcp-server-starrocks","owner":"StarRocks","description":"StarRocks MCP (Model Context Protocol) Server","archived":false,"fork":false,"pushed_at":"2025-06-19T02:09:10.000Z","size":679,"stargazers_count":82,"open_issues_count":5,"forks_count":28,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-06-19T03:24:35.678Z","etag":null,"topics":["agent","ai","database","mcp-server","model-context-protocol","starrocks"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StarRocks.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-05T10:48:25.000Z","updated_at":"2025-06-19T02:09:13.000Z","dependencies_parsed_at":"2025-03-11T13:25:30.718Z","dependency_job_id":"e41e6768-95c7-4b02-ad4d-8a1358acb073","html_url":"https://github.com/StarRocks/mcp-server-starrocks","commit_stats":null,"previous_names":["starrocks/mcp-server-starrocks"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/StarRocks/mcp-server-starrocks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StarRocks%2Fmcp-server-starrocks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StarRocks%2Fmcp-server-starrocks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StarRocks%2Fmcp-server-starrocks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StarRocks%2Fmcp-server-starrocks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StarRocks","download_url":"https://codeload.github.com/StarRocks/mcp-server-starrocks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StarRocks%2Fmcp-server-starrocks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260682467,"owners_count":23046060,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","database","mcp-server","model-context-protocol","starrocks"],"created_at":"2025-06-09T06:38:03.561Z","updated_at":"2025-06-29T11:07:48.404Z","avatar_url":"https://github.com/StarRocks.png","language":"Python","funding_links":[],"categories":["Databases"],"sub_categories":["How to Submit"],"readme":"[![MseeP.ai Security Assessment Badge](https://mseep.net/mseep-audited.png)](https://mseep.ai/app/starrocks-mcp-server-starrocks)\n\n# StarRocks Official MCP Server\n\nThe 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.\n\n\u003ca href=\"https://glama.ai/mcp/servers/@StarRocks/mcp-server-starrocks\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@StarRocks/mcp-server-starrocks/badge\" alt=\"StarRocks Server MCP server\" /\u003e\n\u003c/a\u003e\n\n## Features\n\n- **Direct SQL Execution:** Run `SELECT` queries (`read_query`) and DDL/DML commands (`write_query`).\n- **Database Exploration:** List databases and tables, retrieve table schemas (`starrocks://` resources).\n- **System Information:** Access internal StarRocks metrics and states via the `proc://` resource path.\n- **Detailed Overviews:** Get comprehensive summaries of tables (`table_overview`) or entire databases (`db_overview`), including column definitions, row counts, and sample data.\n- **Data Visualization:** Execute a query and generate a Plotly chart directly from the results (`query_and_plotly_chart`).\n- **Intelligent Caching:** Table and database overviews are cached in memory to speed up repeated requests. Cache can be bypassed when needed.\n- **Flexible Configuration:** Set connection details and behavior via environment variables.\n\n## Configuration\n\nThe MCP server is typically run via an MCP host. Configuration is passed to the host, specifying how to launch the StarRocks MCP server process.\n\n**Using `uv` with installed package:**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-starrocks\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--with\", \"mcp-server-starrocks\", \"mcp-server-starrocks\"],\n      \"env\": {\n        \"STARROCKS_HOST\": \"default localhost\",\n        \"STARROCKS_PORT\": \"default 9030\",\n        \"STARROCKS_USER\": \"default root\",\n        \"STARROCKS_PASSWORD\": \"default empty\",\n        \"STARROCKS_DB\": \"default empty\",\n        \"STARROCKS_OVERVIEW_LIMIT\": \"default 20000\",\n        \"STARROCKS_MYSQL_AUTH_PLUGIN\":\"mysql_clear_password\"\n      }\n    }\n  }\n}\n```\n\n**Using `uv` with local directory (for development):**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-starrocks\": {\n      \"command\": \"uv\",\n      \"args\": [\n        \"--directory\",\n        \"path/to/mcp-server-starrocks\", // \u003c-- Update this path\n        \"run\",\n        \"mcp-server-starrocks\"\n      ],\n      \"env\": {\n        \"STARROCKS_HOST\": \"default localhost\",\n        \"STARROCKS_PORT\": \"default 9030\",\n        \"STARROCKS_USER\": \"default root\",\n        \"STARROCKS_PASSWORD\": \"default empty\",\n        \"STARROCKS_DB\": \"default empty\",\n        \"STARROCKS_OVERVIEW_LIMIT\": \"default 20000\",\n        \"STARROCKS_MYSQL_AUTH_PLUGIN\":\"mysql_clear_password\"\n      }\n    }\n  }\n}\n```\n\n**Using Streamable HTTP (recommended for integration):**\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-server-starrocks\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\nTo start the server in Streamable HTTP mode:\n\n```bash\nexport MCP_TRANSPORT_MODE=streamable-http\nuv run mcp-server-starrocks\n```\n\n- The `url` field should point to the Streamable HTTP endpoint of your MCP server (adjust host/port as needed).\n- With this configuration, clients can interact with the server using standard JSON over HTTP POST requests. No special SDK is required.\n- All tool APIs accept and return standard JSON as described above.\n\n\u003e **Note:**\n\u003e The `sse` (Server-Sent Events) mode is deprecated and no longer maintained. Please use Streamable HTTP mode for all new integrations.\n\n**Environment Variables:**\n\n- `STARROCKS_HOST`: (Optional) Hostname or IP address of the StarRocks FE service. Defaults to `localhost`.\n- `STARROCKS_PORT`: (Optional) MySQL protocol port of the StarRocks FE service. Defaults to `9030`.\n- `STARROCKS_USER`: (Optional) StarRocks username. Defaults to `root`.\n- `STARROCKS_PASSWORD`: (Optional) StarRocks password. Defaults to empty string.\n- `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).\n- `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`.\n- `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.\n- `MCP_TRANSPORT_MODE`: (Optional) Communication mode that specifies how the MCP Server exposes its services. Available options:\n  - `stdio` (default): Communicates through standard input/output, suitable for MCP Host hosting.\n  - `streamable-http` (Streamable HTTP): Starts as a Streamable HTTP Server, supporting RESTful API calls.\n  - `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.**\n\n## Components\n\n### Tools\n\n- `read_query`\n\n  - **Description:** Execute a SELECT query or other commands that return a ResultSet (e.g., `SHOW`, `DESCRIBE`).\n  - **Input:** `{ \"query\": \"SQL query string\" }`\n  - **Output:** Text content containing the query results in a CSV-like format, including a header row and a row count summary. Returns an error message on failure.\n\n- `write_query`\n\n  - **Description:** Execute a DDL (`CREATE`, `ALTER`, `DROP`), DML (`INSERT`, `UPDATE`, `DELETE`), or other StarRocks command that does not return a ResultSet.\n  - **Input:** `{ \"query\": \"SQL command string\" }`\n  - **Output:** Text content confirming success (e.g., \"Query OK, X rows affected\") or reporting an error. Changes are committed automatically on success.\n\n- `query_and_plotly_chart`\n\n  - **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.\n  - **Input:**\n    ```json\n    {\n      \"query\": \"SQL query to fetch data\",\n      \"plotly_expr\": \"Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\\\"col1\\\", y=\\\"col2\\\")'\"\n    }\n    ```\n  - **Output:** A list containing:\n    1.  `TextContent`: A text representation of the DataFrame and a note that the chart is for UI display.\n    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.\n\n- `table_overview`\n\n  - **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.\n  - **Input:**\n    ```json\n    {\n      \"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.\",\n      \"refresh\": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.\n    }\n    ```\n  - **Output:** Text content containing the formatted overview (columns, row count, sample data) or an error message. Cached results include previous errors if applicable.\n\n- `db_overview`\n  - **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.\n  - **Input:**\n    ```json\n    {\n      \"db\": \"database_name\", // Optional if STARROCKS_DB env var is set.\n      \"refresh\": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.\n    }\n    ```\n  - **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.\n\n### Resources\n\n#### Direct Resources\n\n- `starrocks:///databases`\n  - **Description:** Lists all databases accessible to the configured user.\n  - **Equivalent Query:** `SHOW DATABASES`\n  - **MIME Type:** `text/plain`\n\n#### Resource Templates\n\n- `starrocks:///{db}/{table}/schema`\n\n  - **Description:** Gets the schema definition of a specific table.\n  - **Equivalent Query:** `SHOW CREATE TABLE {db}.{table}`\n  - **MIME Type:** `text/plain`\n\n- `starrocks:///{db}/tables`\n\n  - **Description:** Lists all tables within a specific database.\n  - **Equivalent Query:** `SHOW TABLES FROM {db}`\n  - **MIME Type:** `text/plain`\n\n- `proc:///{+path}`\n  - **Description:** Accesses StarRocks internal system information, similar to Linux `/proc`. The `path` parameter specifies the desired information node.\n  - **Equivalent Query:** `SHOW PROC '/{path}'`\n  - **MIME Type:** `text/plain`\n  - **Common Paths:**\n    - `/frontends` - Information about FE nodes.\n    - `/backends` - Information about BE nodes (for non-cloud native deployments).\n    - `/compute_nodes` - Information about CN nodes (for cloud native deployments).\n    - `/dbs` - Information about databases.\n    - `/dbs/\u003cDB_ID\u003e` - Information about a specific database by ID.\n    - `/dbs/\u003cDB_ID\u003e/\u003cTABLE_ID\u003e` - Information about a specific table by ID.\n    - `/dbs/\u003cDB_ID\u003e/\u003cTABLE_ID\u003e/partitions` - Partition information for a table.\n    - `/transactions` - Transaction information grouped by database.\n    - `/transactions/\u003cDB_ID\u003e` - Transaction information for a specific database ID.\n    - `/transactions/\u003cDB_ID\u003e/running` - Running transactions for a database ID.\n    - `/transactions/\u003cDB_ID\u003e/finished` - Finished transactions for a database ID.\n    - `/jobs` - Information about asynchronous jobs (Schema Change, Rollup, etc.).\n    - `/statistic` - Statistics for each database.\n    - `/tasks` - Information about agent tasks.\n    - `/cluster_balance` - Load balance status information.\n    - `/routine_loads` - Information about Routine Load jobs.\n    - `/colocation_group` - Information about Colocation Join groups.\n    - `/catalog` - Information about configured catalogs (e.g., Hive, Iceberg).\n\n### Prompts\n\nNone defined by this server.\n\n## Caching Behavior\n\n- The `table_overview` and `db_overview` tools utilize an in-memory cache to store the generated overview text.\n- The cache key is a tuple of `(database_name, table_name)`.\n- 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.\n- 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.\n- 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.\n- Cached results, including any error messages encountered during the original fetch, are stored and returned on subsequent cache hits.\n\n## Demo\n\n![MCP Demo Image](mcpserverdemo.jpg)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarrocks%2Fmcp-server-starrocks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstarrocks%2Fmcp-server-starrocks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstarrocks%2Fmcp-server-starrocks/lists"}