starrocks-mcp

A read-only MCP (Model Context Protocol) server for StarRocks databases. Query and explore your StarRocks data through Claude and other AI assistants.

Features

Supported ✅

• SQL Query Execution
  • Execute SQL queries directly from Claude Desktop
  • Automatic result truncation for large datasets
• Table Operations
  • List all databases
  • List tables in a database
  • Get table schema details
• LDAP Authentication
  • Secure LDAP authentication support
  • Each user uses their own credentials

Not Supported ❌

• Data Ingestion
• Table/Schema Creation or Modification
• User/Permission Management

Tools

Tool	Description
execute_query	Execute a SQL query and return results
list_databases	List all databases in StarRocks
list_tables	List tables in a database
describe_table	Get detailed schema information for a table

Installation

Using uvx (Recommended)

uvx --from git+https://github.com/jason-ung/starrocks-mcp starrocks-mcp

Using pip

pip install git+https://github.com/jason-ung/starrocks-mcp
starrocks-mcp

Configuration

Environment Variable	Required	Default	Description
STARROCKS_HOST	Yes	-	StarRocks host
STARROCKS_PORT	No	9030	StarRocks port
STARROCKS_USER	Yes	-	Your LDAP username
STARROCKS_PASSWORD	Yes	-	Your LDAP password
STARROCKS_DATABASE	No	ads	Default database
LOG_LEVEL	No	INFO	Logging level
DEFAULT_QUERY_TIMEOUT_MS	No	30000	Default query timeout (ms)
MAX_QUERY_LENGTH	No	10000	Maximum SQL query length

Claude Desktop Setup

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "starrocks": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jason-ung/starrocks-mcp",
        "starrocks-mcp"
      ],
      "env": {
        "STARROCKS_HOST": "starrocks.datapl.datahou.se",
        "STARROCKS_PORT": "9030",
        "STARROCKS_USER": "your.ldap.username",
        "STARROCKS_PASSWORD": "your_ldap_password",
        "STARROCKS_DATABASE": "ads"
      }
    }
  }
}

⚠️ Important: Replace your.ldap.username and your_ldap_password with your actual LDAP credentials.

Usage Examples

User: Show me all databases in StarRocks

Claude: [Uses list_databases]
- ads
- search
- user_behavior

User: What tables are in the ads database?

Claude: [Uses list_tables with database="ads"]
- advtr_product_da_preprocessed_log
- advtr_product_sa_preprocessed_log
- campaign_budget

User: Describe the advtr_product_da_preprocessed_log table

Claude: [Uses describe_table with table="advtr_product_da_preprocessed_log"]
Field | Type | Description
----- | ---- | -----------
eventTs | BIGINT | Event timestamp
eventType | VARCHAR | Event type (IMPRESSION, CLICK, etc.)
...

User: Query the top 10 campaigns by impression count

Claude: [Uses execute_query]
SELECT campaignId, COUNT(*) as impression_count
FROM advtr_product_da_preprocessed_log
WHERE eventType = 'IMPRESSION'
  AND base_dt = '2026-01-29'
GROUP BY campaignId
ORDER BY impression_count DESC
LIMIT 10

Development

Local Setup

git clone https://github.com/jason-ung/starrocks-mcp.git
cd starrocks-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Copy .env.example to .env and configure
cp .env.example .env
# Edit .env with your credentials

# Run the server
starrocks-mcp

Testing Connection

# Test StarRocks connection
mysql -h starrocks.datapl.datahou.se -P 9030 -u your.username -p --ssl-mode=DISABLED --enable-cleartext-plugin

Security

• Never commit credentials: Always use environment variables for sensitive data
• Use personal LDAP accounts: Each user should use their own credentials
• LDAP authentication: Supports cleartext LDAP authentication over secure connections
• Read-only operations: This MCP server only supports SELECT queries and metadata operations

License

MIT License - see LICENSE for details.

Author

Jason Son (@jason-ung)

---

Made with ❤️ for Bucketplace Ads Team