Timeplus

You can run a Timeplus MCP Server locally and connect it to MCP clients to execute SQL queries, explore databases and Kafka topics, and set up streaming ETL from Kafka. This guide walks you through using the Timeplus MCP Server, installing it, and configuring your environment so you can interact with Timeplus from MCP-enabled tools.

How to use

Start by ensuring your MCP client can reach the Timeplus MCP Server. The server exposes a set of tools that let you run SQL against Timeplus, list databases and tables, inspect Kafka topics, and set up a streaming pipeline from Kafka into Timeplus. You can enable read-only mode by default to keep queries safe, and you can opt into write capabilities by adjusting environment variables when you’re ready to perform DDL/DML.

How to install

Prerequisites: you need a Unix-like environment with the uv executable installed for running MCP servers via uvx. You also need access to a Timeplus service you want to connect to.

1. Create or edit your MCP configuration to define the Timeplus MCP Server.

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

Additional setup steps

Prepare your Timeplus connection details and place them as environment variables in the MCP configuration. After saving the config, restart your MCP client or Claude Desktop (or equivalent) to apply the changes.

If you are testing with Timeplus Proton or a Timeplus Enterprise instance, ensure your host, port, user, and credentials match what your Timeplus setup requires.

Configuration and notes

Environment variables used to configure the Timeplus connection are grouped into required and optional fields. Required values include the host, user, and password. Optional values control the port, security, certificate verification, timeouts, read-only mode, and Kafka configuration.

The provided configuration uses an explicit MCP server entry named mcp-timeplus. It runs as a local process via uvx, with the Timeplus connection details passed through environment variables.

Tools and capabilities

The Timeplus MCP Server exposes a set of tools you can invoke from your MCP client to interact with Timeplus. These include running SQL queries, listing databases and tables, listing Kafka topics, exploring Kafka topics, creating a Kafka streaming ETL, and connecting to Apache Iceberg databases when available.

Security and troubleshooting

Use TIMEPLUS_READ_ONLY to prevent DDL/DML by default. If you need to perform write operations, set TIMEPLUS_READ_ONLY to false and ensure you understand the implications. If you encounter connection timeouts, increase TIMEPLUS_CONNECT_TIMEOUT and TIMEPLUS_SEND_RECEIVE_TIMEOUT. Confirm that TIMEPLUS_HOST, TIMEPLUS_PORT, TIMEPLUS_USER, and TIMEPLUS_PASSWORD are correct and that the Timeplus service is reachable from the MCP host.

Notes

You can also test this MCP server with other MCP clients that support the standard MCP interface. For development and testing, you can spin up a Timeplus Proton server in a local environment and verify the MCP server connects successfully.

Available tools

run_sql

Execute SQL queries on your Timeplus cluster. By default queries run in read-only mode; set TIMEPLUS_READ_ONLY to false to run DDL/DML.

list_databases

List all databases on your Timeplus cluster.

list_tables

List all tables in a database selected by the input database name.

list_kafka_topics

List all topics in a Kafka cluster.

explore_kafka_topic

Show messages from a Kafka topic. Specify topic and optional message_count to limit results.

create_kafka_stream

Set up a streaming ETL from a Kafka topic to store messages locally in Timeplus.

connect_to_apache_iceberg

Connect to an Apache Iceberg database. Availability may depend on Timeplus edition; parameters include iceberg_db, aws_account_id, s3_bucket, aws_region, and is_s3_table_bucket.