Timeplus MCP Server

Timeplus的MCP服务器。

功能

提示

• generate_sql为LLM提供更多关于如何通过SQL查询Timeplus的知识

工具

• run_sql

  • 在您的Timeplus集群上执行SQL查询。
  • 输入：sql（字符串）：要执行的SQL查询。
  • 默认情况下，所有Timeplus查询都使用readonly = 1来确保它们是安全的。如果您想运行DDL或DML查询，可以将环境变量TIMEPLUS_READ_ONLY设置为false。

• list_databases

  • 列出Timeplus集群上的所有数据库。

• list_tables

  • 列出数据库中的所有表。
  • 输入：database（字符串）：数据库名称。

• list_kafka_topics

  • 列出Kafka集群中的所有主题

• explore_kafka_topic

  • 显示Kafka主题中的某些消息
  • 输入：topic（字符串）：主题名称。message_count（整数）：要显示的消息数量，默认为1。

• create_kafka_stream

  • 在Timeplus中设置流式ETL以本地保存Kafka消息
  • 输入：topic（字符串）：主题名称。

• connect_to_apache_iceberg

  • 连接到基于Apache Iceberg的数据库。目前这仅通过Timeplus Enterprise提供，计划不久后为Timeplus Proton提供。
  • 输入：iceberg_db（字符串）：Iceberg数据库名称。aws_account_id（整数）：AWS账户ID（12位）。s3_bucket（字符串）：S3存储桶名称。aws_region（字符串）：AWS区域，默认为"us-west-2"。is_s3_table_bucket（布尔值）：S3存储桶是否为S3表存储桶，默认为False。

配置

首先，确保您已安装uv可执行文件。如果没有，请按照此处的说明进行安装。

1. 打开位于以下位置的Claude桌面配置文件：

   • 在macOS上：~/Library/Application Support/Claude/claude_desktop_config.json
   • 在Windows上：%APPDATA%/Claude/claude_desktop_config.json

2. 添加以下内容：

{
  "mcpServers": {
    "mcp-timeplus": {
      "command": "uvx",
      "args": ["mcp-timeplus"],
      "env": {
        "TIMEPLUS_HOST": "<timeplus-host>",
        "TIMEPLUS_PORT": "<timeplus-port>",
        "TIMEPLUS_USER": "<timeplus-user>",
        "TIMEPLUS_PASSWORD": "<timeplus-password>",
        "TIMEPLUS_SECURE": "false",
        "TIMEPLUS_VERIFY": "true",
        "TIMEPLUS_CONNECT_TIMEOUT": "30",
        "TIMEPLUS_SEND_RECEIVE_TIMEOUT": "30",
        "TIMEPLUS_READ_ONLY": "false",
        "TIMEPLUS_KAFKA_CONFIG": "{\"bootstrap.servers\":\"a.aivencloud.com:28864\", \"sasl.mechanism\":\"SCRAM-SHA-256\",\"sasl.username\":\"avnadmin\", \"sasl.password\":\"thePassword\",\"security.protocol\":\"SASL_SSL\",\"enable.ssl.certificate.verification\":\"false\"}"
      }
    }
  }
}

将环境变量更新为指向您自己的Timeplus服务。

3. 重启Claude桌面以应用更改。

您也可以尝试使用其他MCP客户端（如5ire）来使用此MCP服务器。

开发

1. 在test-services目录中运行docker compose up -d以启动Timeplus Proton服务器。您也可以通过curl https://install.timeplus.com/oss | sh下载它，然后使用./proton server启动。

2. 在存储库根目录中的.env文件中添加以下变量。

TIMEPLUS_HOST=localhost
TIMEPLUS_PORT=8123
TIMEPLUS_USER=default
TIMEPLUS_PASSWORD=
TIMEPLUS_SECURE=false
TIMEPLUS_VERIFY=true
TIMEPLUS_CONNECT_TIMEOUT=30
TIMEPLUS_SEND_RECEIVE_TIMEOUT=30
TIMEPLUS_READ_ONLY=false
TIMEPLUS_KAFKA_CONFIG={"bootstrap.servers":"a.aivencloud.com:28864", "sasl.mechanism":"SCRAM-SHA-256","sasl.username":"avnadmin", "sasl.password":"thePassword","security.protocol":"SASL_SSL","enable.ssl.certificate.verification":"false"}

3. 运行uv sync以安装依赖项。然后执行source .venv/bin/activate。

4. 为方便测试，您可以运行mcp dev mcp_timeplus/mcp_server.py以启动MCP服务器。点击"连接"按钮将UI与MCP服务器连接，然后切换到"工具"选项卡以运行可用工具。

5. 要构建Docker镜像，运行docker build -t mcp_timeplus .。

环境变量

以下环境变量用于配置Timeplus连接：

必填变量

• TIMEPLUS_HOST：您的Timeplus服务器的主机名
• TIMEPLUS_USER：用于身份验证的用户名
• TIMEPLUS_PASSWORD：用于身份验证的密码

可选变量

• TIMEPLUS_PORT：您的Timeplus服务器的端口号
  • 默认：如果启用HTTPS，则为8443；如果禁用，则为8123
  • 通常不需要设置，除非使用非标准端口
• TIMEPLUS_SECURE：启用/禁用HTTPS连接
  • 默认："false"
  • 设置为"true"以进行安全连接
• TIMEPLUS_VERIFY：启用/禁用SSL证书验证
  • 默认："true"
  • 设置为"false"以禁用证书验证（不推荐用于生产环境）
• TIMEPLUS_CONNECT_TIMEOUT：连接超时（秒）
  • 默认："30"
  • 如果您遇到连接超时，请增加此值
• TIMEPLUS_SEND_RECEIVE_TIMEOUT：发送/接收超时（秒）
  • 默认："300"
  • 增加此值以用于长时间运行的查询
• TIMEPLUS_DATABASE：默认使用的数据库
  • 默认：无（使用服务器默认值）
  • 设置此值将自动连接到特定数据库
• TIMEPLUS_READ_ONLY：启用/禁用只读模式
  • 默认："true"
  • 设置为"false"以启用DDL/DML
• TIMEPLUS_KAFKA_CONFIG：用于Kafka配置的JSON字符串。请参考librdkafka配置或使用上述示例作为参考。