home / mcp / timeplus mcp server

Timeplus MCP Server

Provides a Timeplus MCP server to run SQL, list databases, and interact with Kafka topics.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jovezhong-mcp-timeplus": {
      "command": "uvx",
      "args": [
        "mcp-timeplus"
      ],
      "env": {
        "TIMEPLUS_HOST": "<timeplus-host>",
        "TIMEPLUS_PORT": "<timeplus-port>",
        "TIMEPLUS_USER": "<timeplus-user>",
        "TIMEPLUS_SECURE": "false",
        "TIMEPLUS_VERIFY": "true",
        "TIMEPLUS_PASSWORD": "<timeplus-password>",
        "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_CONNECT_TIMEOUT": "30",
        "TIMEPLUS_SEND_RECEIVE_TIMEOUT": "30"
      }
    }
  }
}

You can run a Timeplus MCP Server locally to connect Claude or other MCP clients to your Timeplus cluster. This server exposes a set of tools that let you run SQL queries, explore databases, and interact with Kafka topics, all through an MCP interface. It also provides configuration to securely connect to Timeplus and control read-only behavior for safe operations.

How to use

Install and run the MCP server, then connect your MCP client to it. Use the available tools to perform common data operations against your Timeplus cluster. By default, queries run in read-only mode to prevent unintended changes. You can toggle read-only to enable DDL/DML when you need to manage schemas or modify data.

How to install

Prerequisites: you need Python installed for dependencies and the uv runtime for MCP execution. You will also need access to your Timeplus instance and the required credentials.

1) Install and run the MCP server locally using the provided runtime configuration snippet.

2) Start the MCP server with the runtime command and environment variables described in the configuration snippet below.

Configuration

You configure the MCP server by running a client that supports MCP and pointing it to the local runtime with the following settings.

The standard configuration uses uvx to launch the MCP server and sets Timeplus connection details through environment variables.

Notes and tips

- Timeseries and SQL interactions are routed through Timeplus, with read-only mode enabled by default for safety.

- If you need to run DDL or DML operations, set TIMEPLUS_READ_ONLY to "false" in the environment before starting the MCP server.

- The Kafka configuration is provided as a JSON string in TIMEPLUS_KAFKA_CONFIG to connect to your Kafka cluster.

Tools you can use

The MCP server exposes the following tools to interact with Timeplus and related components.

Available tools

run_sql

Execute SQL queries on your Timeplus cluster. By default, queries run with readonly=1 for safety. 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 specified database.

list_kafka_topics

List all topics in the connected Kafka cluster.

explore_kafka_topic

Show messages from a Kafka topic. You can specify the number of messages to display.

create_kafka_stream

Set up a streaming ETL pipeline to save Kafka messages locally.

connect_to_apache_iceberg

Connect to an Apache Iceberg database. Available via Timeplus Enterprise and planned for Proton.