MCP HubMCP Hub
jovezhong

mcp-timeplus

by: jovezhong

mcp timeplus

7created 16/02/2025
Visit
timeplus
monitoring

📌Overview

Purpose: To provide a robust MCP server that facilitates SQL query execution and interaction with Timeplus and Kafka.

Overview: The Timeplus MCP Server is designed to integrate seamlessly with the Timeplus platform, allowing users to effortlessly execute SQL commands and interact with Kafka topics. Its setup requires basic configurations, making it accessible for developers looking to utilize Timeplus for database and streaming analytics.

Key Features:

  • SQL Query Execution: The run_sql tool lets users execute SQL queries on their Timeplus cluster while maintaining safety with default read-only settings.

  • Database and Table Management: Users can easily retrieve information on available databases and tables using list_databases and list_tables tools, enhancing usability and data management efficiency.

  • Kafka Integration: With tools like list_kafka_topics and explore_kafka_topic, users can manage and view Kafka messages, as well as set up streaming ETL solutions using create_kafka_stream.

  • Environment Configuration: The server can be easily configured through environment variables, allowing users to customize connection settings tailored to their specific Timeplus environments.

Timeplus MCP Server

An MCP server for Timeplus.

Features

Prompts

  • generate_sql to provide LLM more knowledge about how to query Timeplus via SQL.

Tools

  • run_sql

    • Execute SQL queries on your Timeplus cluster.
    • Input: sql (string): The SQL query to execute.
    • By default, all queries run with readonly = 1 to ensure safety. To run DDL or DML queries, set the environment variable TIMEPLUS_READ_ONLY to false.

  • list_databases

    • List all databases on your Timeplus cluster.

  • list_tables

    • List all tables in a database.
    • Input: database (string): The name of the database.

  • list_kafka_topics

    • List all topics in a Kafka cluster.

  • explore_kafka_topic

    • Show some messages in the Kafka topic.
    • Input: topic (string): The name of the topic; message_count (int): Number of messages to show, defaults to 1.

  • create_kafka_stream

    • Set up a streaming ETL in Timeplus to save Kafka messages locally.
    • Input: topic (string): The name of the topic.

  • connect_to_apache_iceberg

    • Connect to a database based on Apache Iceberg. Currently available via Timeplus Enterprise; planned for Timeplus Proton soon.
    • Input:
      • iceberg_db (string): Name of the Iceberg database.
      • aws_account_id (int): AWS account ID (12 digits).
      • s3_bucket (string): The S3 bucket name.
      • aws_region (string): AWS region, defaults to "us-west-2".
      • is_s3_table_bucket (bool): Whether the S3 bucket is an S3 table bucket, defaults to False.

Configuration

Ensure you have the uv executable installed. If not, install it by following the instructions at https://docs.astral.sh/uv/.

  1. Open the Claude Desktop configuration file:

    • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • On Windows: %APPDATA%/Claude/claude_desktop_config.json

  2. Add the following:

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

Update environment variables to point to your own Timeplus service.

  1. Restart Claude Desktop to apply changes.

You can also try this MCP server with other MCP clients, such as 5ire.

Development

  1. In the test-services directory, run docker compose up -d to start a Timeplus Proton server. Alternatively, download via:
curl https://install.timeplus.com/oss | sh

then start with:

./proton server
  1. Create a .env file in the root of the repository with:
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. Run uv sync to install dependencies, then activate the virtual environment:
source .venv/bin/activate
  1. To test easily, run:
mcp dev mcp_timeplus/mcp_server.py

Click "Connect" to link the UI with the MCP server, then use the "Tools" tab.

  1. To build the Docker image, run:
docker build -t mcp_timeplus .

Environment Variables

Required Variables

  • TIMEPLUS_HOST: Hostname of your Timeplus server
  • TIMEPLUS_USER: Username for authentication
  • TIMEPLUS_PASSWORD: Password for authentication

Optional Variables

  • TIMEPLUS_PORT: Port number
    • Default: 8443 (HTTPS enabled), 8123 (disabled)
  • TIMEPLUS_SECURE: Enable/disable HTTPS
    • Default: "false"
  • TIMEPLUS_VERIFY: Enable/disable SSL certificate verification
    • Default: "true"
  • TIMEPLUS_CONNECT_TIMEOUT: Connection timeout in seconds
    • Default: "30"
  • TIMEPLUS_SEND_RECEIVE_TIMEOUT: Send/receive timeout in seconds
    • Default: "300"
  • TIMEPLUS_DATABASE: Default database to use
    • None by default
  • TIMEPLUS_READ_ONLY: Enable/disable read-only mode
    • Default: "true"
  • TIMEPLUS_KAFKA_CONFIG: JSON string for Kafka configuration. See librdkafka configuration for details.