Timeplus MCP Server

Timeplus MCP Server

Timeplus 的 MCP 服务。

功能

提示词

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

工具

• run_sql

  • 在你的 Timeplus 集群上执行 SQL 查询。
  • 输入：sql（string）：要执行的 SQL 查询。
  • 默认情况下，所有 Timeplus 查询都以 readonly = 1 模式运行，以确保安全。如果要运行 DDL 或 DML 查询，可以将环境变量 TIMEPLUS_READ_ONLY 设置为 false。

• list_databases

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

• list_tables

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

• list_kafka_topics

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

• explore_kafka_topic

  • 显示 Kafka 主题中的一些消息
  • 输入：topic（string）：主题名称。message_count（int）：要显示的消息数，默认为 1。

• create_kafka_stream

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

• connect_to_apache_iceberg

  • 连接到基于 Apache Iceberg 的数据库。目前，此功能仅适用于 Timeplus Enterprise，计划很快在 Timeplus Proton 中提供。
  • 输入：iceberg_db（string）：Iceberg 数据库名称。aws_account_id（int）：AWS 账号 ID（12 位）。s3_bucket（string）：S3 存储桶名称。aws_region（string）：AWS 区域，默认为 "us-west-2"。is_s3_table_bucket（bool）：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 服务。

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

你也可以使用其他 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 服务。点击“Connect”按钮，将 UI 连接到 MCP 服务，然后切换到“Tools”选项卡运行可用工具。

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 配置，或参考上面的示例。