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 分析）

# 克隆项目
git clone https://github.com/tracymacding/starrocks-mcp-server.git
cd starrocks-mcp-server

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

安装脚本会自动：

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

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

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

为什么强烈推荐 Claude Code：

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

快速安装：

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

配置文件位置：~/.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"
      }
    }
  }
}

配置说明：

查找 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

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）

# 启动 Claude Code
claude

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

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

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

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: 提示 "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

OpenCode 是一款开源的 AI 编程 Agent，支持终端、桌面应用和 IDE 插件，原生支持 MCP 协议。

一键安装（推荐）：

curl -fsSL https://opencode.ai/install | bash

通过 npm 安装：

npm install -g opencode-ai

通过 Homebrew 安装（macOS/Linux）：

brew install anomalyco/tap/opencode

验证安装：

opencode --version

OpenCode 使用 opencode.jsonc 作为配置文件，可放在项目目录或用户主目录下。

编辑或创建配置文件：

# 全局配置（推荐）
nano ~/.config/opencode/opencode.jsonc

# 或在项目目录中创建（仅对该项目生效）
nano opencode.jsonc

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

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "starrocks-expert": {
      "type": "local",
      "command": [
        "node",
        "/path/to/starrocks-mcp-server/starrocks-mcp.js"
      ],
      "enabled": true,
      "environment": {
        "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"
      }
    }
  }
}

配置说明：

# 进入项目目录
cd /path/to/your/project

# 启动 OpenCode
opencode

在 OpenCode 中验证 MCP 连接：

# 查看所有已连接的 MCP 服务器
opencode mcp list

# 预期输出中应包含：
# ✓ starrocks-expert: node .../starrocks-mcp.js (local) - Connected
#   Tools: 34

在 OpenCode 对话中直接输入：

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

或：

查询最近 1 小时的慢查询

OpenCode 会自动调用 StarRocks MCP 工具完成分析。

问题 1: MCP Server 无法连接

# 检查配置文件格式
cat ~/.config/opencode/opencode.jsonc

# 手动测试 MCP Server 能否启动
node /path/to/starrocks-mcp-server/starrocks-mcp.js
# 应该启动并等待输入

问题 2: 找不到 MCP 工具

# 检查 enabled 字段是否为 true
# 检查 command 路径是否正确
ls -la /path/to/starrocks-mcp-server/starrocks-mcp.js

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

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

官方文档: Gemini CLI Installation

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

# 验证安装
gemini --version

参考资源:

• NPM 包: @google/gemini-cli
• GitHub: google-gemini/gemini-cli

# 设置 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

创建或编辑 ~/.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"
      }
    }
  }
}

# 启动 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。

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

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

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接（方便直接使用 gemini 命令）
npm link

gemini --version
# 应该显示版本号，例如: 0.8.0

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

创建或编辑 ~/.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"
      }
    }
  }
}

配置说明：

使用启动脚本（推荐）：

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 诊断)

StarRocks MCP Server 支持在单个进程中管理多个集群，通过 use_cluster / list_clusters 工具实现运行时切换。

在 MCP Server 同级目录创建 clusters.json 文件（可参考 clusters.example.json）：

{
  "prod": {
    "name": "生产集群",
    "sr_host": "192.168.51.111",
    "sr_port": 9030,
    "sr_user": "root",
    "sr_password": "your_password",
    "prometheus_protocol": "http",
    "prometheus_host": "192.168.51.100",
    "prometheus_port": 30090,
    "ssh_user": "admin",
    "ssh_jump_host": "192.168.51.101",
    "central_api": "http://127.0.0.1:80",
    "central_api_token": "your_token"
  },
  "staging": {
    "name": "测试集群",
    "sr_host": "10.0.1.50",
    "sr_port": 9030,
    "sr_user": "root",
    "sr_password": "",
    "prometheus_host": "10.0.1.60",
    "prometheus_port": 9090,
    "central_api": "http://127.0.0.1:80",
    "central_api_token": "your_token"
  }
}

也可通过环境变量 CLUSTERS_CONFIG 指定配置文件路径。

注意：clusters.json 包含数据库密码等敏感信息，已默认加入 .gitignore，请勿提交到仓库。

查看集群列表：

帮我看看当前有哪些集群

MCP Server 会调用 list_clusters 工具，返回所有已配置集群的信息，包括架构类型和当前激活状态。

切换集群：

帮我切换到测试集群

MCP Server 会调用 use_cluster("staging")，切换后：

• 自动重置所有连接（数据库、SSH、Prometheus）
• 自动检测集群架构（shared_data / shared_nothing）
• 后续所有工具调用将使用新集群的配置

架构检测：

切换集群时，MCP Server 会自动检测集群架构类型。当前所有诊断工具仅支持 shared-data（存算分离） 架构：

• shared_data：正常使用所有工具
• shared_nothing：工具调用会被拦截，提示切换到 shared-data 集群
• 检测失败（如网络不通）：默认放行，不阻断使用

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

• 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 协议输入

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

2. 检查防火墙规则
3. 确认数据库用户权限

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