starrocks-mcp-server

tracymacding/starrocks-mcp-server

3.3

If you are the rightful owner of starrocks-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

StarRocks MCP Server is a server implementation of the Model Context Protocol (MCP) designed to provide intelligent diagnostics and analysis capabilities for AI clients using the StarRocks database.

StarRocks MCP Server

MCP Node

StarRocks MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，为 AI 客户端提供 StarRocks 数据库的智能诊断和分析能力。

🎯 功能特性

  • ✅ MCP 协议支持: 完整实现 MCP Stdio Server 协议
  • ✅ 数据库连接: 连接 StarRocks 数据库执行 SQL 查询
  • ✅ 多客户端支持: 兼容 Gemini CLI、Claude Code CLI 等 MCP 客户端
  • ✅ 日志系统: 完整的请求/响应日志记录
  • ✅ 安全性: 支持环境变量配置，保护敏感信息

📦 架构

┌─────────────────────┐
│  MCP Client         │  (Claude Desktop, Cline, etc.)
│  (AI Application)   │
└──────────┬──────────┘
           │ MCP Protocol (Stdio)
           │
┌──────────▼──────────┐
│ StarRocks MCP Server│  (This Project)
│  - Tool Execution   │
│  - SQL Connection   │
│  - API Integration  │
└──────────┬──────────┘
           │
           ├─────────────────────┐
           │                     │
┌──────────▼──────────┐  ┌──────▼─────────────┐
│  StarRocks Database │  │ StarRocks Expert   │
│  (MySQL Protocol)   │  │ (Central API)      │
└─────────────────────┘  └────────────────────┘

🚀 快速开始

前置要求

  • Node.js >= 18.0.0
  • StarRocks 数据库实例
  • StarRocks Expert 中心服务（可选，用于高级分析）
  • DeepSeek API Key（可选，用于 LLM 分析）

安装

方法 1: 使用安装脚本（推荐）
# 克隆项目
git clone https://github.com/tracymacding/starrocks-mcp-server.git
cd starrocks-mcp-server

# 运行安装脚本
./install-starrocks-mcp.sh

安装脚本会自动：

  • 创建 ~/.starrocks-mcp/ 目录
  • 复制所有必要文件
  • 安装 npm 依赖
  • 生成配置文件模板

🔌 MCP 客户端配置

StarRocks MCP Server 支持任何实现了 MCP 协议的客户端。以下是主流客户端的详细配置指南。

方式 1: Claude Code CLI 配置（⭐ 强烈推荐）

Claude Code 是 Anthropic 官方的命令行 AI 编程工具，原生支持 MCP 协议。

为什么强烈推荐 Claude Code：

  • ✅ 最强的代码能力：Claude 在代码理解和生成方面表现卓越
  • ✅ 原生 MCP 支持：无需额外配置即可使用 MCP 工具
  • ✅ 支持 DeepSeek：可配置使用 DeepSeek 模型，大幅降低成本
  • ✅ 交互体验好：流式输出、多轮对话、上下文保持
  • ✅ 跨平台支持：macOS、Linux、Windows 全平台支持
1.1 安装 Claude Code CLI

快速安装：

Claude Code 提供了一键安装脚本，支持 macOS、Linux 和 Windows：

macOS/Linux：

# 一键安装
curl -fsSL https://claude.ai/install.sh | bash

Windows (PowerShell)：

# 一键安装
irm https://claude.ai/install.ps1 | iex

验证安装：

# 检查 Claude Code 是否已安装
claude --version

# 或直接启动
claude
1.2 配置 MCP Server

配置文件位置：~/.claude.json

编辑配置文件：

# macOS/Linux
nano ~/.claude.json

# Windows (PowerShell)
notepad "$env:USERPROFILE\.claude.json"

添加以下配置（根据实际情况修改）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}

配置说明：

