Timeplus MCP Server Abstraction

An operational interface layer (MCP server) designed specifically for the Timeplus environment.

Core Functionality

LLM Augmentation

• generate_sql: Augments Large Language Models with detailed knowledge necessary for constructing effective SQL queries targeting the Timeplus engine.

Data Manipulation & Query Tools

• run_sql
• Facilitates the execution of arbitrary SQL statements against your Timeplus cluster.
• Parameter: sql (string): The specific SQL command intended for execution.

• Default Safety: All database operations are inherently set to read-only (readonly = 1). To permit schema modifications (DDL) or data manipulations (DML), the system environment flag TIMEPLUS_READ_ONLY must be explicitly disabled (false).

• list_databases

• Retrieves a catalog of all accessible databases within the connected Timeplus instance.

• list_tables

• Enumerates all available tables residing within a specified database.

• Parameter: database (string): The identifier of the target database.

• list_kafka_topics

• Provides a roster of all topic names managed by the integrated Kafka messaging system.

• explore_kafka_topic

• Samples and displays message content from a designated Kafka stream.
• Parameter: topic (string): The Kafka topic name to inspect.

• Parameter: message_count (int): The maximum quantity of messages to retrieve (defaults to 1).

• create_kafka_stream

• Establishes a persistent streaming ETL pipeline within Timeplus to persistently archive incoming Kafka messages locally.

• Parameter: topic (string): The source Kafka topic for streaming ingestion.

• connect_to_apache_iceberg

• Establishes a data connection path to a repository utilizing the Apache Iceberg specification. Note: Currently prioritized for Timeplus Enterprise deployments, with eventual migration planned for Timeplus Proton.
• Parameter: iceberg_db (string): The name assigned to the Iceberg database context.
• Parameter: aws_account_id (int): The requisite 12-digit AWS account identifier.
• Parameter: s3_bucket (string): The name of the underlying Amazon S3 storage container.
• Parameter: aws_region (string): The geographical AWS service zone (defaults to "us-west-2").
• Parameter: is_s3_table_bucket (bool): Indicator if the provided S3 location holds primary table data (defaults to False).

Initialization Requirements

Ensure the uv package manager utility is installed. Installation instructions can be found here.

1. Locate and open the configuration blueprint for Claude Desktop:
2. macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows Path: %APPDATA%/Claude/claude_desktop_config.json

4. Integrate the subsequent JSON stanza into the file:

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

Substitute the bracketed placeholders with your specific Timeplus service credentials.

1. Reinitialize Claude Desktop for the modifications to take effect.

This server abstraction is also interoperable with alternative MCP clients, such as 5ire.

Local Development Setup

1. In the test-services directory, execute docker compose up -d to spin up a local Timeplus Proton instance. Alternatively, manual deployment is possible via curl https://install.timeplus.com/oss | sh, followed by launching with ./proton server.

2. Define necessary runtime parameters by creating a .env file in the repository root:

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. Install dependencies using uv sync. Activate the virtual environment with source .venv/bin/activate.

2. For rapid testing cycles, invoke the server via mcp dev mcp_timeplus/mcp_server.py. Connect the UI interface, then navigate to the 'Tools' pane to exercise the capabilities.

3. Create the Docker deployment image using the command: docker build -t mcp_timeplus ..

Configuration Parameters

The Timeplus connection is governed by the following environment variables:

Mandatory Settings

• TIMEPLUS_HOST: The network address (hostname) of the Timeplus service instance.
• TIMEPLUS_USER: The required credential for client authentication.
• TIMEPLUS_PASSWORD: The secret key corresponding to the user.

Optional Tuning Parameters

• TIMEPLUS_PORT: Specifies the communication endpoint port.
• Default Behavior: 8443 if TLS/HTTPS is active; 8123 otherwise.
• Typically only modified for non-standard port configurations.
• TIMEPLUS_SECURE: Flag to enable or disable encrypted (HTTPS) communication.
• Default: "false".
• Set to "true" to enforce secure transport.
• TIMEPLUS_VERIFY: Controls SSL certificate chain validation.
• Default: "true".
• Setting to "false" bypasses verification (caution advised in production environments).
• TIMEPLUS_CONNECT_TIMEOUT: Duration, in seconds, permitted for establishing a connection.
• Default: "30".
• Adjust upwards if connection establishment frequently times out.
• TIMEPLUS_SEND_RECEIVE_TIMEOUT: Maximum time, in seconds, allowed for query operation completion (send/receive cycle).
• Default: "300".
• Increase this for exceptionally long-running analytical operations.
• TIMEPLUS_DATABASE: The preselected default database for subsequent operations.
• Default: None (defaults to the server's primary context).
• Use this to mandate a starting database upon connection.
• TIMEPLUS_READ_ONLY: Dictates whether modifications to data or schema are permitted.
• Default: "true".
• Set to "false" to unlock DDL/DML capabilities.
• TIMEPLUS_KAFKA_CONFIG: A serialized JSON string supplying parameters for Kafka client connectivity. Consult the librdkafka configuration guide or use the provided example as a template.