Timeplus MCP Server 使用说明

项目简介

Timeplus MCP Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，它充当大型语言模型 (LLM) 客户端和 Timeplus 数据分析平台之间的桥梁。通过此服务器，LLM 客户端可以安全、便捷地访问 Timeplus 的数据和功能，实现更智能的数据分析和应用集成。

主要功能点

SQL 查询执行: 允许 LLM 客户端通过 'run_sql' 工具在 Timeplus 集群上执行 SQL 查询，并返回查询结果。
数据库和表浏览: 提供 'list_databases' 和 'list_tables' 工具，帮助 LLM 客户端了解 Timeplus 集群中的数据库和表结构。
Kafka 集成: 支持列出 Kafka 主题 ('list_kafka_topics')、探索 Kafka 主题消息 ('explore_kafka_topic') 和创建 Kafka 流 ('create_kafka_stream')，方便 LLM 客户端与 Kafka 数据流互动。
Prompt 模板辅助 SQL 生成: 提供 'generate_sql' Prompt 模板，引导 LLM 生成符合 Timeplus SQL 语法要求的查询语句。

安装步骤

安装 'mcp-timeplus' Python 包:
```
uv pip install mcp-timeplus
```
- 确保已安装 'uv'，如果未安装，请参考 uv 安装指南。

配置环境变量:

需要配置 Timeplus 连接信息，包括 Host, Port, User, Password 等。
Kafka 集成功能需要配置 Kafka 连接信息，以 JSON 字符串格式设置 'TIMEPLUS_KAFKA_CONFIG' 环境变量。

建议将环境变量配置在 '.env' 文件中，方便管理。示例 '.env' 文件内容如下:

TIMEPLUS_HOST=your_timeplus_host
TIMEPLUS_PORT=8123
TIMEPLUS_USER=your_timeplus_user
TIMEPLUS_PASSWORD=your_timeplus_password
TIMEPLUS_SECURE=false
TIMEPLUS_VERIFY=true
TIMEPLUS_READ_ONLY=false
TIMEPLUS_KAFKA_CONFIG={"bootstrap.servers":"your_kafka_brokers", "sasl.mechanism":"SCRAM-SHA-256","sasl.username":"your_kafka_user", "sasl.password":"your_kafka_password","security.protocol":"SASL_SSL","enable.ssl.certificate.verification":"false"}

请根据您的 Timeplus 和 Kafka 集群信息修改上述配置。

服务器配置 (MCP 客户端配置)

对于 MCP 客户端 (如 Claude Desktop, 5ire 等)，您需要配置 MCP 服务器的启动命令和参数，以便客户端能够连接到 Timeplus MCP Server。

以 Claude Desktop 为例，配置信息如下 (JSON 格式):

{
  "mcpServers": {
    "mcp-timeplus": {  // 服务器名称，客户端内唯一标识
      "command": "uvx", // 启动命令，这里使用 uvx 运行 Python 包
      "args": ["mcp-timeplus"], // 命令参数，指定运行 mcp-timeplus 包
      "env": { // 环境变量配置，传递 Timeplus 和 Kafka 连接信息
        "TIMEPLUS_HOST": "<timeplus-host>",  // Timeplus 主机名
        "TIMEPLUS_PORT": "<timeplus-port>",  // Timeplus 端口号
        "TIMEPLUS_USER": "<timeplus-user>",  // Timeplus 用户名
        "TIMEPLUS_PASSWORD": "<timeplus-password>", // Timeplus 密码
        "TIMEPLUS_SECURE": "false", // 是否启用 HTTPS 连接 (true/false)
        "TIMEPLUS_VERIFY": "true", // 是否验证 SSL 证书 (true/false)
        "TIMEPLUS_READ_ONLY": "false", // 是否只允许只读查询 (true/false)
        "TIMEPLUS_KAFKA_CONFIG": "{\"bootstrap.servers\":\"your_kafka_brokers\", \"sasl.mechanism\":\"SCRAM-SHA-256\",\"sasl.username\":\"your_kafka_user\", \"sasl.password\":\"your_kafka_password\",\"security.protocol\":\"SASL_SSL\",\"enable.ssl.certificate.verification\":\"false\"}" // Kafka 连接配置 (JSON 字符串)
      }
    }
  }
}

请将上述 JSON 配置添加到 Claude Desktop 的 'claude_desktop_config.json' 文件中 (文件路径根据操作系统有所不同，请参考仓库 README.md)。
确保根据您的实际环境修改 '<timeplus-host>', '<timeplus-port>', '<timeplus-user>', '<timeplus-password>' 和 Kafka 相关配置。
配置完成后，重启 Claude Desktop 使配置生效。

基本使用方法

启动 Claude Desktop 或其他 MCP 客户端。
在客户端中连接到 "mcp-timeplus" 服务器 (根据客户端界面操作)。
连接成功后，您可以在客户端的工具栏或菜单中找到 Timeplus MCP Server 提供的工具和 Prompt。
使用 'run_sql' 工具执行 SQL 查询，例如查询数据库列表 'SHOW DATABASES' 或查询表数据 'SELECT * FROM your_table LIMIT 10'。
使用 'list_databases' 和 'list_tables' 工具浏览数据库和表信息。
使用 Kafka 相关工具探索 Kafka 主题或创建 Kafka 数据流。
使用 'generate_sql' Prompt 模板，输入自然语言描述的需求，辅助生成 Timeplus SQL 查询语句。

通过以上步骤，您就可以利用 Timeplus MCP Server 在 LLM 客户端中便捷地访问和操作 Timeplus 数据分析平台。

关键词