参数说明示例
command执行命令（通常是 node）node
args[0]MCP Server 脚本的完整路径/home/user/starrocks-mcp-server/starrocks-mcp.js
SR_HOSTStarRocks 数据库地址localhost
SR_PORTStarRocks 查询端口9030
SR_USER数据库用户名root
SR_PASSWORD数据库密码留空或填写密码
CENTRAL_APIExpert 服务地址（可选）http://127.0.0.1:3002
CENTRAL_API_TOKENAPI Token（可选）向管理员索取
PROMETHEUS_PROTOCOLPrometheus 协议http 或 https
PROMETHEUS_HOSTPrometheus 地址localhost
PROMETHEUS_PORTPrometheus 端口9092

查找 MCP Server 路径：

# 定位 starrocks-mcp.js 文件
find ~ -name "starrocks-mcp.js" 2>/dev/null

# 或者，如果你知道安装目录
cd /path/to/starrocks-mcp-server
pwd
# 输出完整路径，例如: /home/user/starrocks-mcp-server
1.3 使用 DeepSeek 模型（可选，推荐）

Claude Code 默认使用 Anthropic Claude 模型，但你也可以配置使用 DeepSeek 作为后端模型，成本更低且中文支持更好。

DeepSeek 优势：

  • ✅ 成本低廉（约 ¥1/百万 tokens 输入，比 Claude 便宜 90%+）
  • ✅ DeepSeek-V3 性能优秀
  • ✅ 中文理解和生成能力强
  • ✅ 官方支持 Anthropic API 兼容格式

参考文档：DeepSeek Anthropic API 兼容

配置方式

方式 A: 设置环境变量（推荐）

# 添加到 shell 配置文件（~/.bashrc 或 ~/.zshrc）
cat >> ~/.bashrc <<'EOF'

# DeepSeek 配置 for Claude Code
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-api-key-here  # 替换为你的 DeepSeek API Key
export ANTHROPIC_MODEL=deepseek-chat
export API_TIMEOUT_MS=600000  # 防止长输出超时
EOF

# 使配置生效
source ~/.bashrc

方式 B: 启动时设置

# 每次启动 Claude Code 时设置
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic \
ANTHROPIC_AUTH_TOKEN=sk-your-deepseek-api-key \
ANTHROPIC_MODEL=deepseek-chat \
API_TIMEOUT_MS=600000 \
claude

获取 DeepSeek API Key：

  1. 访问 DeepSeek 开放平台
  2. 注册/登录账号
  3. 进入 API Keys 页面创建新的 API Key
  4. 复制 API Key（格式为 sk-xxxxxxxx）
DeepSeek 支持的功能
功能支持情况
max_tokens✅ 支持
stop_sequences✅ 支持
stream✅ 支持
system prompts✅ 支持
temperature (0.0-2.0)✅ 支持
top_p✅ 支持
tool use (MCP 工具调用)✅ 支持
thinking mode✅ 支持
图片内容❌ 不支持
文档类型❌ 不支持
验证 DeepSeek 配置
# 启动 Claude Code
claude

# 如果配置正确，Claude Code 会使用 DeepSeek 模型
# 可以通过询问模型来验证
> 你是什么模型？

# DeepSeek 会回复类似：我是 DeepSeek...

注意：使用 DeepSeek 时，部分 Claude 特有功能（如图片分析）将不可用，但对于代码编写和 StarRocks 诊断等文本任务完全够用。

1.4 验证配置

  1. 启动 Claude Code CLI：

    # 方式 1: 直接启动
claude

# 方式 2: 在项目目录中启动
cd /path/to/your/project
claude

  2. 检查 MCP Server 连接：

    在 Claude Code 中输入：

    列出所有可用的 MCP 工具

    或者：

    /tools

  3. 测试 StarRocks 诊断功能：

    帮我分析 StarRocks 的存储健康状况

    或者：

    查询最近 1 小时的慢查询

  4. 预期结果：

    Claude Code 应该能够：

    • ✅ 自动连接到 StarRocks MCP Server
    • ✅ 列出所有可用工具（34 个 StarRocks 诊断工具）
    • ✅ 执行 SQL 查询并返回分析结果
    • ✅ 提供专业的诊断建议
1.5 故障排查

问题 1: 提示 "MCP Server not found" 或 "Connection failed"

解决方法：

# 检查配置文件是否存在
cat ~/.claude.json

