Timeplus MCP Server

1# Timeplus MCP Server
2[![PyPI - Version](https://img.shields.io/pypi/v/mcp-timeplus)](https://pypi.org/project/mcp-timeplus)
3 
4An MCP server for Timeplus.
5 
6<a href="https://glama.ai/mcp/servers/9aleefsq9s"><img width="380" height="200" src="https://glama.ai/mcp/servers/9aleefsq9s/badge" alt="mcp-timeplus MCP server" /></a>
7 
8## Features
9 
10### Prompts
11 
12* `generate_sql` to give LLM more knowledge about how to query Timeplus via SQL
13 
14### Tools
15 
16* `run_sql`
17  - Execute SQL queries on your Timeplus cluster.
18  - Input: `sql` (string): The SQL query to execute.
19  - By default, all Timeplus queries are run with `readonly = 1` to ensure they are safe. If you want to run DDL or DML queries, you can set the environment variable `TIMEPLUS_READ_ONLY` to `false`.
20 
21* `list_databases`
22  - List all databases on your Timeplus cluster.
23 
24* `list_tables`
25  - List all tables in a database.
26  - Input: `database` (string): The name of the database.
27 
28* `list_kafka_topics`
29  - List all topics in a Kafka cluster
30 
31* `explore_kafka_topic`
32  - Show some messages in the Kafka topic
33  - Input: `topic` (string): The name of the topic. `message_count` (int): The number of messages to show, default to 1.
34 
35* `create_kafka_stream`
36  - Setup a streaming ETL in Timeplus to save the Kafka messages locally
37  - Input: `topic` (string): The name of the topic.
38 
39* `connect_to_apache_iceberg`
40  - Connect to a database based on Apache Iceberg. Currently this is only available via Timeplus Enterprise and it's planned to make it available for Timeplus Proton soon.
41  - Input: `iceberg_db` (string): The name of the Iceberg database. `aws_account_id` (int): The AWS account ID (12 digits). `s3_bucket` (string): The S3 bucket name. `aws_region` (string): The AWS region, default to "us-west-2". `is_s3_table_bucket` (bool): Whether the S3 bucket is a S3 table bucket, default to False.
42 
43## Configuration
44 
45First, ensure you have the `uv` executable installed. If not, you can install it by following the instructions [here](https://docs.astral.sh/uv/).
46 
471. Open the Claude Desktop configuration file located at:
48   - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
49   - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
50 
512. Add the following:
52 
53```json
54{
55  "mcpServers": {
56    "mcp-timeplus": {
57      "command": "uvx",
58      "args": ["mcp-timeplus"],
59      "env": {
60        "TIMEPLUS_HOST": "<timeplus-host>",
61        "TIMEPLUS_PORT": "<timeplus-port>",
62        "TIMEPLUS_USER": "<timeplus-user>",
63        "TIMEPLUS_PASSWORD": "<timeplus-password>",
64        "TIMEPLUS_SECURE": "false",
65        "TIMEPLUS_VERIFY": "true",
66        "TIMEPLUS_CONNECT_TIMEOUT": "30",
67        "TIMEPLUS_SEND_RECEIVE_TIMEOUT": "30",
68        "TIMEPLUS_READ_ONLY": "false",
69        "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\"}"
70      }
71    }
72  }
73}
74```
75 
76Update the environment variables to point to your own Timeplus service.
77 
783. Restart Claude Desktop to apply the changes.
79 
80You can also try this MCP server with other MCP clients, such as [5ire](https://github.com/nanbingxyz/5ire).
81 
82## Development
83 
841. In `test-services` directory run `docker compose up -d` to start a Timeplus Proton server. You can also download it via `curl https://install.timeplus.com/oss | sh`, then start with `./proton server`.
85 
862. Add the following variables to a `.env` file in the root of the repository.
87 
88```
89TIMEPLUS_HOST=localhost
90TIMEPLUS_PORT=8123
91TIMEPLUS_USER=default
92TIMEPLUS_PASSWORD=
93TIMEPLUS_SECURE=false
94TIMEPLUS_VERIFY=true
95TIMEPLUS_CONNECT_TIMEOUT=30
96TIMEPLUS_SEND_RECEIVE_TIMEOUT=30
97TIMEPLUS_READ_ONLY=false
98TIMEPLUS_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"}
99```
100 
1013. Run `uv sync` to install the dependencies. Then do `source .venv/bin/activate`.
102 
1034. For easy testing, you can run `mcp dev mcp_timeplus/mcp_server.py` to start the MCP server. Click the "Connect" button to connect the UI with the MCP server, then switch to the "Tools" tab to run the available tools.
104 
1055. To build the Docker image, run `docker build -t mcp_timeplus .`.
106 
107### Environment Variables
108 
109The following environment variables are used to configure the Timeplus connection:
110 
111#### Required Variables
112* `TIMEPLUS_HOST`: The hostname of your Timeplus server
113* `TIMEPLUS_USER`: The username for authentication
114* `TIMEPLUS_PASSWORD`: The password for authentication
115 
116#### Optional Variables
117* `TIMEPLUS_PORT`: The port number of your Timeplus server
118  - Default: `8443` if HTTPS is enabled, `8123` if disabled
119  - Usually doesn't need to be set unless using a non-standard port
120* `TIMEPLUS_SECURE`: Enable/disable HTTPS connection
121  - Default: `"false"`
122  - Set to `"true"` for secure connections
123* `TIMEPLUS_VERIFY`: Enable/disable SSL certificate verification
124  - Default: `"true"`
125  - Set to `"false"` to disable certificate verification (not recommended for production)
126* `TIMEPLUS_CONNECT_TIMEOUT`: Connection timeout in seconds
127  - Default: `"30"`
128  - Increase this value if you experience connection timeouts
129* `TIMEPLUS_SEND_RECEIVE_TIMEOUT`: Send/receive timeout in seconds
130  - Default: `"300"`
131  - Increase this value for long-running queries
132* `TIMEPLUS_DATABASE`: Default database to use
133  - Default: None (uses server default)
134  - Set this to automatically connect to a specific database
135* `TIMEPLUS_READ_ONLY`: Enable/disable read-only mode
136  - Default: `"true"`
137  - Set to `"false"` to enable DDL/DML
138* `TIMEPLUS_KAFKA_CONFIG`: A JSON string for the Kafka configuration. Please refer to [librdkafka configuration](https://github.com/confluentinc/librdkafka/blob/master/CONFIGURATION.md) or take the above example as a reference.
139