# starrocks-mcp

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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)

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

### Using pip

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

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

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

```bash
# 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](LICENSE) for details.

## Author

Jason Son ([@jason-ung](https://github.com/jason-ung))

---

**Made with ❤️ for Bucketplace Ads Team**