mcp-timeplus
This server allows users to interact with a Timeplus cluster and Kafka streams via SQL queries and database operations. Key capabilities include:
Execute SQL Queries: Run SQL queries on the Timeplus cluster
List Databases: Retrieve all databases available on the Timeplus cluster
List Tables: Enumerate tables in a specified database
List Kafka Topics: Display topics in a connected Kafka cluster
Explore Kafka Topic: View messages from a Kafka topic
Create Kafka Stream: Set up streaming ETL in Timeplus to save Kafka messages locally
Connect to Apache Iceberg: Establish connection to Apache Iceberg database (Timeplus Enterprise only)
The MCP server is available as a package on PyPI, allowing users to install it using package managers.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-timeplusshow me the latest 5 messages from the 'user_activity' Kafka topic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Timeplus MCP Server
An MCP server for Timeplus.
Features
Prompts
generate_sqlto give LLM more knowledge about how to query Timeplus via SQL
Tools
run_sqlExecute SQL queries on your Timeplus cluster.
Input:
sql(string): The SQL query to execute.By default, all Timeplus queries are run with
readonly = 1to ensure they are safe. If you want to run DDL or DML queries, you can set the environment variableTIMEPLUS_READ_ONLYtofalse.
list_databasesList all databases on your Timeplus cluster.
list_tablesList all tables in a database.
Input:
database(string): The name of the database.
list_kafka_topicsList all topics in a Kafka cluster
explore_kafka_topicShow some messages in the Kafka topic
Input:
topic(string): The name of the topic.message_count(int): The number of messages to show, default to 1.
create_kafka_streamSetup a streaming ETL in Timeplus to save the Kafka messages locally
Input:
topic(string): The name of the topic.
connect_to_apache_icebergConnect 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.
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.
Related MCP server: Kafka MCP Server
Configuration
First, ensure you have the uv executable installed. If not, you can install it by following the instructions here.
Open the Claude Desktop configuration file located at:
On macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonOn Windows:
%APPDATA%/Claude/claude_desktop_config.json
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 the environment variables to point to your own Timeplus service.
Restart Claude Desktop to apply the changes.
You can also try this MCP server with other MCP clients, such as 5ire.
Development
In
test-servicesdirectory rundocker compose up -dto start a Timeplus Proton server. You can also download it viacurl https://install.timeplus.com/oss | sh, then start with./proton server.Add the following variables to a
.envfile in the root of the repository.
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"}Run
uv syncto install the dependencies. Then dosource .venv/bin/activate.For easy testing, you can run
mcp dev mcp_timeplus/mcp_server.pyto 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.To build the Docker image, run
docker build -t mcp_timeplus ..
Environment Variables
The following environment variables are used to configure the Timeplus connection:
Required Variables
TIMEPLUS_HOST: The hostname of your Timeplus serverTIMEPLUS_USER: The username for authenticationTIMEPLUS_PASSWORD: The password for authentication
Optional Variables
TIMEPLUS_PORT: The port number of your Timeplus serverDefault:
8443if HTTPS is enabled,8123if disabledUsually doesn't need to be set unless using a non-standard port
TIMEPLUS_SECURE: Enable/disable HTTPS connectionDefault:
"false"Set to
"true"for secure connections
TIMEPLUS_VERIFY: Enable/disable SSL certificate verificationDefault:
"true"Set to
"false"to disable certificate verification (not recommended for production)
TIMEPLUS_CONNECT_TIMEOUT: Connection timeout in secondsDefault:
"30"Increase this value if you experience connection timeouts
TIMEPLUS_SEND_RECEIVE_TIMEOUT: Send/receive timeout in secondsDefault:
"300"Increase this value for long-running queries
TIMEPLUS_DATABASE: Default database to useDefault: None (uses server default)
Set this to automatically connect to a specific database
TIMEPLUS_READ_ONLY: Enable/disable read-only modeDefault:
"true"Set to
"false"to enable DDL/DML
TIMEPLUS_KAFKA_CONFIG: A JSON string for the Kafka configuration. Please refer to librdkafka configuration or take the above example as a reference.
Available Tools
7 toolsconnect_to_apache_icebergC
Create a Timeplus database in iceberg type to connect to Iceberg
| Name | Required | Description | Default |
|---|---|---|---|
| iceberg_db | Yes | ||
| aws_account_id | Yes | ||
| s3_bucket | Yes | ||
| aws_region | No | us-west-2 | |
| is_s3_table_bucket | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose side effects, idempotency, or required permissions. Simply stating 'create' without behavioral context is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, making it concise, but it lacks structure or any additional useful details. It is under-specified rather than effectively concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 0% schema coverage, no annotations, and no output schema, the description fails to provide enough context for correct invocation. Critical details about parameters and behavior are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no information about any of the 5 parameters. The agent must rely solely on parameter names, which are ambiguous (e.g., 'aws_account_id' may not be self-explanatory).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create a Timeplus database' and the target 'to connect to Iceberg'. The verb and resource are specific, and it differentiates from sibling tools focused on Kafka or general SQL.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs. alternatives, no prerequisites or conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
create_kafka_streamD
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
explore_kafka_topicD
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | ||
| message_count | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_databasesA
List available Timeplus databases
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description should disclose behavioral traits. It only says 'list', implying read-only, but lacks detail on auth requirements or side effects. For a trivial tool this is marginal, but more context could be added.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Every word earns its place. Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, no output schema), the description is largely complete. However, it does not specify the return format, which might be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100% (with no params). No additional parameter information is needed, so the description is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and resource (Timeplus databases), effectively distinguishing it from siblings like list_tables which lists tables.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives, but the simple nature of the tool implies usage for listing databases. The sibling tools cover different operations, so context is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_kafka_topicsD
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Tool has no description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool has no description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_tablesC
List available tables/streams in the given database
| Name | Required | Description | Default |
|---|---|---|---|
| database | No | default | |
| like | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the basic action but provides no details on side effects, read-only nature, permissions needed, or performance implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the main action. It could be slightly improved by adding parameter details without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description lacks essential context: no output schema, no explanation of the 'like' parameter, and no mention of error handling or return format. An agent may struggle to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no meaning to the parameters (database, like). The 'like' parameter's purpose (filtering pattern) is not explained, leaving the agent to guess.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', resource 'tables/streams', and scope 'in the given database', which distinguishes it from sibling tools like list_databases or list_kafka_topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, when not to use it, or any prerequisites. The description lacks context for appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
run_sqlC
Run a query in a Timeplus database
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. However, it only states 'Run a query' without indicating potential side effects, required permissions, query limits, or whether results are returned. This is insufficient for a tool that executes arbitrary SQL.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which might seem concise, but it is under-specified. It lacks critical information needed for proper tool usage, making it insufficient rather than appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of executing SQL queries, the absence of output schema, and no annotations, the description is woefully incomplete. It does not explain return values, error handling, or whether the query can be any valid SQL statement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single required parameter 'query' with no description, and the schema description coverage is 0%. The description adds minimal meaning beyond 'run a query', failing to explain what type of SQL is supported, syntax constraints, or how to specify parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Run a query in a Timeplus database' clearly specifies the action (run) and the resource (query in a Timeplus database). It effectively distinguishes this tool from sibling tools like connect_to_apache_iceberg or list_tables, as it is the only one focused on executing SQL queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For example, it does not clarify whether it supports read-only queries or modifications, nor does it mention any prerequisites or restrictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
7 tool updates
- First observed
connect_to_apache_iceberg - First observed
create_kafka_stream - First observed
explore_kafka_topic - First observed
list_databases - First observed
list_kafka_topics - First observed
list_tables - First observed
run_sql
TDQS
Most tools have distinct purposes, such as list_databases, list_tables, and run_sql, which clearly target different operations. However, create_kafka_stream and explore_kafka_topic could be slightly ambiguous if an agent needs to understand the exact boundary between creating and exploring Kafka topics, but descriptions likely clarify this.
The tools follow a consistent verb_noun pattern, like list_databases and run_sql, with clear and readable names. There is a minor deviation with connect_to_apache_iceberg, which uses a longer, more specific name, but overall the naming is mostly consistent and predictable.
With 7 tools, the count is well-scoped for a Timeplus server, covering essential operations like listing resources, creating streams, and running queries. Each tool appears to earn its place without feeling too thin or overloaded, fitting typical server purposes.
The tool set covers key operations such as listing databases/tables and running SQL, but there are notable gaps in CRUD lifecycle coverage. For example, there are no tools for updating or deleting databases, streams, or tables, which could limit agent workflows in managing Timeplus resources.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu
- toolsOAuthcom.streamkap
Streamkap CLI & MCP server - manage CDC pipelines, sources, destinations, and transforms
A collaborative substrate over your data: vector, knowledge graph, SQL, geospatial, streaming.
Related MCP Servers
AlicenseAqualityAmaintenanceClickHouse database integration with schema inspection and query capabilities3866Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables AI models to publish and consume messages from Apache Kafka topics through a standardized interface, making it easy to integrate Kafka messaging with LLM and agent applications.17Apache 2.0
- FlicenseAqualityNot gradedmaintenanceEnables unified access to both structured databases (PostgreSQL, MySQL, SQLite, etc.) and unstructured object storage (AWS S3, Alibaba OSS, Huawei OBS, etc.) through a single interface.7-
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage and monitor Apache Kafka clusters through natural language, providing real-time operations, health monitoring, consumer lag analysis, and temporal trend detection for intelligent cluster management.-
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/timeplus-io/mcp-timeplus'
If you have feedback or need assistance with the MCP directory API, please join our Discord server