by apache
An MCP server for Apache IoTDB, enabling database interaction and business intelligence capabilities for time-series data.
The Apache IoTDB MCP Server is a Model Context Protocol server that allows users to interact with the Apache IoTDB time-series database. It provides tools to query metadata and data, as well as export data in various formats.
To use the server, you need to configure the IOTDB_SQL_DIALECT
to either tree
or table
. The server exposes different tools based on the selected dialect. You can then use these tools to execute SQL queries for metadata, data selection, and data export.
SHOW DATABASES
, COUNT TIMESERIES
).SUM
, AVG
, MAX_VALUE
).Currently, there is no FAQ section in the project's README.
English | 中文
A Model Context Protocol (MCP) server implementation that provides database interaction and business intelligence capabilities through IoTDB. This server enables running SQL queries and interacting with IoTDB using different SQL dialects (Tree Model and Table Model).
The server doesn't expose any resources.
The server doesn't provide any prompts.
The server offers different tools for IoTDB Tree Model and Table Model. You can choose between them by setting the "IOTDB_SQL_DIALECT" configuration to either "tree" or "table".
metadata_query
query_sql
(string): The SHOW/COUNT SQL query to executeselect_query
query_sql
(string): The SELECT SQL query to execute (using TREE dialect, time using ISO 8601 format, e.g. 2017-11-01T00:08:00.000)export_query
query_sql
(string): The SQL query to execute (using TREE dialect)format
(string): Export format, either "csv" or "excel" (default: "csv")filename
(string): Optional filename for the exported file. If not provided, a unique filename will be generated.Query Tools
read_query
query_sql
(string): The SELECT SQL query to execute (using TABLE dialect, time using ISO 8601 format, e.g. 2017-11-01T00:08:00.000)Schema Tools
list_tables
describe_table
table_name
(string): Name of table to describeexport_table_query
query_sql
(string): The SQL query to execute (using TABLE dialect)format
(string): Export format, either "csv" or "excel" (default: "csv")filename
(string): Optional filename for the exported file. If not provided, a unique filename will be generated.IoTDB MCP Server supports the following configuration options, which can be set via environment variables or command-line arguments:
Option | Environment Variable | Default Value | Description |
---|---|---|---|
--host | IOTDB_HOST | 127.0.0.1 | IoTDB host address |
--port | IOTDB_PORT | 6667 | IoTDB port |
--user | IOTDB_USER | root | IoTDB username |
--password | IOTDB_PASSWORD | root | IoTDB password |
--database | IOTDB_DATABASE | test | IoTDB database name |
--sql-dialect | IOTDB_SQL_DIALECT | table | SQL dialect: tree or table |
--export-path | IOTDB_EXPORT_PATH | /tmp | Path for exporting query results |
IoTDB MCP Server includes the following performance optimization features:
uv
package manager# Clone the repository
git clone https://github.com/apache/iotdb-mcp-server.git
cd iotdb-mcp-server
# Create virtual environment
uv venv
source venv/bin/activate # or `venv\Scripts\activate` on Windows
# Install development dependencies
uv sync
Configure the MCP server in Claude Desktop's configuration file:
Location: ~/Library/Application Support/Claude/claude_desktop_config.json
Location: %APPDATA%/Claude/claude_desktop_config.json
You may need to put the full path to the uv executable in the command field. You can get this by running which uv
on MacOS/Linux or where uv
on Windows.
Add the following configuration to Claude Desktop's configuration file:
{
"mcpServers": {
"iotdb": {
"command": "uv",
"args": [
"--directory",
"/Users/your_username/iotdb-mcp-server/src/iotdb_mcp_server",
"run",
"server.py"
],
"env": {
"IOTDB_HOST": "127.0.0.1",
"IOTDB_PORT": "6667",
"IOTDB_USER": "root",
"IOTDB_PASSWORD": "root",
"IOTDB_DATABASE": "test",
"IOTDB_SQL_DIALECT": "table",
"IOTDB_EXPORT_PATH": "/path/to/export/folder"
}
}
}
}
Note: Make sure to replace the
--directory
parameter's path with your actual repository clone path.
IoTDB MCP Server includes comprehensive error handling and logging capabilities:
You can build a container image for the IoTDB MCP Server using the Dockerfile
in the project root:
# Build Docker image
docker build -t iotdb-mcp-server .
# Run container
docker run -e IOTDB_HOST=<your-iotdb-host> -e IOTDB_PORT=<your-iotdb-port> -e IOTDB_USER=<your-iotdb-user> -e IOTDB_PASSWORD=<your-iotdb-password> iotdb-mcp-server
Please log in to share your review and rating for this MCP.
Discover more MCP servers with similar functionality and use cases
by googleapis
Provides a configurable MCP server that abstracts connection pooling, authentication, observability, and tool management to accelerate development of database‑backed AI tools.
by bytebase
DBHub is a universal database gateway that implements the Model Context Protocol (MCP) server interface, enabling MCP-compatible clients to interact with various databases.
by neo4j-contrib
Provides Model Context Protocol servers for interacting with Neo4j databases, managing Aura instances, and handling personal knowledge graph memory through natural‑language interfaces.
by mongodb-js
Provides a Model Context Protocol server that connects to MongoDB databases and Atlas clusters, exposing a rich set of tools for querying, managing, and administering data and infrastructure.
by benborla
A Model Context Protocol (MCP) server that provides read-only access to MySQL databases, enabling Large Language Models (LLMs) to inspect database schemas and execute read-only queries.
by ClickHouse
Provides tools that let AI assistants run read‑only SQL queries against ClickHouse clusters or the embedded chDB engine, plus a health‑check endpoint for service monitoring.
by elastic
Provides direct, natural‑language access to Elasticsearch indices via the Model Context Protocol, allowing AI agents to query and explore data without writing DSL.
by motherduckdb
Provides an MCP server that enables SQL analytics on DuckDB and MotherDuck databases, allowing AI assistants and IDEs to execute queries via a unified interface.
by redis
Provides a natural language interface for agentic applications to manage and search data in Redis efficiently.