# 检查配置文件 JSON 格式是否正确
cat ~/.claude.json | jq .

# 手动测试 MCP Server 是否能启动
export SR_HOST=localhost
export SR_PORT=9030
export SR_USER=root
export SR_PASSWORD=
export CENTRAL_API=http://127.0.0.1:3002
export CENTRAL_API_TOKEN=your_token
export PROMETHEUS_PROTOCOL=http
export PROMETHEUS_HOST=localhost
export PROMETHEUS_PORT=9092

node /path/to/starrocks-mcp-server/starrocks-mcp.js
# 应该启动并等待输入

问题 2: 工具执行失败

解决方法：

  • 检查 StarRocks 数据库连接：

    mysql -h 127.0.0.1 -P 9030 -u root -e "SELECT 1"

  • 检查中心 API 服务器（如果使用）：

    curl http://localhost:80/health

问题 3: 配置文件路径不正确

检查配置文件：

# 检查配置文件是否存在
ls -la ~/.claude.json

# 查看配置文件内容
cat ~/.claude.json

方式 2: Gemini CLI 配置

Gemini CLI 是 Google 官方的命令行工具，原生支持 MCP 协议。根据是否需要使用 DeepSeek 作为 LLM 提供商，有两种配置方式：

方式 2A: 原生 Gemini CLI（仅支持 Google Gemini）

如果你只需要使用 Google Gemini API，可以安装原生版本。

2A.1 安装原生 Gemini CLI

官方文档: Gemini CLI Installation

# 全局安装 Gemini CLI
npm install -g @google/gemini-cli

# 验证安装
gemini --version

参考资源:

2A.2 配置 Google Gemini API Key
# 设置 API Key（从 https://aistudio.google.com/apikey 获取）
export GOOGLE_API_KEY="your-google-api-key-here"

# 或添加到 shell 配置文件
echo 'export GOOGLE_API_KEY="your-google-api-key-here"' >> ~/.bashrc
source ~/.bashrc
2A.3 配置 MCP Server

创建或编辑 ~/.gemini/settings.json 文件：

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

添加以下配置（根据实际情况修改路径和连接信息）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}
2A.4 验证配置
# 启动 Gemini CLI
gemini

# 检查 MCP 连接状态
> /mcp list

# 预期输出：
# ✓ starrocks-expert: node .../starrocks-mcp.js (stdio) - Connected
#   Tools: 34

# 测试工具
> 帮我查看 StarRocks 的存储健康状况

注意：原生 Gemini CLI 仅支持 Google Gemini API，不支持 DeepSeek 等其他 LLM 提供商。如需使用 DeepSeek，请使用方式 2B。

方式 2B: 定制版 Gemini CLI（支持 DeepSeek，推荐）

定制版 Gemini CLI 扩展了原生版本，支持 DeepSeek 等多种 LLM 提供商，成本更低且性能优秀。

2B.1 安装定制版 Gemini CLI
# 克隆定制版 Gemini CLI 项目
git clone https://github.com/tracymacding/gemini-cli.git
cd gemini-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（方便直接使用 gemini 命令）
npm link
2B.2 验证安装
gemini --version
# 应该显示版本号，例如: 0.8.0
2B.3 配置 DeepSeek API Key

DeepSeek 优势：

  • ✅ 比 Google Gemini 便宜约 90%（¥1/百万 tokens 输入）
  • ✅ 性能优秀（DeepSeek-V3）
  • ✅ 中文支持更好

方式 A: 使用 .env 文件（推荐）

cd gemini-cli

# 创建 .env 文件
cat > .env <<'EOF'
# DeepSeek API Key
# 获取地址: https://platform.deepseek.com/
DEEPSEEK_API_KEY=sk-your-deepseek-api-key-here
EOF

方式 B: 设置环境变量

# 临时设置（当前终端有效）
export DEEPSEEK_API_KEY="sk-your-deepseek-api-key-here"

# 永久设置（添加到 shell 配置）
echo 'export DEEPSEEK_API_KEY="sk-your-deepseek-api-key-here"' >> ~/.bashrc
source ~/.bashrc
2B.4 配置 MCP Server

