mcp-server-starrocks

核心功能#

mcp-server-starrocks 是连接 AI 模型与 StarRocks OLAP 数据库的官方适配器，通过 Model Context Protocol (MCP) 暴露一系列工具：

SQL 执行工具#

• read_query: 执行 SELECT、SHOW、DESCRIBE 等返回结果集的命令
• write_query: 执行 DDL (CREATE/ALTER/DROP) 和 DML (INSERT/UPDATE/DELETE) 命令
• analyze_query: 通过 Query Profile 或 Explain Analyze 分析查询性能

数据库探索#

• table_overview: 获取表结构、行数及样本数据（支持内存缓存）
• db_overview: 获取指定数据库中所有表的概览信息
• 资源路径：starrocks:///databases、starrocks:///{db}/tables、starrocks:///{db}/{table}/schema

系统信息访问#

• 通过 proc:///{path} 访问 StarRocks 内部系统信息
• 支持路径：/frontends、/backends、/compute_nodes、/dbs、/transactions、/jobs、/catalog 等

数据可视化#

• query_and_plotly_chart: 执行 SQL 并使用 Plotly Express 生成图表，返回 Base64 PNG 图像

技术特性#

连接架构#

• 标准 MySQL 协议: 使用 mysql.connector 连接（默认端口 9030）
• Arrow Flight SQL: 高性能连接，使用 ADBC 驱动（启用条件：设置 STARROCKS_FE_ARROW_FLIGHT_SQL_PORT）

智能缓存#

• 表和数据库概览使用内存缓存，缓存键为 (database_name, table_name) 元组
• 可通过 refresh=true 参数绕过缓存
• 通过 STARROCKS_OVERVIEW_LIMIT 环境变量控制概览文本长度（默认 20000 字符）

传输模式#

• stdio 模式（默认）
• Streamable HTTP 模式（推荐）
• SSE 模式

安全机制#

• SQL 注入防护：使用参数化查询和反引号转义
• Plotly 表达式验证：使用 AST 解析防止代码注入

安装与配置#

安装方式#

pip install mcp-server-starrocks
# 或使用 uv
uv run --with mcp-server-starrocks mcp-server-starrocks

环境变量配置#

• STARROCKS_URL: 连接串（优先级最高），格式 user:password@host:port/database
• STARROCKS_HOST / PORT / USER / PASSWORD / DB: 分离式配置
• STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: 启用高性能 Arrow Flight 连接
• MCP_TRANSPORT_MODE: 传输模式

适用场景#

• 自然语言驱动的数据库查询与分析（Text-to-SQL 执行）
• AI Agent 自主进行数据库结构探索与性能诊断
• 集成到支持 MCP 的客户端（如 Claude Desktop、Cursor 等）中实现实时数据对话

核心模块#

• server.py: 主服务实现，定义 MCP Tools 与 Resources
• db_client.py: 数据库连接池管理
• db_summary_manager.py: 元数据缓存与概览信息生成
• connection_health_checker.py: 连接状态监控与自动重连