Timeplus MCP 服务器

用于 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 Desktop 配置文件：

   • 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 服务。

1. 重启 Claude Desktop 以应用更改。

您还可以尝试使用其他 MCP 客户端来测试此 MCP 服务器，例如 5ire。

开发

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"}

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

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

3. 要构建 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 配置 或以上示例作为参考。