创建或编辑 ~/.gemini/settings.json 文件：

mkdir -p ~/.gemini
nano ~/.gemini/settings.json

添加以下配置（根据实际情况修改路径和连接信息）：

{
  "mcpServers": {
    "starrocks-expert": {
      "command": "node",
      "args": [
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "env": {
        "SR_HOST": "localhost",
        "SR_USER": "root",
        "SR_PASSWORD": "",
        "SR_PORT": "9030",
        "CENTRAL_API": "http://127.0.0.1:3002",
        "CENTRAL_API_TOKEN": "your_api_token_here",
        "PROMETHEUS_PROTOCOL": "http",
        "PROMETHEUS_HOST": "localhost",
        "PROMETHEUS_PORT": "9092"
      }
    }
  }
}

配置说明：

参数说明示例
args[0]MCP Server 脚本的完整路径/home/user/starrocks-mcp-server/starrocks-mcp.js
SR_HOSTStarRocks 数据库地址localhost 或 192.168.1.100
SR_PORTStarRocks 查询端口9030 (默认)
SR_USER数据库用户名root
SR_PASSWORD数据库密码留空或填写实际密码
CENTRAL_APIExpert 服务地址（可选）http://127.0.0.1:3002
CENTRAL_API_TOKENAPI 认证 Token（可选）向管理员索取
PROMETHEUS_PROTOCOLPrometheus 协议http 或 https
PROMETHEUS_HOSTPrometheus 地址localhost
PROMETHEUS_PORTPrometheus 端口9092
2B.5 验证配置

使用启动脚本（推荐）：

cd gemini-cli
./start-gemini-cli.sh

或手动启动：

# 启动 Gemini CLI 并使用 DeepSeek
gemini --provider deepseek -m deepseek-chat

# 检查 MCP 连接状态
> /mcp list

# 预期输出：
# ✓ starrocks-expert: node .../starrocks-mcp.js (stdio) - Connected
#   Tools: 34

# 查看可用工具
> /tools

# 测试工具
> 帮我分析 StarRocks 的存储健康状况

预期输出示例：

🤖 启动 Gemini CLI (DeepSeek + MCP)
====================================

✅ 已加载 .env 配置
✅ DeepSeek API Key: sk-76b76...
📡 检查中心 API 服务器...
   ✅ API 服务器运行正常
🔧 检查 MCP 配置...
   ✅ MCP 服务器已连接

🚀 启动 Gemini CLI...

💡 使用的功能:
   • DeepSeek 模型 (deepseek-chat)
   • MCP 工具 (StarRocks 诊断)

配置验证清单

完成配置后，使用以下清单验证：

  • MCP Server 能成功启动（没有报错）
  • 客户端显示 "Connected" 状态
  • 可以看到工具列表（通常 30+ 个工具）
  • 能成功执行一个测试工具（例如查询数据库版本）
  • 日志文件正常生成（./logs/ 目录）

故障排查

如果连接失败，请按顺序检查：

  1. 检查 Node.js 版本：

    node --version  # 必须 >= 18.0.0

  2. 检查文件路径：

    ls -la /path/to/starrocks-mcp.js  # 文件必须存在

  3. 检查数据库连接：

    mysql -h $SR_HOST -P $SR_PORT -u $SR_USER -p

  4. 查看日志：

    tail -f /path/to/starrocks-mcp-server/logs/starrocks-mcp-*.log

  5. 手动测试 MCP Server：

    cd /path/to/starrocks-mcp-server
node starrocks-mcp.js
# 应该启动并等待 MCP 协议输入

🐛 故障排查

MCP Server 无法连接

  1. 检查 Node.js 版本：node --version（需要 >= 18）
  2. 检查环境变量：cat .env
  3. 查看日志：tail -f logs/starrocks-mcp-*.log

数据库连接失败

  1. 测试数据库连接：
mysql -h $SR_HOST -P $SR_PORT -u $SR_USER -p
  1. 检查防火墙规则
  2. 确认数据库用户权限

工具执行失败

  1. 检查日志中的错误信息
  2. 确认 StarRocks Expert 服务是否运行
  3. 验证 API Token 是否正确